XQItemAccessor

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ddtek.xquery3
Interface XQItemAccessor

All Known Subinterfaces:: XQItem, XQResultItem, XQResultSequence, XQSequence

public interface XQItemAccessor

This interface represents a common interface for accessing the values of an XQuery item. All the get functions raise an exception if the underlying sequence object is not positioned on an item (e.g. if the sequence is positioned before the first item or after the last item).

Example -

 
  XQPreparedExpression expr = conn.prepareExpression("for $i ..");
  XQSequence result = expr.executeQuery();

  // create the ItemTypes for string and integer
  XQItemType strType = conn.createAtomicType(XQItemType.XQBASETYPE_STRING);
  XQItemType intType = conn.createAtomicType(XQItemType.XQBASETYPE_INTEGER);
 
  // posititioned before the first item
  while (result.next())
  {
    // If string or any of its subtypes, then get the string value out
 
    if (result.instanceOf(strType))
      String str = result.getAtomicValue();
    else if (result.instanceOf(intType))
       // if it is exactly an int
      int intval = result.getInt();
      ...
 
    // Alternatively, you can get the exact type out.
    XQItemType type = result.getItemType();
 
    // Now perform the comparison..
    if (type.isOfType(intType))
    { ... };
  
  }

getBoolean

public boolean getBoolean()
                   throws XQException

Gets the current item as a boolean. The current item must be an atomic value of type xs:boolean or a subtype.

Returns:: a boolean representing the current item
Throws:: XQException - if (1) the conversion of the current item to a boolean fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getByte

public byte getByte()
             throws XQException

Gets the current item as a byte. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of byte.

Returns:: a byte representing the current item
Throws:: XQException - if (1) the conversion of the current item to a byte fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getDouble

public double getDouble()
                 throws XQException

Gets the current item as a double. The current item must be an atomic value of type xs:double or a subtype.

Returns:: a double representing the current item
Throws:: XQException - if (1) the conversion of the current item to a double fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getFloat

public float getFloat()
               throws XQException

Gets the current item as a float. The current item must be an atomic value of type xs:float or a subtype.

Returns:: a float representing the current item
Throws:: XQException - if (1) the conversion of the current item to a float fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getInt

public int getInt()
           throws XQException

Gets the current item as an int. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of int.

Returns:: an int representing the current item
Throws:: XQException - if (1) the conversion of the current item to a int fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getItemType

public XQItemType getItemType()
                       throws XQException

Gets the type of the item.
On a forward only sequence his method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method.

Returns:: the type of the item.
Throws:: XQException - if (1) there are errors accessing the type of the item, or (2) the underlying sequence or item is in a closed state

getAtomicValue

public String getAtomicValue()
                      throws XQException

Gets the current item as a Java String. The current item must be an atomic value. This function casts the current item to an xs:string value according to the casting rules defined in 17.1.2 Casting to xs:string and xs:untypedAtomic, XQuery 1.0 and XPath 2.0 Functions and Operators, and then returns the value as a Java String.

Returns:: the string representation of the item
Throws:: XQException - if (1) there are errors accessing the item's value, (2) the item is not an atomic value, (3) there is an error when casting the item to a string representation, (4) the underlying sequence or item is in a closed state, or (5) in the case of forward only sequences, a get or write method was already invoked on the current item

getLong

public long getLong()
             throws XQException

Gets the current item as a long. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of long.

Returns:: a long representing the current item
Throws:: XQException - if (1) the conversion of the current item to a long fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getNode

public Node getNode()
             throws XQException

Gets the item as a DOM node. The current item must be a node. The type of the returned DOM node is governed by Table 4 - XQuery Node Types and Corresponding Java Object Types XQuery API for Java (XQJ) 1.0 The instance of the returned node is implementation dependent. The node may be a reference or a copy of the internal state of the item. It is advisable to make a copy of the node if the application plans to modify it.

Returns:: a DOM node representing the current item
Throws:: XQException - if (1) if there are errors accessing the current item, (2) the current item is not a node, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getNodeUri

public URI getNodeUri()
               throws XQException

Returns the URI for this item. If the item is a document node, then this method returns the absolute URI of the resource from which the document node was constructed. If the document URI is not available, then the empty string is returned. If the document URI is available, the returned value is the same as if fn:document-uri were evaluated on this document node. If the item is of a node kind other than document node, then the returned URI is implementation-defined.
On a forward only sequence his method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method on the current item.

Returns:: the URI for this item. If the item is a document node, then this method returns the absolute URI of the resource from which the document node was constructed. If the document URI is not available, then the empty string is returned. If the document URI is available, the returned value is the same as if fn:document-uri were evaluated on this document node. If the item is of a node kind other than document node, then the returned URI is implementation-defined.
On a forward only sequence his method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method on the current item.
Throws:: XQException - if (1) if there are errors accessing the current item, (2) the current item is not a node, or (3) if the underlying sequence or item is in a closed state.

getObject

public Object getObject()
                 throws XQException

Gets the current item as an Object. The data type of the returned object will be the Java Object type as specified in 6.3 Mapping an XQuery Atomic Value to a Java Object Type and 6.4 Mapping an XQuery Node to a Java Object Type, XQuery API for Java (XQJ) 1.0. If a XQCommonHandler is set at the XQConnection, then that handler will be used to return the relevant object.

Returns:: an object representing the current item
Throws:: XQException - if (1) if there are errors accessing the current item, (2) if the underlying sequence or item is in a closed state, or (3) in the case of forward only sequences, a get or write method was already invoked on the current item

getObject

public Object getObject(XQCommonHandler hdlr)
                 throws XQException

Returns a Java Object corresponding to the XQuery type using the XQCommonHandler passed in.

Parameters:: hdlr - an XQCommonHandler to use for generating the object. If the hdlr is null, then the data type of the returned object will be the Java Object type as specified in 6.3 Mapping an XQuery Atomic Value to a Java Object Type and 6.4 Mapping an XQuery Node to a Java Object Type, XQuery API for Java (XQJ) 1.0.
Returns:: the result item as a Java Object
Throws:: XQException - if (1) if there are errors accessing the current item, (2) if the underlying sequence or item is in a closed state, or (3) in the case of forward only sequences, a get or write method was already invoked on the current item

getItemAsStream

public XMLStreamReader getItemAsStream()
                                throws XQException

Read the current item as an XMLStreamReader object, as described in Section 4.4.4 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case a XQException is thrown. While the stream is being read, the application MUST NOT do any other concurrent operations on the underlying item or sequence. The operation on the stream is undefined if the underlying sequence is repositioned or the state of the underlying item or sequence is changed by concurrent operations.

Returns:: an XML reader object as XMLStreamReader
Throws:: XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) in case of an error during serialization of the current item into a StAX event stream as defined in Section 4.4.4 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0

getItemAsString

public String getItemAsString(Properties props)
                       throws XQException

Serializes the current item according to the XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 4.4.3.2 Serializing an XQSequence, XQuery API for Java (XQJ) 1.0 for more information.

Parameters:: props - specifies the serialization parameters, null is considered equivalent to an empty Properties object.
Returns:: the serialized representation of the item
Throws:: XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) if there are errors during serialization

getShort

public short getShort()
               throws XQException

Gets the current item as a short. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of short.

Returns:: a short representing the current item
Throws:: XQException - if (1) the conversion of the current item to a short fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

instanceOf

public boolean instanceOf(XQItemType type)
                   throws XQException

Checks if the item "matches" an item type, as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language. You can use this method to first check the type of the result before calling the specific get methods.

Example -

  ...
  XQItemType strType = conn.createAtomicType(XQItemType.XQBASETYPE_STRING);
  XQItemType nodeType = conn.createNodeType();

  XQSequence result = preparedExpr.executeQuery();
  while (result.next())
  {
     // Generic check for node.. 
     if (result.instanceOf(nodeType))
        org.w3.dom.Node node = result.getNode();
     else if (result.instanceOf(strType))
        String str = result.getAtomicValue();
   }

If either the type of the XQItemAccessor or the input XQItemType is not a built-in type, then this method is allowed to raise exception if it can NOT determine the instanceOf relationship due to the lack of the access of the XML schema that defines the user defined schmea types if the XQMetaData.isUserDefinedXMLSchemaTypeSupported() method returns false.
Otherwise, this method must determine if the type of the XQItemAccessor is an instance of the input XQItemType. Note even if isUserDefinedXMLScheamTypeSupported() returns false, an XQJ implementation may still be able to determine the instanceOf relationship for certain cases involving user defined schema type. For example, if the type of an XQItemAccessor is of 'mySchema:hatSize +' sequence type and the input parameter XQItemType is of 'item()' sequence type, the return value for instanceOf relationship should always be false even though the XQJ implementation does not know the precise type information of mySchema:hatSize type defined in XML schema 'mySchema'.

Parameters:: type - item type to match
Returns:: true if this item matches the input item type as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language, and false if it does not.
Throws:: XQException - if (1) there are errors accessing the item's type, or (2) if the underlying sequence or item is in a closed state, or (3) if the implementation is unable to determine the schema definition of a user defined schema type.

writeItem

public void writeItem(OutputStream os,
                      Properties props)
               throws XQException

Serializes the current item. XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 4.4.3.2 Serializing an XQSequence, XQuery API for Java (XQJ) 1.0 for more information.

Parameters:: os - the output stream into which the current item is to be serialized; props - specifies the serialization parameters, null is considered equivalent to an empty Properties object.
Throws:: XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) if there are errors during serialization

writeItem

public void writeItem(Writer ow,
                      Properties props)
               throws XQException

Serializes the current item according to a Writer according to XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 4.4.3.2 Serializing an XQSequence, XQuery API for Java (XQJ) 1.0 for more information.

Warning: When outputting to a Writer, make sure the writer's encoding matches the encoding parameter if specified as a property or the default encoding.

Parameters:: ow - the writer object into which the current item is to be serialized; props - specifies the serialization parameters, null is considered equivalent to an empty Properties object.
Throws:: XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) if there are errors during serialization

writeItemToSAX

public void writeItemToSAX(ContentHandler saxhdlr)
                    throws XQException

Writes the current item to a SAX handler, as described in in Section 4.4.5 Serializing an XDM instance into a StAX event stream, XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case a XQException is thrown. The specified org.xml.sax.ContentHandler can optionally implement the org.xml.sax.LexicalHandler interface. An implementation must check if the specified ContentHandler implements LexicalHandler. If the handler is a LexicalHandler comment nodes are reported, otherwise they will be silently ignored.

Parameters:: saxhdlr - the SAX content handler, optionally a lexical handler
Throws:: XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) in case of an error while serializing the XDM instance into a SAX event stream.

writeItemToResult

public void writeItemToResult(Result result)
                       throws XQException

Writes the current item to a Result. First the item is normalized as described in [XQuery Serialization]. Note that the normalization process can fail, in which case an XQException is thrown. Subsequently it is serialized to the Result object.
An XQJ implementation must at least support the following implementations:

javax.xml.transform.dom.DOMResult

javax.xml.transform.sax.SAXResult

javax.xml.transform.stream.StreamResult

Parameters:: result - the result object into which the item is to be serialized
Throws:: XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) in case of an error while serializing the current item into the Result object.

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Method Summary
`String`	`getAtomicValue()` Gets the current item as a Java `String`.
`boolean`	`getBoolean()` Gets the current item as a `boolean`.
`byte`	`getByte()` Gets the current item as a `byte`.
`double`	`getDouble()` Gets the current item as a `double`.
`float`	`getFloat()` Gets the current item as a `float`.
`int`	`getInt()` Gets the current item as an `int`.
`XMLStreamReader`	`getItemAsStream()` Read the current item as an `XMLStreamReader` object, as described in Section 4.4.4 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0.
`String`	`getItemAsString(Properties props)` Serializes the current item according to the XSLT 2.0 and XQuery 1.0 serialization.
`XQItemType`	`getItemType()` Gets the type of the item.
`long`	`getLong()` Gets the current item as a `long`.
`Node`	`getNode()` Gets the item as a DOM node.
`URI`	`getNodeUri()` Returns the URI for this item.
`Object`	`getObject()` Gets the current item as an `Object`.
`Object`	`getObject(XQCommonHandler hdlr)` Returns a Java `Object` corresponding to the XQuery type using the `XQCommonHandler` passed in.
`short`	`getShort()` Gets the current item as a `short`.
`boolean`	`instanceOf(XQItemType type)` Checks if the item "matches" an item type, as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language.
`void`	`writeItem(OutputStream os, Properties props)` Serializes the current item.
`void`	`writeItem(Writer ow, Properties props)` Serializes the current item according to a `Writer` according to XSLT 2.0 and XQuery 1.0 serialization.
`void`	`writeItemToResult(Result result)` Writes the current item to a `Result`.
`void`	`writeItemToSAX(ContentHandler saxhdlr)` Writes the current item to a SAX handler, as described in in Section 4.4.5 Serializing an XDM instance into a StAX event stream, XQuery API for Java (XQJ) 1.0.

com.ddtek.xquery3 Interface XQItemAccessor

getBoolean

getByte

getDouble

getFloat

getInt

getItemType

getAtomicValue

getLong

getNode

getNodeUri

getObject

getObject

getItemAsStream

getItemAsString

getShort

instanceOf

writeItem

writeItem

writeItemToSAX

writeItemToResult

com.ddtek.xquery3
Interface XQItemAccessor