Package com.opencloud.slee.resources.cgin.xpath

Supports the use of XPath expressions on CGIN data structures such as operation arguments, results and errors.

See: Description

Class Summary

Class	Description
AbstractArrayIterator<T>	Abstract superclass of all CGIN array iterators.
AbstractFieldsObjectIterator	A NodeIterator for an AbstractFieldsObject.
AbstractFieldsObjectPointer	A NodePointer for an AbstractFieldsObject.
ArrayDataObjectIterator<T>	A NodeIterator for an ArrayDataObject.
ArrayDataObjectPointer<T>	A NodePointer for an ArrayDataObject.
ArrayIterator<T>	A NodeIterator for an array.
ArrayPointer<T>	A NodePointer for an array.
ASN1NullPointer	A NodePointer for an ASN1Null.
BitStringPointer	A NodePointer for a BitString.
BooleanPointer	A NodePointer for a Boolean.
ByteArrayPointer	A NodePointer for a byte[].
BytePointer	A NodePointer for a Byte.
CGINIterator	Abstract superclass of all CGIN NodeIterators.
CGINJXPathContext	Wraps a JXPathContext in such a way that rhino grants the security permissions that it needs.
CGINPointer	Abstract superclass of NodePointers for CGIN data structures.
CGINPointerFactory	Creates NodePointers for CGIN data structures.
CollectionCGINPointer	Abstract superclass of NodePointers for collections.
DoublePointer	A NodePointer for a Double.
EnumIterator<E extends Enum<E>>	A NodeIterator for an enum.
EnumPointer	A NodePointer for an enum.
FloatPointer	A NodePointer for a Float.
IntegerPointer	A NodePointer for an Integer.
LeafCGINPointer	Abstract superclass of NodePointers for leaves.
LongPointer	A NodePointer for a Long.
NamedIntegerIterator	A NodeIterator for a NamedInteger.
NamedIntegerPointer	A NodePointer for a NamedInteger.
ObjectIDPointer	A NodePointer for an ObjectID.
ShortPointer	A NodePointer for a Short.
StringPointer	A NodePointer for a String.
Utils	Static utility methods.

Package com.opencloud.slee.resources.cgin.xpath Description

Supports the use of XPath expressions on CGIN data structures such as operation arguments, results and errors. It is based on Apache's JXPath - see http://commons.apache.org/jxpath - initially version 1.3.

Using cgin-xpath

Here's an example of selecting components from an idpArg.

      OCJXPathContext jXPathContext = OCJXPathContext.newContext(idpArg);
      String xPathQuery = "calledPartyNumber/address";
      String address = (String)jXPathContext.getValue(xPathQuery);
    

• The first line establishes the context against which XPath expressions are evaluated. (OCJXPathContext is a necessary wrapper around JXPathContext.)
• The second line has an XPath expression.
• The third line gets the single value that matches the XPath expression from the context.

The above selection achieves the same effect as the following Java expression.

      idpArg.getCalledPartyNumber().getAddress()
    

One reason for using XPath rather than Java code is that the query expression doesn't need to be known at compile time. Further advantages come from further features of the XPath query language, such as predicates for choosing from alternatives, as illustrated here.

      OCJXPathContext jXPathContext = OCJXPathContext.newContext(requestReportBCSMEventArg);
      String xPathQuery = "bcsmEvents[legID/receivingSideID/encodedValue/intValue=1]/eventTypeBCSM";
      CCEventTypeBCSM eventTypeBCSM = (CCEventTypeBCSM)jXPathContext.getValue(xPathQuery);
    

The components that can be selected from a CGIN data structure depend on the type of structure.

Type of structure	Components
SEQUENCE and CHOICE (AbstractFieldsObjects)	The named fields
array	[indexing] of elements numbered from 1
ArrayDataObject	[indexing] of elements numbered from 1
enum	intValue
NamedInteger	byteValue, shortValue, intValue, longValue, floatValue, doubleValue

All other types (INTEGERs, BIT STRINGs, OCTET STRINGs, etc) are currently regarded as leaves from the cgin-xpath perspective.

The treatment of arrays deserves explanation, as it might surprise. Suppose the context is a CCRequestReportBCSMEventArg whose bcsmEvents array has two elements. jXPathContext.getValue("bcsmEvents[1]") and jXPathContext.getValue("bcsmEvents[2]") work as you'd expect, bearing in mind that indexing is from 1 not 0. But jXPathContext.getValue("bcsmEvents") returns the first element, not the whole array. This behaviour originates in XML, where elements can have multiple occurrences (think books in library, from the traditional example), and there are no arrays as such. The context's getValue() method is just returning the first element that it finds with the right name. To access all the elements that have the same name, such as the elements of a CGIN array, the context provides a different method that returns an iterator.

    Iterator iterator = jXPathContext.iterate("bcsmEvents");
    

Deployment

An SBB that uses cgin-xpath needs to declare dependencies on a couple of libraries in its deployment descriptor.

      library-name="CGIN XPath"
      library-version="@cgin-xpath.library.version@"
      library-vendor="OpenCloud"

      library-name="commons-jxpath"
      library-version="@commons-jxpath.version@"
      library-vendor="apache"
    

These libraries are deployed as part of the CGIN RA, so no special action is required.

Limitations

Only getting of components is supported by cgin-xpath; setting is there in JXPath, but hasn't been implemented in cgin-xpath yet.