org.basex.api.xqj
Class BXQDataFactory

java.lang.Object
  extended by org.basex.api.xqj.BXQDataFactory
All Implemented Interfaces:
XQDataFactory
Direct Known Subclasses:
BXQConnection

public class BXQDataFactory
extends java.lang.Object
implements XQDataFactory

Java XQuery API - Data Factory.

Author:
Workgroup DBIS, University of Konstanz 2005-08, ISC License, Christian Gruen

Constructor Summary
BXQDataFactory()
          Constructor.
 
Method Summary
 void close()
          Closes the class.
 BXQItemType createAtomicType(int b)
          Creates a new XQItemType object representing an XQuery atomic type.
 BXQItemType createAtomicType(int b, javax.xml.namespace.QName qn, java.net.URI uri)
          Creates a new XQItemType object representing an XQuery atomic type.
 BXQItemType createAttributeType(javax.xml.namespace.QName qn, int it)
          Creates a new XQItemType object representing the XQuery attribute(nodename, basetype) type with the given node name and base type.
 BXQItemType createAttributeType(javax.xml.namespace.QName qn, int it, javax.xml.namespace.QName qn2, java.net.URI uri)
          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.
 BXQItemType createCommentType()
          Creates a new XQItemType object representing the XQuery comment() type.
 BXQItemType createDocumentElementType(XQItemType it)
          Creates a new XQItemType object representing the XQuery document-node(elementType) type containing a single element.
 BXQItemType createDocumentSchemaElementType(XQItemType it)
          Creates a new XQItemType object representing the XQuery document-node(elementType) type containing a single schema-element(...).
 BXQItemType createDocumentType()
          Creates a new XQItemType object representing the XQuery document-node() type.
 BXQItemType createElementType(javax.xml.namespace.QName qn, int it)
          Creates a new XQItemType object representing the XQuery element(nodename, basetype) type, with the given node name and base type.
 BXQItemType createElementType(javax.xml.namespace.QName qn, int it, javax.xml.namespace.QName qn2, java.net.URI uri, boolean n)
          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.
 BXQItem createItem(XQItem v)
          Creates a copy of the specified XQItem.
 BXQItem createItemFromAtomicValue(java.lang.String v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromBoolean(boolean v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromByte(byte v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromDocument(java.io.InputStream is, java.lang.String base, XQItemType it)
          Creates an item from the given value.
 BXQItem createItemFromDocument(java.io.Reader r, java.lang.String base, XQItemType it)
          Creates an item from the given value.
 BXQItem createItemFromDocument(javax.xml.transform.Source s, XQItemType it)
          Creates an item from the given Source.
 BXQItem createItemFromDocument(java.lang.String v, java.lang.String base, XQItemType it)
          Creates an item from the given value.
 BXQItem createItemFromDocument(org.xml.sax.XMLReader r, XQItemType it)
          Creates an item from the given value.
 BXQItem createItemFromDocument(javax.xml.stream.XMLStreamReader sr, XQItemType it)
          Creates an item from the given value.
 BXQItem createItemFromDouble(double v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromFloat(float v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromInt(int v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromLong(long v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromNode(org.w3c.dom.Node v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromObject(java.lang.Object v, XQItemType t)
          Creates an item from a given value.
 BXQItem createItemFromShort(short v, XQItemType it)
          Creates an item from a given value.
 BXQItem createItemFromString(java.lang.String v, XQItemType it)
          Creates an item from a given value.
 BXQItemType createItemType()
          Creates a new XQItemType object representing the XQuery item type.
 BXQItemType createNodeType()
          Creates a new XQItemType object representing the XQuery node() type.
 BXQItemType createProcessingInstructionType(java.lang.String nm)
          Creates a new XQItemType object representing the XQuery processing-instruction(piTarget) type.
 BXQItemType createSchemaAttributeType(javax.xml.namespace.QName qn, int it, java.net.URI uri)
          Creates a new XQItemType object representing the XQuery schema-attribute(nodename,basetype,schemaURI) type, with the given node name, base type, and schema URI.
 BXQItemType createSchemaElementType(javax.xml.namespace.QName qn, int it, java.net.URI uri)
          Creates a new XQItemType object representing the XQuery schema-element(nodename,basetype,schemaURI) type, given the node name, base type, and the schema URI.
 BXQSequence createSequence(java.util.Iterator it)
          Creates an XQSequence, containing all the items from the iterator.
 BXQSequence createSequence(XQSequence seq)
          Creates a copy of the specified XQSequence.
 BXQItemType createSequenceType(XQItemType it, int occ)
          Creates a new sequence type from an item type and occurence indicator.
 BXQItemType createTextType()
          Creates a new XQItemType object representing the XQuery text() type.
 boolean isClosed()
          Returns the closed flag.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BXQDataFactory

public BXQDataFactory()
Constructor.

Method Detail

createAtomicType

public BXQItemType createAtomicType(int b,
                                    javax.xml.namespace.QName qn,
                                    java.net.URI uri)
                             throws XQException
Description copied from interface: XQDataFactory
Creates a new XQItemType object representing an XQuery atomic type. The item kind of the item type will be XQItemType.XQITEMKIND_ATOMIC.
Example -

  XQConnection conn = ...;

  // to create po:hatsize atomic item type
  conn.createAtomicType(XQItemType.XQBASETYPE_INTEGER, 
                  new QName("http://www.hatsizes.com", "hatsize","po"), 
                  new URI("http://hatschema.com"));
 

Specified by:
createAtomicType in interface XQDataFactory
Parameters:
b - one of the XQItemType.XQBASETYPE_* constants. All basetype constants except the following are valid:
 
  XQItemType.XQBASETYPE_UNTYPED
  XQItemType.XQBASETYPE_ANYTYPE
  XQItemType.XQBASETYPE_IDREFS
  XQItemType.XQBASETYPE_NMTOKENS
  XQItemType.XQBASETYPE_ENTITIES
  XQItemType.XQBASETYPE_ANYSIMPLETYPE
 
qn - the QName of the type. If the QName refers to a predefinied type, it must match the basetype. Can be null
uri - 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 atomic type
Throws:
XQException - if (1) an invalid basetype value is passed in, (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

createAtomicType

public BXQItemType createAtomicType(int b)
                             throws XQException
Description copied from interface: XQDataFactory
Creates a new XQItemType object representing an XQuery atomic type. The item kind of the item type will be XQItemType.XQITEMKIND_ATOMIC.
Example -
  XQConnection conn = ...;

  // to create xs:integer item type
  conn.createAtomicType(XQItemType.XQBASETYPE_INTEGER); 
 

Specified by:
createAtomicType in interface XQDataFactory
Parameters:
b - one of the XQItemType.XQBASETYPE_* constants. All basetype constants except the following are valid:
 
  XQItemType.XQBASETYPE_UNTYPED
  XQItemType.XQBASETYPE_ANYTYPE
  XQItemType.XQBASETYPE_IDREFS
  XQItemType.XQBASETYPE_NMTOKENS
  XQItemType.XQBASETYPE_ENTITIES
  XQItemType.XQBASETYPE_ANYSIMPLETYPE
 
Returns:
a new XQItemType representing the atomic type
Throws:
XQException - if (1) an invalid basetype value is passed in, or (2) the underlying object implementing the interface is closed

createAttributeType

public BXQItemType createAttributeType(javax.xml.namespace.QName qn,
                                       int it,
                                       javax.xml.namespace.QName qn2,
                                       java.net.URI uri)
                                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:
qn - specifies the name of the node.null indicates a wildcard for the node name
it - the base type of the attribute. One of the XQItemTyupe.XQBASETYPE_* constants other than XQItemType.XQBASETYPE_UNTYPED or XQItemType.XQBASETYPE_ANYTYPE
qn2 - the QName of the type. If the QName refers to a predefinied type, it must match the basetype. Can be null.
uri - 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

createAttributeType

public BXQItemType createAttributeType(javax.xml.namespace.QName qn,
                                       int it)
                                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:
qn - specifies the name of the node.null indicates a wildcard for the node name
it - 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

createCommentType

public BXQItemType 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 BXQItemType createDocumentElementType(XQItemType it)
                                      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:
it - 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 BXQItemType createDocumentSchemaElementType(XQItemType it)
                                            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:
it - 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 BXQItemType 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 BXQItemType createElementType(javax.xml.namespace.QName qn,
                                     int it,
                                     javax.xml.namespace.QName qn2,
                                     java.net.URI uri,
                                     boolean n)
                              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:
qn - specifies the name of the element. null indicates a wildcard for the node name
it - the base type of the item. One of the XQItemType.XQBASETYPE_* constants
qn2 - the QName of the type. If the QName refers to a predefinied type, it must match the basetype. Can be null
uri - the URI to the schema. Can be null. This can only be specified if the typename is also specified
n - 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

createElementType

public BXQItemType createElementType(javax.xml.namespace.QName qn,
                                     int it)
                              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:
qn - specifies the name of the node. null indicates a wildcard for the node name
it - 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

createItem

public BXQItem createItem(XQItem v)
                   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:
v - 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

createItemFromAtomicValue

public BXQItem createItemFromAtomicValue(java.lang.String v,
                                         XQItemType it)
                                  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:
v - the lexical string value of the type
it - 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 BXQItem createItemFromBoolean(boolean v,
                                     XQItemType it)
                              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:
v - the value to be converted
it - 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 BXQItem createItemFromByte(byte v,
                                  XQItemType it)
                           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:
v - the value to be converted
it - 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 BXQItem createItemFromDocument(java.io.InputStream is,
                                      java.lang.String base,
                                      XQItemType it)
                               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:
is - the value to be converted, cannot be null
base - an optional base URI, can be null. It can be used, for example, to resolve relative URIs and to include in error messages.
it - 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 BXQItem createItemFromDocument(java.io.Reader r,
                                      java.lang.String base,
                                      XQItemType it)
                               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:
r - the value to be converted, cannot be null
base - an optional base URI, can be null. It can be used, for example, to resolve relative URIs and to include in error messages.
it - 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 BXQItem createItemFromDocument(javax.xml.transform.Source s,
                                      XQItemType it)
                               throws XQException
Description copied from interface: XQDataFactory
Creates an item from the given Source. An XQJ implementation must at least support the following implementations:

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:
s - the value to be converted, cannot be null
it - 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 BXQItem createItemFromDocument(java.lang.String v,
                                      java.lang.String base,
                                      XQItemType it)
                               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:
v - the value to be converted, cannot be null
base - an optional base URI, can be null. It can be used, for example, to resolve relative URIs and to include in error messages.
it - 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 BXQItem createItemFromDocument(org.xml.sax.XMLReader r,
                                      XQItemType it)
                               throws XQException
Description copied from interface: XQDataFactory
Creates an item from the given value.

If the XMLReader produces 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:
r - the XMLReader producing SAX events representing the document to create
it - 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 BXQItem createItemFromDocument(javax.xml.stream.XMLStreamReader sr,
                                      XQItemType it)
                               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:
sr - the value to be converted, cannot be null
it - 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 BXQItem createItemFromDouble(double v,
                                    XQItemType it)
                             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:
v - the value to be converted
it - 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 BXQItem createItemFromFloat(float v,
                                   XQItemType it)
                            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:
v - the value to be converted
it - 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 BXQItem createItemFromInt(int v,
                                 XQItemType it)
                          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:
v - the value to be converted
it - 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 BXQItem createItemFromLong(long v,
                                  XQItemType it)
                           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:
v - the value to be converted
it - 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 BXQItem createItemFromNode(org.w3c.dom.Node v,
                                  XQItemType it)
                           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:
v - the value to be converted, cannot be null
it - 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 BXQItem createItemFromObject(java.lang.Object v,
                                    XQItemType t)
                             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:
v - the value to be converted, cannot be null
t - 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

createItemFromShort

public BXQItem createItemFromShort(short v,
                                   XQItemType it)
                            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:
v - the value to be converted
it - 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

createItemFromString

public BXQItem createItemFromString(java.lang.String v,
                                    XQItemType it)
                             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:
v - the value to be converted, cannot be null
it - 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 BXQItemType 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

createNodeType

public BXQItemType 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 BXQItemType createProcessingInstructionType(java.lang.String nm)
                                            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:
nm - 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 BXQItemType createSchemaAttributeType(javax.xml.namespace.QName qn,
                                             int it,
                                             java.net.URI uri)
                                      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:
qn - specifies the name of the node
it - the base type of the attribute. One of the XQItemTyupe.XQBASETYPE_* constants other than XQItemType.XQBASETYPE_UNTYPED or XQItemType.XQBASETYPE_ANYTYPE
uri - 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 BXQItemType createSchemaElementType(javax.xml.namespace.QName qn,
                                           int it,
                                           java.net.URI uri)
                                    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:
qn - specifies the name of the element
it - the base type of the item. One of the XQItemType.XQBASETYPE_* constants
uri - 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 BXQSequence createSequence(java.util.Iterator it)
                           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:
it - 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, or (2) the i parameter is null

createSequence

public BXQSequence createSequence(XQSequence seq)
                           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:
seq - input sequence
Returns:
XQSequence representing a copy of the input sequence
Throws:
XQException - if (1) there are errors accessing the items in the sequence, (2) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (3) the s parameter is null

createSequenceType

public BXQItemType createSequenceType(XQItemType it,
                                      int occ)
                               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:
it - the item type. This parameter must be null if the occurance is XQSequenceType.OCC_EMPTY, and cannot be null for any other occurance indicator
occ - 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 BXQItemType 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

close

public final void close()
Closes the class.


isClosed

public final boolean isClosed()
Returns the closed flag.

Returns:
flag