io::zorba::api::xqj::ZorbaXQPreparedExpression

This class describes an expression that can be prepared for multiple subsequent executions. A prepared expression can be created from the connection.The preparation of the expression does the static analysis of the expression using the static context information.The dynamic context information, such as values for bind variables, can then be set using the setter methods. When setting values for bind variables, these variables should be present as external variables in the prolog of the prepared expression.The static type information of the query can also be retrieved if the XQuery implementation provides it using the getStaticResultType method.When the expression is executed using the executeQuery method, if the execution is successful, then an ZorbaXQResultSequence object is returned. The ZorbaXQResultSequence object is tied to the ZorbaXQPreparedExpression from which it was prepared and is closed implicitly if that expression is either closed or if re-executed.The ZorbaXQPreparedExpression object is dependent on the ZorbaXQConnection object from which it was created and is only valid for the duration of that object. Thus, if the ZorbaXQConnection object is closed then this ZorbaXQPreparedExpression object will be implicitly closed and it can no longer be used.An XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call close method explicitly to free any resources. It is also recommended that they do so under a final block to ensure that the object is closed even when there are exceptions. Not closing this object implicitly or explicitly might result in serious memory leaks.When the ZorbaXQPreparedExpression is closed any ZorbaXQResultSequence object obtained from it is also implicitly closed.Example - 
 {.java}
   ZorbaXQConnection conn = XQDataSource.getconnection();
   ZorbaXQPreparedExpression expr = conn.prepareExpression
           ("for $i in (1) return 'abc' "); 
  
   // get the sequence type out.. This would be something like xs:string *
   ZorbaXQSequenceType type = expr.getStaticResultType();
 
   XQSequence result1 = expr.executeQuery();
  
   // process the result..
   result1.next();
   System.out.println(" First result1 "+ result1.getAtomicValue());
 
   ZorbaXQResultSequence result2 = expr.executeQuery();
 
   // result1 is implicitly closed 
   // recommended to close the result sequences explicitly.
 
   // process the result..
   while (result2.next()) 
      System.out.println(" result is "+ result2.getAtomicValue());
  
   result2.close(); 
   expr.close(); // closing expression implicitly closes all result sequence or
                 // items obtained from this expression.
   conn.close(); // closing connections will close expressions and results.

Private Attributes

boolean

closed

XQConnection

connection

DynamicContext

dynamicContext

Collection< String >

itemsBounded

XQuery

query

Collection< XQResultSequence >

resultSequences

XQStaticContext

staticContext

XmlDataManager

xmlDataManager

Public Functions

void

bindAtomicValue(QName varName, String value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindBoolean(QName varName, boolean value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindByte(QName varName, byte value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindDocument(QName varName, String value, String baseURI, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindDocument(QName varName, Reader value, String baseURI, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindDocument(QName varName, InputStream value, String baseURI, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindDocument(QName varName, XMLStreamReader value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindDocument(QName varName, Source value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindDouble(QName varName, double value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindFloat(QName varName, float value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindInt(QName varName, int value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindItem(QName varName, XQItem value)

Binds a value to the given external variable.

void

bindLong(QName varName, long value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindNode(QName varName, Node value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindObject(QName varName, Object value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindSequence(QName varName, XQSequence value)

Binds a value to the given external variable or the context item.

void

bindShort(QName varName, short value, XQItemType type)

Binds a value to the given external variable or the context item.

void

bindString(QName varName, String value, XQItemType type)

Binds a value to the given external variable or the context item.

void

cancel()

Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an ZorbaXQPreparedExpression.

void

close()

Closes the expression object and release all resources associated with this prepared expression.

XQResultSequence

executeQuery()

Executes the prepared query expression.

QName[]

getAllExternalVariables()

Retrieves all the external variables defined in the prolog of the prepared expression.

QName[]

getAllUnboundExternalVariables()

Retrieves the names of all unbound external variables.

TimeZone

getImplicitTimeZone()

Gets the implicit timezone.

XQStaticContext

getStaticContext()

Gets an ZorbaXQStaticContext representing the values for all expression properties.

XQSequenceType

getStaticResultType()

Gets the static type information of the result sequence.

XQSequenceType

getStaticVariableType(QName varName)

Retrieves the static type of a given external variable.

boolean

isClosed()

Checks if the prepared expression in a closed state.

void

setImplicitTimeZone(TimeZone value)

Sets the implicit timezone.

ZorbaXQPreparedExpression(XQConnection conn, String string)

ZorbaXQPreparedExpression(XQConnection conn, Reader reader)

ZorbaXQPreparedExpression(XQConnection conn, InputStream input)

ZorbaXQPreparedExpression(XQConnection conn, String string, XQStaticContext sc)

ZorbaXQPreparedExpression(XQConnection conn, Reader reader, XQStaticContext sc)

ZorbaXQPreparedExpression(XQConnection conn, InputStream input, XQStaticContext sc)

Private Functions

void

isClosedXQException()

boolean

isExternal(String varName)

void

isNullXQException(Object value)

String

nodeToString(Node node)

Private Attributes

closed

boolean closed

connection

XQConnection connection

dynamicContext

DynamicContext dynamicContext

itemsBounded

Collection< String > itemsBounded

query

XQuery query

resultSequences

Collection< XQResultSequence > resultSequences

staticContext

XQStaticContext staticContext

xmlDataManager

XmlDataManager xmlDataManager

Public Functions

bindAtomicValue

void bindAtomicValue(QName varName, String value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is thrown either by this method or during query evaluation.

Parameters

varName - the name of the external variable to bind to
value - the lexical string value of the type
type - the item type of the bind

Parameters

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, (4) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (5) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (6) the expression is in a closed state

bindBoolean

void bindBoolean(QName varName, boolean value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindByte

void bindByte(QName varName, byte value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindDocument

void bindDocument(QName varName, String value, String baseURI, XQItemType type)

Binds a value to the given external variable or the context item.

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 conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. 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.

Parameters

varName - the name of the external variable to bind to, cannot be null
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, ZorbaXQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindDocument

void bindDocument(QName varName, Reader value, String baseURI, XQItemType type)

Binds a value to the given external variable or the context item.

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 conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. 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.

Parameters

varName - the name of the external variable to bind to, cannot be null
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, ZorbaXQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindDocument

void bindDocument(QName varName, InputStream value, String baseURI, XQItemType type)

Binds a value to the given external variable or the context item.

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 conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. 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.

Parameters

varName - the name of the external variable to bind to, cannot be null
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, ZorbaXQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindDocument

void bindDocument(QName varName, XMLStreamReader value, XQItemType type)

Binds a value to the given external variable or the context item.

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 conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. 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.

Parameters

varName - the name of the external variable to bind to, cannot be null
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, ZorbaXQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindDocument

void bindDocument(QName varName, Source value, XQItemType type)

Binds a value to the given external variable or the context item.

Binds a value to the given external variable or the context 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 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 conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. 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.

Parameters

varName - the name of the external variable to bind to, cannot be null
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, ZorbaXQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindDouble

void bindDouble(QName varName, double value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindFloat

void bindFloat(QName varName, float value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindInt

void bindInt(QName varName, int value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindItem

void bindItem(QName varName, XQItem value)

Binds a value to the given external variable.

The dynamic type of the value is derived from the ZorbaXQItem. In case of a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, cannot be null

Parameters

XQException - if (1) any of the arguments are null, (2) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (3) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, (4) the expression is in a closed state, or (5) the specified item is closed

bindLong

void bindLong(QName varName, long value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindNode

void bindNode(QName varName, Node value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindObject

void bindObject(QName varName, Object value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindSequence

void bindSequence(QName varName, XQSequence value)

Binds a value to the given external variable or the context item.

The input sequence is consumed from its current position to the end, after which the input sequence's position will be set to point after the last item. The dynamic type of the value is derived from the items in the sequence. In case of a mismatch between the static and dynamic types, an XQException is be raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, cannot be null

Parameters

XQException - if (1) any of the arguments are null, (2) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (3) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, (4) the expression is in a closed state, or (5) the specified item is closed

bindShort

void bindShort(QName varName, short value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
value - the value to be bound, 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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

bindString

void bindString(QName varName, String value, XQItemType type)

Binds a value to the given external variable or the context item.

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, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.

Parameters

varName - the name of the external variable to bind to, cannot be null
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

Parameters

XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an ZorbaXQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an ZorbaXQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

cancel

void cancel()

Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an ZorbaXQPreparedExpression.

This method can be used by one thread to cancel an ZorbaXQPreparedExpression, that is being executed in another thread. If cancellation is not supported or the attempt to cancel the execution was not successful, the method returns without any error. If the cancellation is successful, an XQException is thrown, to indicate that it has been aborted, by executeQuery, executeCommand or any method accessing the ZorbaXQResultSequence returned by executeQuery. If applicable, any open ZorbaXQResultSequence and XQResultItem objects will also be implicitly closed in this case.

Parameters

XQException - if the prepared expression is in a closed state

close

void close()

Closes the expression object and release all resources associated with this prepared expression.

This also closes any result sequences obtained from this expression. Once the expression is closed, all methods on this object other than the close or isClosed will raise exceptions. Calling close on an XQExpression object that is already closed has no effect.

Parameters

XQException - if there are errors when closing the expression

executeQuery

XQResultSequence executeQuery()

Executes the prepared query expression.

Calling this method implicitly closes any previous result sequence obtained from this expression.

Returns

the xquery sequence object containing the result of the query execution

Parameters

XQException - if (1) there are errors when executing the prepared expression, (2) the prepared expression is in a closed state, or (3) the query execution is cancelled

getAllExternalVariables

QName[] getAllExternalVariables()

Retrieves all the external variables defined in the prolog of the prepared expression.

Returns

an array of QName objects for all the external variables defined in the prolog of a prepared expression. Empty array if there are no external variables present.

Parameters

XQException - if the prepared expression is in a closed state

getAllUnboundExternalVariables

QName[] getAllUnboundExternalVariables()

Retrieves the names of all unbound external variables.

Gets the static type information of the result sequence. If an implementation does not do static typing of the query, then this method must return an ZorbaXQSequenceType object corresponding to the XQuery sequence type item()*.

Returns

ZorbaXQSequenceType containing the static result information.

Parameters

XQException - if the prepared expression is in a closed state

getImplicitTimeZone

TimeZone getImplicitTimeZone()

Gets the implicit timezone.

Returns

the implicit timezone. This may have been set by an application using the setImplicitTimeZone method or provided by the implementation

Parameters

XQException - if the expression is in a closed state

getStaticContext

XQStaticContext getStaticContext()

Gets an ZorbaXQStaticContext representing the values for all expression properties.

Note that these properties cannot be changed; in order to change, a new ZorbaXQPreparedExpression needs to be created.

Returns

an ZorbaXQStaticContext representing the values for all expression properties

Parameters

XQException - if the expression is in a closed state

getStaticResultType

XQSequenceType getStaticResultType()

Gets the static type information of the result sequence.

If an implementation does not do static typing of the query, then this method must return an ZorbaXQSequenceType object corresponding to the XQuery sequence type item()*.

Returns

ZorbaXQSequenceType containing the static result information.

Parameters

XQException - if the prepared expression is in a closed state

getStaticVariableType

XQSequenceType getStaticVariableType(QName varName)

Retrieves the static type of a given external variable.

Parameters

varName - the name of the external variable

Returns

the static type information of the variable as defined in the prolog of the prepared expression

Parameters

XQException - if (1) the variable does not exist in the static context of the expression, or (2) the sequence is in a closed state, or (3) the name parameter is null

isClosed

boolean isClosed()

Checks if the prepared expression in a closed state.

Returns

true if the prepared expression is in a closed state, false otherwise.

setImplicitTimeZone

void setImplicitTimeZone(TimeZone value)

Sets the implicit timezone.

Parameters

value - time zone to be set

Parameters

XQException - if the expression is in a closed state

ZorbaXQPreparedExpression

 ZorbaXQPreparedExpression(XQConnection conn, String string)

ZorbaXQPreparedExpression

 ZorbaXQPreparedExpression(XQConnection conn, Reader reader)

ZorbaXQPreparedExpression

 ZorbaXQPreparedExpression(XQConnection conn, InputStream input)

ZorbaXQPreparedExpression

 ZorbaXQPreparedExpression(XQConnection conn, String string, XQStaticContext sc)

ZorbaXQPreparedExpression

 ZorbaXQPreparedExpression(XQConnection conn, Reader reader, XQStaticContext sc)

ZorbaXQPreparedExpression

 ZorbaXQPreparedExpression(XQConnection conn, InputStream input, XQStaticContext sc)

Private Functions

isClosedXQException

void isClosedXQException()

isExternal

boolean isExternal(String varName)

isNullXQException

void isNullXQException(Object value)

nodeToString

String nodeToString(Node node)