com.autonomy.aci
Class AciResponse

java.lang.Object
  extended bycom.autonomy.aci.AciResponse

public class AciResponse
extends java.lang.Object

AciResponse objects are used as the nodes of a linked-list representation of the XML response from an ACI server. Each AciResponse object then corresponds to an individual tag within the XML and provides access to the tag's name, attributes and value (defined as the CDATA contained within that tag). The AciResponse class also provides methods for locating specific tags and traversing through the XML structure.

The hierarchical structure of the XML response is preserved by linking the AciResponse objects using parent-child (a tag enclosed within another is considered a child of the enclosing tag) and sibling-sibling (two consecutive tags at the same depth or level in the XML document are siblings) relationships. For instance, within this XML fragment:

  <document>
    <section>
      <tag 1>text</tag 1>
    </section>
    <section>
      <tag 2>text</tag 2>
      <tag 3>text</tag 3>
    </section>
  </document>
 

the <section> tags are children of <document> while <tag 3> is a sibling of <tag 2>. Thus if acirDocument is an AciResponse object representing the <document> tag, the first <section> tag can be accessed using:

  AciResponse acirFirstSection = acirDocument.child();
 
(since the child() method returns the first child or enclosed tag) and the second <section> tag can be accessed with:
  AciResponse acirSecondSection = acirFirstSection.next();
 
and the first tag contained within the second section with:
  AciResponse acirTag2 = acirSecondSection.child();
 
If the name of this last tag is known however, the method findFirstOccurrence(String) can be used to traverse directly to that tag rather than moving atomically through the various relationships:
  AciResponse acirTag2 = acirDocument.findFirstOccurrence("tag 2");
 


Constructor Summary
AciResponse()
          Create an empty AciResponse.
AciResponse(java.lang.String sName)
          Create an code>AciResponse to represent an xml tag with the given name.
AciResponse(java.lang.String sName, java.lang.String sValue)
          Create an code>AciResponse to represent an xml tag with the given name containing the given CDATA.
 
Method Summary
 boolean checkForSuccess()
          Checks whether an ACI server reply object contains a successful response entry.
 AciResponse child()
          Returns the first xml tag contained within this tag if one exists.
 AciResponse findFirstEnclosedOccurrence(java.lang.String sTagName)
          Find the first occurrence of an xml tag with the given name contained within this xml tag.
 AciResponse findFirstOccurrence(java.lang.String sTagName)
          Find the first occurrence of an xml tag with the given name contained within this xml tag or in xml tags following this one.
 java.lang.String getAttribute(java.lang.String sAttribName)
          Returns the value of the attribute with the specified name or an empty string if no attribute with this name is assosciated with this xml tag.
 java.util.Set getAttributeNames()
          Reads the names of all the attributes assosciated with this xml tag.
 java.lang.String getName()
          Returns the name of the xml tag represented by this AciResponse object.
 java.lang.String getTagValue(java.lang.String sTagName)
          Try to read the value of an xml tag (it's CDATA) as a String.
 boolean getTagValue(java.lang.String sTagName, boolean bDefaultValue)
          Try to read the value of an xml tag (it's CDATA) as a boolean.
 double getTagValue(java.lang.String sTagName, double dDefaultValue)
          Try to read the value of an xml tag (it's CDATA) as a double.
 float getTagValue(java.lang.String sTagName, float fDefaultValue)
          Try to read the value of an xml tag (it's CDATA) as an float.
 int getTagValue(java.lang.String sTagName, int nDefaultValue)
          Try to read the value of an xml tag (it's CDATA) as an int.
 long getTagValue(java.lang.String sTagName, long lDefaultValue)
          Try to read the value of an xml tag (it's CDATA) as a long.
 java.lang.String getTagValue(java.lang.String sTagName, java.lang.String sDefaultValue)
          Try to read the value of an xml tag (it's CDATA) as a String.
 java.lang.String getValue()
          Returns the value of the xml tag (that is, the CDATA contained within it) represented by this AciResponse object.
 AciResponse next()
          Returns the next xml tag after this tag if one exists.
 AciResponse next(java.lang.String sTagName)
          Returns the next xml tag after this tag with the given name if one exists.
 java.lang.String toHTMLString()
          Constructs an xml fragment representing the linked list headed by this AciResponse in HTML (for displaying within e.g.
 java.lang.String toString()
          Constructs an xml fragment representing the linked list headed by this AciResponse, detailing all parameters and attributes set on each object in the linked list.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AciResponse

public AciResponse()

Create an empty AciResponse.


AciResponse

public AciResponse(java.lang.String sName)

Create an code>AciResponse to represent an xml tag with the given name.

Parameters:
sName - the name of the xml tag that this object represents.

AciResponse

public AciResponse(java.lang.String sName,
                   java.lang.String sValue)

Create an code>AciResponse to represent an xml tag with the given name containing the given CDATA.

Parameters:
sName - the name of the xml tag that this object represents.
sValue - the CDATA of the xml tag that this object represents.
Method Detail

getName

public java.lang.String getName()

Returns the name of the xml tag represented by this AciResponse object.

Returns:
the name of the xml tag represented by this AciResponse object.

getValue

public java.lang.String getValue()

Returns the value of the xml tag (that is, the CDATA contained within it) represented by this AciResponse object.

Returns:
the value of the xml tag represented by this AciResponse object.

getAttributeNames

public java.util.Set getAttributeNames()

Reads the names of all the attributes assosciated with this xml tag.

Returns:
a Set of String objects containing the names of all the attributes assosciated with this xml tag.

getAttribute

public java.lang.String getAttribute(java.lang.String sAttribName)

Returns the value of the attribute with the specified name or an empty string if no attribute with this name is assosciated with this xml tag.

Parameters:
sAttribName - the name of the attribute.
Returns:
the value of the attribute with the specified name or an empty string if no attribute with this name is assosciated with this xml tag.

child

public AciResponse child()

Returns the first xml tag contained within this tag if one exists.

Returns:
the first xml tag contained within this tag if one exists or null otherwise.

next

public AciResponse next()

Returns the next xml tag after this tag if one exists.

Returns:
the next xml tag after this tag if one exists or null otherwise.

next

public AciResponse next(java.lang.String sTagName)

Returns the next xml tag after this tag with the given name if one exists. Useful for accessing multiple tags with the same name, say 'autn:hit', when these are mixed in with other tags at the same document level. For example:

  AciResponse response = connection.aciActionExecute(action);
  ...
  AciResponse hit = response.findFirstOccurrence("autn:hit");
  while(hit != null)
  {
    // use 'hit' (read value, read child tags, ...)
    ...
    // move on to next autn:hit tag
    hit = hit.next("autn:hit");
  }
 

Parameters:
sTagName - the name of the tag to find.
Returns:
the next xml tag after this tag with the given name if one exists or null otherwise.

findFirstOccurrence

public AciResponse findFirstOccurrence(java.lang.String sTagName)

Find the first occurrence of an xml tag with the given name contained within this xml tag or in xml tags following this one.

Parameters:
sTagName - the name of the xml tag to find.
Returns:
the AciResponse representing the first occurrence of the xml tag with the given name or null if non is found.

findFirstEnclosedOccurrence

public AciResponse findFirstEnclosedOccurrence(java.lang.String sTagName)

Find the first occurrence of an xml tag with the given name contained within this xml tag.

Parameters:
sTagName - the name of the xml tag to find.
Returns:
the AciResponse representing the first occurrence of the xml tag with the given name or null if non is found.

checkForSuccess

public boolean checkForSuccess()

Checks whether an ACI server reply object contains a successful response entry.

Returns:
true if this xml contains a 'response' xml tag with value "SUCCESS", false otherwise.

getTagValue

public java.lang.String getTagValue(java.lang.String sTagName,
                                    java.lang.String sDefaultValue)

Try to read the value of an xml tag (it's CDATA) as a String. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
sDefaultValue - the value to return if the tag does not exist or has no value.
Returns:
the value as read from the specified tag or the default value given if no corresponding tag could be found or this tag did not have a value.

getTagValue

public java.lang.String getTagValue(java.lang.String sTagName)

Try to read the value of an xml tag (it's CDATA) as a String. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
Returns:
the value as read from the specified tag or null if no corresponding tag could be found or this tag did not have a value.

getTagValue

public int getTagValue(java.lang.String sTagName,
                       int nDefaultValue)

Try to read the value of an xml tag (it's CDATA) as an int. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
nDefaultValue - the value to return if the tag does not exist or has no value.
Returns:
the value as read from the specified tag or the default value given if no corresponding tag could be found or this tag did not have a value.

getTagValue

public long getTagValue(java.lang.String sTagName,
                        long lDefaultValue)

Try to read the value of an xml tag (it's CDATA) as a long. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
lDefaultValue - the value to return if the tag does not exist or has no value.
Returns:
the value as read from the specified tag or the default value given if no corresponding tag could be found or this tag did not have a value.

getTagValue

public float getTagValue(java.lang.String sTagName,
                         float fDefaultValue)

Try to read the value of an xml tag (it's CDATA) as an float. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
fDefaultValue - the value to return if the tag does not exist or has no value.
Returns:
the value as read from the specified tag or the default value given if no corresponding tag could be found or this tag did not have a value.

getTagValue

public double getTagValue(java.lang.String sTagName,
                          double dDefaultValue)

Try to read the value of an xml tag (it's CDATA) as a double. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
dDefaultValue - the value to return if the tag does not exist or has no value.
Returns:
the value as read from the specified tag or the default value given if no corresponding tag could be found or this tag did not have a value.

getTagValue

public boolean getTagValue(java.lang.String sTagName,
                           boolean bDefaultValue)

Try to read the value of an xml tag (it's CDATA) as a boolean. Essentially this performs a findFirstOccurrence on this object to try to find the specified tag within this tag's child or sibling sub-branches and then read the value from it.

Parameters:
sTagName - the name of the xml tag whose value should be read.
bDefaultValue - the value to return if the tag does not exist or has no value.
Returns:
the value as read from the specified tag or the default value given if no corresponding tag could be found or this tag did not have a value.

toString

public java.lang.String toString()

Constructs an xml fragment representing the linked list headed by this AciResponse, detailing all parameters and attributes set on each object in the linked list.

Returns:
a String representation of the ACI response.

toHTMLString

public java.lang.String toHTMLString()

Constructs an xml fragment representing the linked list headed by this AciResponse in HTML (for displaying within e.g. a web browser), detailing all parameters and attributes set on each object in the linked list.

Returns:
an HTML version of the ACI response.