Package javax.xml.xquery
Interface XQItemAccessor
-
- All Known Subinterfaces:
XQItem,XQResultItem,XQResultSequence,XQSequence
- All Known Implementing Classes:
SaxonXQForwardSequence,SaxonXQItem,SaxonXQSequence
public interface XQItemAccessorThis 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.equals(intType)) { ... }; }See also:- Table 6 - XQuery Atomic Types and Corresponding Java Object Types,
XQuery API for Java (XQJ) 1.0, for mapping of XQuery atomic
types to Java object types. For example, if the XQuery value returned is
of type
xs:unsignedByte, then calling thegetObject()method will return a Java object of typejava.lang.Short. - Table 7 - XQuery Node Types and Corresponding Java Object Types
XQuery API for Java (XQJ) 1.0, for the mapping of XQuery node types
to the corresponding Java object types. For example, if the XQuery value
returned is an element node, then calling the
getObject()orgetNode()method will return a Java object of typeorg.w3.dom.Element.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.lang.StringgetAtomicValue()Gets the current item as a JavaString.booleangetBoolean()Gets the current item as aboolean.bytegetByte()Gets the current item as abyte.doublegetDouble()Gets the current item as adouble.floatgetFloat()Gets the current item as afloat.intgetInt()Gets the current item as anint.javax.xml.stream.XMLStreamReadergetItemAsStream()Read the current item as anXMLStreamReaderobject, as described in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0.java.lang.StringgetItemAsString(java.util.Properties props)Serializes the current item according to the XSLT 2.0 and XQuery 1.0 serialization.XQItemTypegetItemType()Gets the type of the item.longgetLong()Gets the current item as along.org.w3c.dom.NodegetNode()Gets the item as a DOM node.java.net.URIgetNodeUri()Returns the URI for this item.java.lang.ObjectgetObject()Gets the current item as anObject.shortgetShort()Gets the current item as ashort.booleaninstanceOf(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.voidwriteItem(java.io.OutputStream os, java.util.Properties props)Serializes the current item to aWriteraccording to XSLT 2.0 and XQuery 1.0 serialization.voidwriteItem(java.io.Writer ow, java.util.Properties props)Serializes the current item to aWriteraccording to XSLT 2.0 and XQuery 1.0 serialization.voidwriteItemToResult(javax.xml.transform.Result result)Writes the current item to aResult.voidwriteItemToSAX(org.xml.sax.ContentHandler saxhdlr)Writes the current item to a SAX handler, as described in in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0.
-
-
-
Method Detail
-
getBoolean
boolean getBoolean() throws XQExceptionGets the current item as aboolean. The current item must be an atomic value of typexs:booleanor a subtype.- Returns:
- a
booleanrepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to abooleanfails, (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
byte getByte() throws XQExceptionGets the current item as abyte. The current item must be an atomic value of typexs:decimalor a subtype, and its value must be in the value space ofbyte.- Returns:
- a
byterepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to abytefails, (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
double getDouble() throws XQExceptionGets the current item as adouble. The current item must be an atomic value of typexs:doubleor a subtype.- Returns:
- a
doublerepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to adoublefails, (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
float getFloat() throws XQExceptionGets the current item as afloat. The current item must be an atomic value of typexs:floator a subtype.- Returns:
- a
floatrepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to afloatfails, (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
int getInt() throws XQExceptionGets the current item as anint. The current item must be an atomic value of typexs:decimalor a subtype, and its value must be in the value space ofint.- Returns:
- an
intrepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to aintfails, (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
XQItemType getItemType() throws XQException
Gets the type of the item.
On a forward only sequence this 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
java.lang.String getAtomicValue() throws XQExceptionGets the current item as a JavaString. The current item must be an atomic value. This function casts the current item to anxs:stringvalue 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 JavaString.- 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
long getLong() throws XQExceptionGets the current item as along. The current item must be an atomic value of typexs:decimalor a subtype, and its value must be in the value space oflong.- Returns:
- a
longrepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to alongfails, (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
org.w3c.dom.Node getNode() throws XQExceptionGets the item as a DOM node. The current item must be a node. The type of the returned DOM node is governed by Table 7 - 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
java.net.URI getNodeUri() throws XQExceptionReturns 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 iffn:document-uriwere 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 this 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 document URI for this document node or the empty string if not available. For other node kinds, the result is implementation-defined
- 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
-
getObject
java.lang.Object getObject() throws XQExceptionGets the current item as anObject. The data type of the returned object will be the JavaObjecttype as specified in 14.4 Mapping an XQuery Atomic Value to a Java Object Type and 14.5 Mapping an XQuery Node to a Java Object Type, XQuery API for Java (XQJ) 1.0.- 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
-
getItemAsStream
javax.xml.stream.XMLStreamReader getItemAsStream() throws XQExceptionRead the current item as anXMLStreamReaderobject, as described in Section 12.1 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 aXQExceptionis 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 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0
-
getItemAsString
java.lang.String getItemAsString(java.util.Properties props) throws XQExceptionSerializes 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 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.- Parameters:
props- specifies the serialization parameters,nullis considered equivalent to an emptyPropertiesobject- 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
short getShort() throws XQExceptionGets the current item as ashort. The current item must be an atomic value of typexs:decimalor a subtype, and its value must be in the value space ofshort.- Returns:
- a
shortrepresenting the current item - Throws:
XQException- if (1) the conversion of the current item to ashortfails, (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
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 theXQItemAccessoror the inputXQItemTypeis 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 schema types if theXQMetaData.isUserDefinedXMLSchemaTypeSupported()method returnsfalse.
Otherwise, this method must determine if the type of theXQItemAccessoris an instance of the inputXQItemType. Note even ifisUserDefinedXMLSchemaTypeSupported()returnsfalse, 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 anXQItemAccessoris ofmySchema:hatSizesequence type and the input parameterXQItemTypeis ofitem()sequence type, the return value for instanceOf relationship should always betrueeven though the XQJ implementation does not know the precise type information ofmySchema:hatSizetype defined in XML schema'mySchema'.- Parameters:
type- item type to match- Returns:
trueif 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, andfalseif it does not- Throws:
XQException- if (1) there are errors accessing the item's type, (2) if the underlying sequence or item is in a closed state, (3) if the implementation is unable to determine the schema definition of a user defined schema type, or (4) thetypeparameter isnull
-
writeItem
void writeItem(java.io.OutputStream os, java.util.Properties props) throws XQExceptionSerializes the current item to aWriteraccording 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 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.- Parameters:
os- the output stream into which the current item is to be serializedprops- specifies the serialization parameters,nullis considered equivalent to an emptyPropertiesobject- 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, (4) if there are errors during serialization, or (5) theosparameter isnull
-
writeItem
void writeItem(java.io.Writer ow, java.util.Properties props) throws XQExceptionSerializes the current item to aWriteraccording 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 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
Warning: When outputting to aWriter, 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 serializedprops- specifies the serialization parameters,nullis considered equivalent to an emptyPropertiesobject- 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, (4) if there are errors during serialization, or (5) theowparameter isnull
-
writeItemToSAX
void writeItemToSAX(org.xml.sax.ContentHandler saxhdlr) throws XQExceptionWrites the current item to a SAX handler, as described in in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case aXQExceptionis thrown. The specifiedorg.xml.sax.ContentHandlercan optionally implement theorg.xml.sax.LexicalHandlerinterface. An implementation must check if the specifiedContentHandlerimplementsLexicalHandler. If the handler is aLexicalHandlercomment 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, (4) in case of an error while serializing the XDM instance into a SAX event stream, or (5) thesaxhdlrparameter isnull
-
writeItemToResult
void writeItemToResult(javax.xml.transform.Result result) throws XQExceptionWrites the current item to aResult. First the item is normalized as described in XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized to theResultobject.
Note that the normalization process can fail, in which case anXQExceptionis thrown. An XQJ implementation must at least support the following implementations:javax.xml.transform.dom.DOMResultjavax.xml.transform.sax.SAXResultjavax.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, (4) in case of an error while serializing the current item into theResultobject, or (5) theresultparameter isnull
-
-