net.sf.saxon.xqj

## Class SaxonXQDataFactory

- java.lang.Object
- - net.sf.saxon.xqj.Closable
  - - net.sf.saxon.xqj.SaxonXQDataFactory

- All Implemented Interfaces:
    XQDataFactory
  Direct Known Subclasses:
    SaxonXQConnection

      public abstract class SaxonXQDataFactory
      extends Closable
      implements XQDataFactory

  Saxon implementation of the XQJ interface XQDataFactory. This is an abstract superclass for SaxonXQDataSource and SaxonXQConnection, both of which provide the factory methods in this interface.

  For Javadoc specifications of the public methods in this class, see the XQJ documentation.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SaxonXQDataFactory()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XQItemType` | `createAtomicType(int baseType)` Create an atomic item type object representing a particular built-in atomic type
    `XQItemType` | `createAtomicType(int baseType, QName typename, URI schemaURI)` See interface definition, and description of Saxon extensions below.
    `XQItemType` | `createAttributeType(QName nodename, int basetype)` Creates a new `XQItemType` object representing the XQuery `attribute(nodename, basetype)` type with the given node name and base type.
    `XQItemType` | `createAttributeType(QName nodename, int basetype, QName typename, URI schemaURI)` Creates a new `XQItemType` object representing the XQuery `attribute(nodename,basetype,typename,schemaURI)` type, with the given node name, base type, schema type name and schema URI.
    `XQItemType` | `createCommentType()` Creates a new `XQItemType` object representing the XQuery `comment()` type.
    `XQItemType` | `createDocumentElementType(XQItemType elementType)` Creates a new `XQItemType` object representing the XQuery `document-node(elementType)` type containing a single element.
    `XQItemType` | `createDocumentSchemaElementType(XQItemType type)` Creates a new `XQItemType` object representing the XQuery `document-node(elementType)` type containing a single `schema-element(...)`.
    `XQItemType` | `createDocumentType()` Creates a new `XQItemType` object representing the XQuery `document-node()` type.
    `XQItemType` | `createElementType(QName nodename, int basetype)` Creates a new `XQItemType` object representing the XQuery `element(nodename, basetype)` type, with the given node name and base type.
    `XQItemType` | `createElementType(QName nodename, int basetype, QName typename, URI schemaURI, boolean allowNill)` Creates a new `XQItemType` object representing the XQuery `element(nodename,basetype,typename,schemaURI, allowNill)` type, given the node name, base type, schema type name, schema URI, and nilled check.
    `XQItem` | `createItem(XQItem item)` Creates a copy of the specified `XQItem`.
    `XQItem` | `createItemFromAtomicValue(String value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromBoolean(boolean value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromByte(byte value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromDocument(InputStream value, String baseURI, XQItemType type)` Creates an item from the given value.
    `XQItem` | `createItemFromDocument(Reader value, String baseURI, XQItemType type)` Creates an item from the given value.
    `XQItem` | `createItemFromDocument(Source value, XQItemType type)` Creates an item from the given `Source`.
    `XQItem` | `createItemFromDocument(String value, String baseURI, XQItemType type)` Creates an item from the given value.
    `XQItem` | `createItemFromDocument(XMLStreamReader value, XQItemType type)` Creates an item from the given value.
    `XQItem` | `createItemFromDouble(double value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromFloat(float value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromInt(int value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromLong(long value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromNode(Node value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromObject(Object value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromShort(short value, XQItemType type)` Creates an item from a given value.
    `XQItem` | `createItemFromString(String value, XQItemType type)` Creates an item from a given value.
    `XQItemType` | `createItemType()` Creates a new `XQItemType` object representing the XQuery item type.
    `XQItemType` | `createNodeType()` Creates a new `XQItemType` object representing the XQuery `node()` type.
    `XQItemType` | `createProcessingInstructionType(String piTarget)` Creates a new `XQItemType` object representing the XQuery `processing-instruction(piTarget)` type.
    `XQItemType` | `createSchemaAttributeType(QName nodename, int basetype, URI schemaURI)` Creates a new `XQItemType` object representing the XQuery `schema-attribute(nodename,basetype,schemaURI)` type, with the given node name, base type, and schema URI.
    `XQItemType` | `createSchemaElementType(QName nodename, int basetype, URI schemaURI)` Creates a new `XQItemType` object representing the XQuery `schema-element(nodename,basetype,schemaURI)` type, given the node name, base type, and the schema URI.
    `XQSequence` | `createSequence(Iterator i)` Creates an `XQSequence`, containing all the items from the iterator.
    `XQSequence` | `createSequence(XQSequence s)` Creates a copy of the specified `XQSequence`.
    `XQSequenceType` | `createSequenceType(XQItemType item, int occurrence)` Creates a new sequence type from an item type and occurence indicator.
    `XQItemType` | `createTextType()` Creates a new `XQItemType` object representing the XQuery `text()` type.
    `ObjectConverter` | `getObjectConverter()` Get the ObjectConverter in use.
    `protected void` | `init()`
    `void` | `setObjectConverter(ObjectConverter converter)` Set the ObjectConverter to be used.

    - ### Methods inherited from class net.sf.saxon.xqj.Closable

      `close, isClosed, setClosableContainer`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SaxonXQDataFactory

          public SaxonXQDataFactory()

  - ### Method Detail

    - #### init

          protected void init()

    - #### setObjectConverter

          public void setObjectConverter(ObjectConverter converter)

      Set the ObjectConverter to be used. This allows user-defined object conversions to override or supplement the standard conversions
      Parameters:
        `converter` - the user-supplied ObjectConverter

    - #### getObjectConverter

          public ObjectConverter getObjectConverter()

      Get the ObjectConverter in use. This will either be the default object converter supplied by Saxon, or a user-supplied ObjectConverter if one has been set.
      Returns:
        the ObjectConverter in use.

    - #### createAtomicType

          public XQItemType createAtomicType(int baseType)
                                      throws XQException

      Create an atomic item type object representing a particular built-in atomic type
      Specified by:
        `createAtomicType` in interface `XQDataFactory`
      Parameters:
        `baseType` - the built-in atomic type, typically a constant such as XQItemType.XQBASETYPE_BOOLEAN
      Returns:
        the corresponding XQItemType
      Throws:
        `XQException` - if the supplied baseType parameter is not an atomic type

    - #### createAtomicType

          public XQItemType createAtomicType(int baseType,
                                    QName typename,
                                    URI schemaURI)
                                      throws XQException

      See interface definition, and description of Saxon extensions below.

      In addition to the actions described in the XQJ interface definitions, Saxon allows the typename to be a name representing a Java external type. In this case the URI part of the QName must be `NamespaceConstant.JAVA_TYPE`, and the local part of the name must be the Java class name (qualified with its package name)

      Specified by:
        `createAtomicType` in interface `XQDataFactory`
      Parameters:
        `baseType` - the "baseType" (in XQJ terminology)
        `typename` - the qualified name of the type
        `schemaURI` - the location of a schema document in which the type is defined (may be null)
      Returns:
        the item type definition
      Throws:
        `XQException`

    - #### createAttributeType

          public XQItemType createAttributeType(QName nodename,
                                       int basetype)
                                         throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `attribute(nodename, basetype)` type with the given node name and base type. This method can be used to create item type for attributes with a pre-defined schema type.
      Example -

            XQConnection conn = ..; // An XQuery connection

            - attribute() // no node name, pass null for the node name

              conn.createAttributeType(null, XQItemType.XQBASETYPE_ANYSIMPLETYPE);

            - attribute (*)  // equivalent to attribute()

              conn.createAttributeType(null, XQItemType.XQBASETYPE_ANYSIMPLETYPE);

            - attribute (person) // attribute of name person and any simple type.

              conn.createAttributeType(new QName("person"), XQItemType.XQBASETYPE_ANYSIMPLETYPE);

            - attribute(foo:bar) // node name foo:bar, type is any simple type

              conn.createAttributeType(new QName("http://www.foo.com", "bar","foo"),
                                       XQItemType.XQBASETYPE_ANYSIMPLETYPE);

            - attribute(foo:bar, xs:integer) // node name foo:bar, type is xs:integer

              conn.createAttributeType(new QName("http://www.foo.com", "bar","foo"),
                                       XQItemType.XQBASETYPE_INTEGER);

      Specified by:
        `createAttributeType` in interface `XQDataFactory`
      Parameters:
        `nodename` - specifies the name of the node.`null` indicates a wildcard for the node name
        `basetype` - the base type of the attribute. One of the `XQItemType.XQBASETYPE_*` other than `XQItemType.XQBASETYPE_UNTYPED` or `XQItemType.XQBASETYPE_ANYTYPE`
      Returns:
        a new `XQItemType` representing the XQuery `attribute(nodename, basetype)` type
      Throws:
        `XQException` - if (1) the underlying object implementing the interface is closed or (2) if the base type is one of: `XQItemType.XQBASETYPE_UNTYPED` or `XQItemType.XQBASETYPE_ANYTYPE`

    - #### createAttributeType

          public XQItemType createAttributeType(QName nodename,
                                       int basetype,
                                       QName typename,
                                       URI schemaURI)
                                         throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `attribute(nodename,basetype,typename,schemaURI)` type, with the given node name, base type, schema type name and schema URI. The type name can reference either pre-defined simple types or user-defined simple types.
      Example -

            XQConnection conn = ..; // An XQuery connection

            - attribute (name, employeename) // attribute name of type employeename

            conn.createAttributeType(new QName("name"), XQItemType.XQBASETYPE_ANYSIMPLETYPE,
                                     new QName("employeename"), null);

            - attribute (foo:bar, po:city)
            where the prefix foo refers to the namespace http://www.foo.com and the
            prefix po refers to the namespace "http://www.address.com"

            conn.createAttributeType(new QName("http://www.foo.com", "bar","foo"),
                                     XQItemType.XQBASETYPE_ANYSIMPLETYPE,
                                     new QName("http://address.com", "address","po"), null);

            - attribute (zip, zipcode) // attribute zip of type zipchode which derives from
                                       // xs:string

            conn.createAttributeType(new QName("zip"), XQItemType.XQBASETYPE_STRING,
                                     new QName("zipcode"), null);

            - attribute(foo:bar, po:hatsize)
            where the prefix foo refers to the namespace http://www.foo.com and the
            prefix po refers to the namespace "http://www.hatsizes.com"
            with schema URI "http://hatschema.com"

            conn.createAttributeType(new QName("http://www.foo.com", "bar","foo"),
                            XQItemType.XQBASETYPE_INTEGER,
                            new QName("http://www.hatsizes.com", "hatsize","po"),
                            new QName("http://hatschema.com"));

      Specified by:
        `createAttributeType` in interface `XQDataFactory`
      Parameters:
        `nodename` - specifies the name of the node.`null` indicates a wildcard for the node name
        `basetype` - the base type of the attribute. One of the `XQItemTyupe.XQBASETYPE_*` constants other than `XQItemType.XQBASETYPE_UNTYPED` or `XQItemType.XQBASETYPE_ANYTYPE`
        `typename` - the `QName` of the type. If the `QName` refers to a predefinied type, it must match the `basetype`. Can be `null`.
        `schemaURI` - the URI to the schema. Can be `null`. This can only be specified if the typename is also specified
      Returns:
        a new `XQItemType` representing the XQuery `attribute(nodename,basetype, typename,schemaURI)` type.
      Throws:
        `XQException` - if (1) the underlying object implementing the interface is closed, (2) if the base type is one of: `XQItemType.XQBASETYPE_UNTYPED` or `XQItemType.XQBASETYPE_ANYTYPE`, (3) the schema URI is specified and the typename is not specified, (4) the implementation does not support user-defined XML schema types, or (5) if the `typename` refers to a predefinied type and does not match `basetype`

    - #### createCommentType

          public XQItemType createCommentType()
                                       throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `comment()` type. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_COMMENT`.
      Example -

            XQConnection conn = ..; // An XQuery connection
            XQItemType cmttype = conn.createCommentType();

            int itemkind = cmttype.getItemKind(); // will be XQItemType.XQITEMKIND_COMMENT

            XQExpression expr = conn.createExpression();
            XQSequence result = expr.executeQuery("<!-- comments -->");

            result.next();
            boolean pi = result.instanceOf(cmttype);  // will be true

      Specified by:
        `createCommentType` in interface `XQDataFactory`
      Returns:
        a new `XQItemType` representing the XQuery `comment()` type
      Throws:
        `XQException` - if the underlying object implementing the interface is closed

    - #### createDocumentElementType

          public XQItemType createDocumentElementType(XQItemType elementType)
                                               throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `document-node(elementType)` type containing a single element. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_DOCUMENT_ELEMENT` and the base type set to the item type of the input `elementType`.
      Specified by:
        `createDocumentElementType` in interface `XQDataFactory`
      Parameters:
        `elementType` - an `XQItemType` object representing an XQuery `element()` type, cannot be `null`
      Returns:
        a new `XQItemType` representing the XQuery `document-node(elementType)` type containing a single element
      Throws:
        `XQException` - if (1) the underlying object implementing the interface is closed or (2) the `elementType` has an item kind different from `XQItemType.XQITEMKIND_ELEMENT`, (3) the `elementType` argument is `null`, or (4) the implementation does not support user-defined XML schema types

    - #### createDocumentSchemaElementType

          public XQItemType createDocumentSchemaElementType(XQItemType type)
                                                     throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `document-node(elementType)` type containing a single `schema-element(...)`. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT` and the base type set to the item type of the input `elementType`.
      Specified by:
        `createDocumentSchemaElementType` in interface `XQDataFactory`
      Parameters:
        `type` - an `XQItemType` object representing an XQuery `schema-element(...)` type, cannot be `null`
      Returns:
        a new `XQItemType` representing the XQuery `document-node(elementType)` type containing a single `schema-element(...)` element
      Throws:
        `XQException` - if (1) the underlying object implementing the interface is closed or (2) the `elementType` has an item kind different from `XQItemType.XQITEMKIND_SCHEMA_ELEMENT`, (3) the `elementType` argument is `null`, (4) the implementation does not support user-defined XML schema types

    - #### createDocumentType

          public XQItemType createDocumentType()
                                        throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `document-node()` type. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_DOCUMENT`.
      Specified by:
        `createDocumentType` in interface `XQDataFactory`
      Returns:
        a new `XQItemType` representing the XQuery `document-node()` type
      Throws:
        `XQException` - if the underlying object implementing the interface is closed

    - #### createElementType

          public XQItemType createElementType(QName nodename,
                                     int basetype)
                                       throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `element(nodename, basetype)` type, with the given node name and base type. This method can be used to create item type for elements with a pre-defined schema type.
      Example -

            XQConnection conn = ..; // An XQuery connection
            - element() // no node name, pass null for the node name

            conn.createElementType(null, XQItemType.XQBASETYPE_ANYTYPE);

            - element (*)  // equivalent to element()

            conn.createElementType(null, XQItemType.XQBASETYPE_ANYTYPE);

            - element(person) // element of name person and any type.

            conn.createElementType(new QName("person"), XQItemType.XQBASETYPE_ANYTYPE);

            - element(foo:bar) // node name foo:bar, type is anytype

            conn.createElementType(new QName("http://www.foo.com", "bar","foo"),
                                   XQItemType.XQBASETYPE_ANYTYPE);

            - element(foo:bar, xs:integer) // node name foo:bar, type is xs:integer

            conn.createElementType(new QName("http://www.foo.com", "bar","foo"),
                                   XQItemType.XQBASETYPE_INTEGER);

      Specified by:
        `createElementType` in interface `XQDataFactory`
      Parameters:
        `nodename` - specifies the name of the node. `null` indicates a wildcard for the node name
        `basetype` - the base type of the item. One of the `XQItemType.XQBASETYPE_*` constants
      Returns:
        a new `XQItemType` representing the XQuery `element(nodename, basetype)` type
      Throws:
        `XQException` - if (1) the underlying object implementing the interface is closed

    - #### createElementType

          public XQItemType createElementType(QName nodename,
                                     int basetype,
                                     QName typename,
                                     URI schemaURI,
                                     boolean allowNill)
                                       throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `element(nodename,basetype,typename,schemaURI, allowNill)` type, given the node name, base type, schema type name, schema URI, and nilled check. The type name can reference either pre-defined schema types or user-defined types.
      Example -

            XQConnection conn = ..; // An XQuery connection

            - element (person, employee) // element person of type employee

            conn.createElementType(new QName("person"), XQItemType.XQBASETYPE_ANYTYPE,
                                   new QName("employee"), null ,false);

            - element(person, employee ? ) // element person of type employee, whose nilled
                                           // property may be true or false.

            conn.createElementType(new QName("person"), XQItemType.XQBASETYPE_ANYTYPE,
                                   new QName("employee"), null ,true);

            - element(foo:bar, po:address)
            where the prefix foo refers to the namespace http://www.foo.com and the
            prefix po refers to the namespace "http://www.address.com"

            conn.createElementType(new QName("http://www.foo.com", "bar","foo"),
                         XQItemType.XQBASETYPE_ANYTYPE,
                         new QName("http://address.com", "address","po"), null, false);

            - element (zip, zipcode) // element zip of type zipchode which derives from
                                     // xs:string

            conn.createElementType(new QName("zip"), XQItemType.XQBASETYPE_STRING,
                                   new QName("zipcode"), null, false);

            - element (*, xs:anyType ?)

            conn.createElementType(null, XQItemType.XQBASETYPE_ANYTYPE, null, null, true);

            - element(foo:bar, po:hatsize)
            where the prefix foo refers to the namespace http://www.foo.com and the
            prefix po refers to the namespace "http://www.hatsizes.com"
            with schema URI "http://hatschema.com"

            conn.createElementType(new QName("http://www.foo.com", "bar","foo"),
                                XQItemType.XQBASETYPE_INTEGER,
                                new QName("http://www.hatsizes.com", "hatsize","po"),
                                new QName("http://hatschema.com"), false);

      Specified by:
        `createElementType` in interface `XQDataFactory`
      Parameters:
        `nodename` - specifies the name of the element. `null` indicates a wildcard for the node name
        `basetype` - the base type of the item. One of the `XQItemType.XQBASETYPE_*` constants
        `typename` - the `QName` of the type. If the `QName` refers to a predefinied type, it must match the `basetype`. Can be `null`
        `schemaURI` - the URI to the schema. Can be `null`. This can only be specified if the typename is also specified
        `allowNill` - the nilled property of the element
      Returns:
        a new `XQItemType` representing the XQuery `element(nodename,basetype, typename,schemaURI, allowNill)` type
      Throws:
        `XQException` - if (1) schemaURI is specified but the typename is not specified, (2) the underlying object implementing the interface is closed, (3) the implementation does not support user-defined XML schema types, or (4) if the `typename` refers to a predefinied type and does not match `basetype`

    - #### createItem

          public XQItem createItem(XQItem item)
                            throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a copy of the specified `XQItem`. This method can be used, for example, to copy an `XQResultItem` object so that the new item is not dependant on the connection.
      Specified by:
        `createItem` in interface `XQDataFactory`
      Parameters:
        `item` - the `XQItem` to copy
      Returns:
        `XQItem` independent of any underlying `XQConnection` is created
      Throws:
        `XQException` - if (1) the specified item is `null`, (2) the underlying object implementing the interface is closed, (3) the specified item is closed

    - #### createItemFromAtomicValue

          public XQItem createItemFromAtomicValue(String value,
                                         XQItemType type)
                                           throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the casting from `xs:string` rules outlined in 17.1.1 Casting from xs:string and xs:untypedAtomic, XQuery 1.0 and XPath 2.0 Functions and Operators. If the cast fails an `XQException` is thrown.
      Specified by:
        `createItemFromAtomicValue` in interface `XQDataFactory`
      Parameters:
        `value` - the lexical string value of the type
        `type` - the item type
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) any of the arguments are `null`, (2) given type is not an atomic type, (3) the conversion of the value to an XDM instance failed, or (4) the underlying object implementing the interface is closed

    - #### createItemFromBoolean

          public XQItem createItemFromBoolean(boolean value,
                                     XQItemType type)
                                       throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromBoolean` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createItemFromByte

          public XQItem createItemFromByte(byte value,
                                  XQItemType type)
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromByte` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createItemFromDocument

          public XQItem createItemFromDocument(InputStream value,
                                      String baseURI,
                                      XQItemType type)
                                        throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from the given value.
      If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be `null`, `XQITEMKIND_DOCUMENT_ELEMENT`, or `XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT`.
      The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
      If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
      Specified by:
        `createItemFromDocument` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `baseURI` - an optional base URI, can be `null`. It can be used, for example, to resolve relative URIs and to include in error messages.
        `type` - the type of the value for the created document node. If `null` is specified, it behaves as if `XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED))` were passed in as the type parameter. That is, the type represents the XQuery sequence type `document-node(element(*, xs:untyped))`
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the value argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromDocument

          public XQItem createItemFromDocument(Reader value,
                                      String baseURI,
                                      XQItemType type)
                                        throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from the given value.
      If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be `null`, `XQITEMKIND_DOCUMENT_ELEMENT`, or `XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT`.
      The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
      If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
      Specified by:
        `createItemFromDocument` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `baseURI` - an optional base URI, can be `null`. It can be used, for example, to resolve relative URIs and to include in error messages.
        `type` - the type of the value for the created document node. If `null` is specified, it behaves as if `XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED))` were passed in as the type parameter. That is, the type represents the XQuery sequence type `document-node(element(*, xs:untyped))`
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the value argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromDocument

          public XQItem createItemFromDocument(Source value,
                                      XQItemType type)
                                        throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from the given `Source`. An XQJ implementation must at least support the following implementations:
      - `javax.xml.transform.dom.DOMSource`
      - `javax.xml.transform.sax.SAXSource`
      - `javax.xml.transform.stream.StreamSource`
      If the value represents a well-formed XML document, it will result in a document node. The kind of the input type must be `null`, `XQITEMKIND_DOCUMENT_ELEMENT`, or `XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT`.
      The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
      If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
      Specified by:
        `createItemFromDocument` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `type` - the type of the value for the created document node. If `null` is specified, it behaves as if `XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED))` were passed in as the type parameter. That is, the type represents the XQuery sequence type `document-node(element(*, xs:untyped))`
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the value argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromDocument

          public XQItem createItemFromDocument(String value,
                                      String baseURI,
                                      XQItemType type)
                                        throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from the given value.
      If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be `null`, `XQITEMKIND_DOCUMENT_ELEMENT`, or `XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT`.
      The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
      If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
      Specified by:
        `createItemFromDocument` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `baseURI` - an optional base URI, can be `null`. It can be used, for example, to resolve relative URIs and to include in error messages.
        `type` - the type of the value for the created document node. If `null` is specified, it behaves as if `XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED))` were passed in as the type parameter. That is, the type represents the XQuery sequence type `document-node(element(*, xs:untyped))`
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the value argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromDocument

          public XQItem createItemFromDocument(XMLStreamReader value,
                                      XQItemType type)
                                        throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from the given value.
      If the value represents a well-formed XML document, it results in a document node. The kind of the input type must be `null`, `XQITEMKIND_DOCUMENT_ELEMENT` or `XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT`.
      The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
      If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
      Specified by:
        `createItemFromDocument` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `type` - the type of the value for the created document node. If `null` is specified, it behaves as if `XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED))` were passed in as the type parameter. That is, the type represents the XQuery sequence type `document-node(element(*, xs:untyped))`
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the value argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromDouble

          public XQItem createItemFromDouble(double value,
                                    XQItemType type)
                                      throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromDouble` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createItemFromFloat

          public XQItem createItemFromFloat(float value,
                                   XQItemType type)
                                     throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromFloat` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createItemFromInt

          public XQItem createItemFromInt(int value,
                                 XQItemType type)
                                   throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromInt` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createItemFromLong

          public XQItem createItemFromLong(long value,
                                  XQItemType type)
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromLong` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createItemFromNode

          public XQItem createItemFromNode(Node value,
                                  XQItemType type)
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromNode` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the `value` argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromObject

          public XQItem createItemFromObject(Object value,
                                    XQItemType type)
                                      throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromObject` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the `value` argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemFromString

          public XQItem createItemFromString(String value,
                                    XQItemType type)
                                      throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type, which must represent an `xs:string` or a type derived by restriction from `xs:string`. If the specified type is `null`, it defaults to `xs:string`.
      Subsequently the value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromString` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted, cannot be `null`
        `type` - the type of the value to be bound to the external variable. The default type, `xs:string`, is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - if (1) the `value` argument is `null`, (2) the conversion of the value to an XDM instance failed, or (3) the underlying object implementing the interface is closed

    - #### createItemType

          public XQItemType createItemType()
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery item type. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_ITEM`.
      Example -

            XQConnection conn = ..; // An XQuery connection
            XQItemType typ = conn.createItemType(); // represents the XQuery item type "item()"

      Specified by:
        `createItemType` in interface `XQDataFactory`
      Returns:
        a new `XQItemType` representing the XQuery item type
      Throws:
        `XQException` - if the underlying object implementing the interface is closed

    - #### createItemFromShort

          public XQItem createItemFromShort(short value,
                                   XQItemType type)
                                     throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an item from a given value. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the converstion fails, an `XQException` will be thrown.
      Specified by:
        `createItemFromShort` in interface `XQDataFactory`
      Parameters:
        `value` - the value to be converted
        `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
      Returns:
        `XQItem` representing the resulting item
      Throws:
        `XQException` - (1) the conversion of the value to an XDM instance failed, or (2) the underlying object implementing the interface is closed

    - #### createNodeType

          public XQItemType createNodeType()
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `node()` type. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_NODE`.
      Specified by:
        `createNodeType` in interface `XQDataFactory`
      Returns:
        a new `XQItemType` representing the XQuery `node()` type
      Throws:
        `XQException` - if the underlying object implementing the interface is closed

    - #### createProcessingInstructionType

          public XQItemType createProcessingInstructionType(String piTarget)
                                                     throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `processing-instruction(piTarget)` type. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_PI`. A string literal can be passed to match the PITarget of the processing instruction as described in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language.
      Example -

             XQConnection conn = ..; // An XQuery connection
             XQItemType anypi = conn.createProcessingInstructionType();
             XQItemType foopi = conn.createProcessingInstructionType("foo-format");

             XQExpression expr = conn.createExpression();
             XQSequence result = expr.executeQuery("<?format role="output" ?>");

             result.next();
             boolean pi = result.instanceOf(anypi);  // will be true
             pi = result.instanceOf(foopi);  // will be false

             XQExpression expr = conn.createExpression();
             XQSequence result = expr.executeQuery("<?foo-format role="output" ?>");

             result.next();
             boolean pi = result.instanceOf(anypi);  // will be true
             pi = result.instanceOf(foopi);  // will be true

      Specified by:
        `createProcessingInstructionType` in interface `XQDataFactory`
      Parameters:
        `piTarget` - the string literal to match the processing instruction's PITarget. A `null` string value will match all processing instruction nodes
      Returns:
        a new `XQItemType` representing the XQuery `processing-instruction(piTarget)` type
      Throws:
        `XQException` - if the underlying object implementing the interface is closed

    - #### createSchemaAttributeType

          public XQItemType createSchemaAttributeType(QName nodename,
                                             int basetype,
                                             URI schemaURI)
                                               throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `schema-attribute(nodename,basetype,schemaURI)` type, with the given node name, base type, and schema URI.
      Example -

               XQConnection conn = ..; // An XQuery connection

               - schema-attribute (name) // schema-attribute name, found in the schema
                                         // available at http://customerschema.com

               conn.createSchemaAttributeType(new QName("name"),
                            XQItemType.XQBASETYPE_STRING,
                            new URI(http://customerschema.com));

      Specified by:
        `createSchemaAttributeType` in interface `XQDataFactory`
      Parameters:
        `nodename` - specifies the name of the node
        `basetype` - the base type of the attribute. One of the `XQItemTyupe.XQBASETYPE_*` constants other than `XQItemType.XQBASETYPE_UNTYPED` or `XQItemType.XQBASETYPE_ANYTYPE`
        `schemaURI` - the URI to the schema. Can be `null`
      Returns:
        a new `XQItemType` representing the XQuery `schema-attribute(nodename,basetype, schemaURI)` type
      Throws:
        `XQException` - if (1) the node name is `null`, (2) if the base type is one of: `XQItemType.XQBASETYPE_UNTYPED` or `XQItemType.XQBASETYPE_ANYTYPE`, (3) the underlying object implementing the interface is closed, or (4) the implementation does not support user-defined XML schema types

    - #### createSchemaElementType

          public XQItemType createSchemaElementType(QName nodename,
                                           int basetype,
                                           URI schemaURI)
                                             throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `schema-element(nodename,basetype,schemaURI)` type, given the node name, base type, and the schema URI.
      Example -

               XQConnection conn = ..; // An XQuery connection

               - schema-element (customer) // schema-element person, found in
                                           // the schema available at http://customerschema.com

               conn.createElementType(new QName("customer"), XQItemType.XQBASETYPE_ANYTYPE,
                                   new URI("http://customerschema.com"));

      Specified by:
        `createSchemaElementType` in interface `XQDataFactory`
      Parameters:
        `nodename` - specifies the name of the element
        `basetype` - the base type of the item. One of the `XQItemType.XQBASETYPE_*` constants
        `schemaURI` - the URI to the schema. Can be `null`
      Returns:
        a new `XQItemType` representing the XQuery `schema-element(nodename,basetype, schemaURI)` type
      Throws:
        `XQException` - if (1) the node name is `null`, (2) the underlying object implementing the interface is closed, or (3) the implementation does not support user-defined XML schema types

    - #### createSequence

          public XQSequence createSequence(Iterator i)
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates an `XQSequence`, containing all the items from the iterator. The newly created `XQSequence` is scrollable and independent of any underlying `XQConnection`. If the iterator returns an `XQItem`, it is added to the sequence. If the iterator returns any other object, an item is added to the sequence following the rules from 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the iterator does not return any items, then an empty sequence is created.
      Specified by:
        `createSequence` in interface `XQDataFactory`
      Parameters:
        `i` - input iterator
      Returns:
        `XQSequence` representing the sequence containing all items from the input iterator
      Throws:
        `XQException` - if (1) the conversion of any of the objects in the iterator to item fails, (2) the `i` parameter is `null`, or (3) underlying object implementing the interface is closed

    - #### createSequence

          public XQSequence createSequence(XQSequence s)
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a copy of the specified `XQSequence`. The newly created `XQSequence` is scrollable and independent of any underlying `XQConnection`. The new `XQSequence` will contain all items from the specified `XQSequence` starting from its current position. The copy process will implicitly perform next operations on the specified sequence to read the items. All items are consumed, the current position of the cursor is set to point after the last item.
      Specified by:
        `createSequence` in interface `XQDataFactory`
      Parameters:
        `s` - input sequence
      Returns:
        `XQSequence` representing a copy of the input sequence
      Throws:
        `XQException` - if (1) there are errors accessing the items in the specified sequence, (2) the specified sequence is closed, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) the `s` parameter is `null`, or (5) the underlying object implementing the interface is closed

    - #### createSequenceType

          public XQSequenceType createSequenceType(XQItemType item,
                                          int occurrence)
                                            throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new sequence type from an item type and occurence indicator.
      Specified by:
        `createSequenceType` in interface `XQDataFactory`
      Parameters:
        `item` - the item type. This parameter must be `null` if the occurance is `XQSequenceType.OCC_EMPTY`, and cannot be `null` for any other occurance indicator
        `occurrence` - The occurence of the item type, must be one of `XQSequenceType.OCC_ZERO_OR_ONE`, `XQSequenceType.OCC_EXACTLY_ONE`, `XQSequenceType.OCC_ZERO_OR_MORE`, `XQSequenceType.OCC_ONE_OR_MORE`, `XQSequenceType.OCC_EMPTY`
      Returns:
        a new `XQSequenceType` representing the type of a sequence
      Throws:
        `XQException` - if (1) the `item` is `null` and the occurance is not `XQSequenceType.OCC_EMPTY`, (2) the `item` is not `null` and the occurance is `XQSequenceType.OCC_EMPTY`, (3) the occurence is not one of: `XQSequenceType.OCC_ZERO_OR_ONE`, `XQSequenceType.OCC_EXACTLY_ONE`, `XQSequenceType.OCC_ZERO_OR_MORE`, `XQSequenceType.OCC_ONE_OR_MORE`, `XQSequenceType.OCC_EMPTY` or (4) the underlying object implementing the interface is closed

    - #### createTextType

          public XQItemType createTextType()
                                    throws XQException

      Description copied from interface: `XQDataFactory`
      Creates a new `XQItemType` object representing the XQuery `text()` type. The `XQItemType` object will have the item kind set to `XQItemType.XQITEMKIND_TEXT`.
      Specified by:
        `createTextType` in interface `XQDataFactory`
      Returns:
        a new `XQItemType` representing the XQuery `text()` type
      Throws:
        `XQException` - if the underlying object implementing the interface is closed

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.