Package com.saxonica.xqj

Class SaxonXQItem

    • Method Detail

      • getSaxonItem

        public Item getSaxonItem()
        Description copied from interface: SaxonXQItemAccessor
        Get the current item, in the form of a Saxon Item object. This allows access to non-XQJ methods to manipulate the item, which will not necessarily be stable from release to release. The resulting Item will be an instance of either NodeInfo or AtomicValue.
        Specified by:
        getSaxonItem in interface SaxonXQItemAccessor
        Returns:
        the current item

      • getConnection

        public XQConnection getConnection()
                           throws XQException
        Description copied from interface: XQResultItem
        Gets the XQuery connection associated with this result item
        Specified by:
        getConnection in interface XQResultItem
        Returns:
        the connection associated with this result item
        Throws:
        XQException - if the result item is in a closed state

      • getAtomicValue

        public java.lang.String getAtomicValue()
                                throws XQException
        Description copied from interface: XQItemAccessor
        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.
        Specified by:
        getAtomicValue in interface XQItemAccessor
        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

      • getBoolean

        public boolean getBoolean()
                   throws XQException
        Description copied from interface: XQItemAccessor
        Gets the current item as a boolean. The current item must be an atomic value of type xs:boolean or a subtype.
        Specified by:
        getBoolean in interface XQItemAccessor
        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
        Description copied from interface: XQItemAccessor
        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.
        Specified by:
        getByte in interface XQItemAccessor
        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
        Description copied from interface: XQItemAccessor
        Gets the current item as a double. The current item must be an atomic value of type xs:double or a subtype.
        Specified by:
        getDouble in interface XQItemAccessor
        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
        Description copied from interface: XQItemAccessor
        Gets the current item as a float. The current item must be an atomic value of type xs:float or a subtype.
        Specified by:
        getFloat in interface XQItemAccessor
        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
        Description copied from interface: XQItemAccessor
        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.
        Specified by:
        getInt in interface XQItemAccessor
        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

      • getItemAsStream

        public javax.xml.stream.XMLStreamReader getItemAsStream()
                                                 throws XQException
        Description copied from interface: XQItemAccessor
        Read the current item as an XMLStreamReader object, 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 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.

        Specified by:
        getItemAsStream in interface XQItemAccessor
        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

        public java.lang.String getItemAsString​(java.util.Properties props)
                                 throws XQException
        Description copied from interface: XQItemAccessor
        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 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.

        Specified by:
        getItemAsString in interface XQItemAccessor
        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

      • validateSerializationProperties

        protected static void validateSerializationProperties​(java.util.Properties props,
                                                      Configuration config)
                                               throws XQException
        Throws:
        XQException

      • getItemType

        public XQItemType getItemType()
                       throws XQException
        Description copied from interface: XQItemAccessor
        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.

        Specified by:
        getItemType in interface XQItemAccessor
        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

      • getLong

        public long getLong()
             throws XQException
        Description copied from interface: XQItemAccessor
        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.
        Specified by:
        getLong in interface XQItemAccessor
        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 org.w3c.dom.Node getNode()
                         throws XQException
        Description copied from interface: XQItemAccessor
        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 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.

        Specified by:
        getNode in interface XQItemAccessor
        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 java.net.URI getNodeUri()
                        throws XQException
        Description copied from interface: XQItemAccessor
        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 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.

        Specified by:
        getNodeUri in interface XQItemAccessor
        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

        public java.lang.Object getObject()
                           throws XQException
        Description copied from interface: XQItemAccessor
        Gets the current item as an Object.

        The data type of the returned object will be the Java Object type 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.

        Specified by:
        getObject in interface XQItemAccessor
        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

      • getShort

        public short getShort()
               throws XQException
        Description copied from interface: XQItemAccessor
        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.
        Specified by:
        getShort in interface XQItemAccessor
        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
        Description copied from interface: XQItemAccessor
        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 schema 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 isUserDefinedXMLSchemaTypeSupported() 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 true even though the XQJ implementation does not know the precise type information of mySchema:hatSize type defined in XML schema 'mySchema'.
        Specified by:
        instanceOf in interface XQItemAccessor
        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, (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) the type parameter is null

      • writeItem

        public void writeItem​(java.io.OutputStream os,
                      java.util.Properties props)
               throws XQException
        Description copied from interface: XQItemAccessor
        Serializes the current item 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 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.

        Specified by:
        writeItem in interface XQItemAccessor
        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, (4) if there are errors during serialization, or (5) the os parameter is null

      • writeItem

        public void writeItem​(java.io.Writer ow,
                      java.util.Properties props)
               throws XQException
        Description copied from interface: XQItemAccessor
        Serializes the current item 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 12 Serialization, 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.

        Specified by:
        writeItem in interface XQItemAccessor
        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, (4) if there are errors during serialization, or (5) the ow parameter is null

      • writeItemToResult

        public void writeItemToResult​(javax.xml.transform.Result result)
                       throws XQException
        Description copied from interface: XQItemAccessor
        Writes the current item to a Result. First the item is normalized as described in XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized to the Result object.

        Note that the normalization process can fail, in which case an XQException is thrown.

        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
        Specified by:
        writeItemToResult in interface XQItemAccessor
        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 the Result object, or (5) the result parameter is null

      • writeItemToSAX

        public void writeItemToSAX​(org.xml.sax.ContentHandler saxHandler)
                    throws XQException
        Description copied from interface: XQItemAccessor
        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.

        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.

        Specified by:
        writeItemToSAX in interface XQItemAccessor
        Parameters:
        saxHandler - 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) the saxhdlr parameter is null