com.ddtek.xquery3
Interface XQDynamicContext

All Known Subinterfaces:

XQExpression, XQPreparedExpression

public interface XQDynamicContext

XQDynamicContext provides access to the dynamic context as defined in 2.1.2 Dynamic Context, XQuery 1.0: An XML Query Language. The following components can be accessed:

• The context item can be set
• The variable values can be bound
• The implicit time zone can be retrieved or specified

Where the prolog of the expression specifies the static type of external variables, this interface allows the dynamic type and value of the variable to be specified. Note that in case of an XQPreparedExpression, values may only be bound to those variables that are defined in the prolog of the expression.

Example -

  XQConnection conn = XQDataSource.getConnection();

  // create an XQPreparedExpression with external variable
  XQPreparedExpression e1 = conn.prepareExpression("declare variable $i as xs:int external;
                                                    $i + 10");

  // bind an int to the external variable
  e1.bindInt(new QName("i"), 200, null);

  // this will fail as the expression has no external variable $foo
  e1.bindInt(new QName("foo"), 200, null); 

  // this will fail as xs:double is not compatible with an external
  variable declared as xs:int
  e1.bindDouble(new QName("i"), 2e2, null);

  // create an XQExpression with external variable

  XQExpression e2 = conn.createExpression();

  // bind a value to $i and $foo
  e2.bindInt(new QName("i"), 200, null); 
  e2.bindInt(new QName("foo"), 200, null);

  // the value bound to $foo is ignored as the expression doesn't
  // declare $foo as external variable

  e2.executeQuery("declare variable $i as xs:int external; $i + 10");

 

Binding a value to the context item is achieved in the same way as binding a value to an external variable. However, instead of specifying the variable's name as first argument of the bindXXX() method, use XQConstants.CONTEXT_ITEM as the first argument.

Binding mode

The default binding mode is immediate. In other words, the external variable value specified by the application is consumed during the bindXXX() method.

An application has the ability to set the binding mode to deferred. In deferred mode an application cannot assume that the bound value will be consumed during the invocation of the bindXXX method. In such scenario the order in which the bindings are evaluated is implementation-dependent, and an implementation doesn't necessarily need to consume a binding if it can evaluate the query without requiring the external variable. The XQJ implementation is also free to read the bound value either at bind time or during the subsequent evaluation and processing of the query results.

Also note that in deferred binding mode, bindings are only active for a single execution cycle. The application is required to explicitly re-bind values to every external variable before each execution. Failing to do so will result in an XQException, as the implementation will assume during the next execution that none of the external variables are bound.

Finally, note that in deferred binding mode, any error condition specified to throw an exception during the bindXXX() methods, may as well be thrown later during the query's evaluation.

Example - in case of an immediate binding mode, bindings stay active over executions

  // BINDING_MODE_IMMEDIATE is the default, no need to change it
  QName v = new QName(v);

  XQPreparedExpression e = c.prepareExpression("declare variable $v
                                                external; $v");
  e.bindInt(v, 1)

  // successful execution
  e.executeQuery();

  // successful execution
  e.executeQuery(); 
 

Example - in case of a deferred binding mode, bindings are only valid for a single execution

  // BINDING_MODE_IMMEDIATE is the default, change it to
  // BINDING_MODE_DEFERRED
  XQStaticContext cntxt = conn.getStaticContext();
  cntxt.setBindingMode(XQConstants.BINDING_MODE_DEFERRED);
  conn.setStaticContext(cntxt);

  QName v = new QName(v);

  XQPreparedExpression e = c.prepareExpression("declare variable $v
                                                external; $v");
  e.bindInt(v, 1)

  // successful execution
  XQSequence s = e.executeQuery();

  while (s.next())
    System.out.println(s.getInt());

  // an error is reported during the next query
  // evaluation as not all external variables are bound
  s = e.executeQuery(); 

  while (s.next())
    System.out.println(s.getInt());
 

Method Summary

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, InputStream value) Binds a value to the given external variable or the context item.
void	bindDocument(QName varName, Reader value) Binds a value to the given external variable or the context item.
void	bindDocument(QName varName, Source value) Binds a value to the given external variable or the context item.
void	bindDocument(QName varName, String value) Binds a value to the given external variable or the context item.
void	bindDocument(QName varName, XMLReader value) Binds a value to the given external variable.
void	bindDocument(QName varName, XMLStreamReader value) 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.
TimeZone	getImplicitTimeZone() Gets the implicit timezone
void	setImplicitTimeZone(TimeZone implicitTimeZone) Sets the implicit timezone

Method Detail

getImplicitTimeZone

public TimeZone getImplicitTimeZone()
                             throws XQException

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

Throws:

XQException - if the expression is in a closed state.

bindAtomicValue

public void bindAtomicValue(QName varName,
                            String value,
                            XQItemType type)
                     throws XQException

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

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

bindDocument

public void bindDocument(QName varName,
                         String value)
                  throws XQException

Binds a value to the given external variable or the context item. The value must represent a well-formed XML document, will be parsed and results in a document node. If the value does not represent a well formed XML document then the implementation may raise an XQException. 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

Throws:

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

bindDocument

public void bindDocument(QName varName,
                         Reader value)
                  throws XQException

Binds a value to the given external variable or the context item. The value must represent a well-formed XML document, will be parsed and results in a document node. If the value does not represent a well formed XML document then the implementation may raise an XQException. 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

Throws:

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

bindDocument

public void bindDocument(QName varName,
                         InputStream value)
                  throws XQException

Binds a value to the given external variable or the context item. The value must represent a well-formed XML document, will be parsed and results in a document node. If the value does not represent a well formed XML document then the implementation may raise an XQException. 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

Throws:

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

bindDocument

public void bindDocument(QName varName,
                         XMLReader value)
                  throws XQException

Binds a value to the given external variable. The XMLReader must produce a well-formed XML document. 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 the execute method.

The contract of this method is as follows. First a ContentHandler is passed to the XML XMLReader; and optionally an implementation can specify additional handlers like a LexicalHandler. Subsequently parse(String systemId) will be invoked; and as such the XMLReader will pass the SAX event representing the document to bind. The systemId argument identifies the external variable, a QName formatted into a String using the James Clark representation.

Example - the application loads an XML document (foo.xml) using a SAX parser, this document is bound to an external variable. The XQuery returns all foo elements in the document, which are written to stdout. Assume there is an XQConnection connection...

  ...

  // Create an XMLReader, which will pass the SAX events to the XQJ
  // implementation 
  XMLFilter xmlReader = new XMLFilterImpl() {

    public void parse(String systemId) throws IOException,
    SAXException {

       // foo.xml is the XML document to bind 
       super.parse("foo.xml");

      }        

    };

  // The parent XML Reader is a SAX parser, which will do the
  // actual work of parsing the XML document
  xmlReader.setParent(org.xml.sax.helpers.XMLReaderFactory.createXMLReader());

  // Create an XQPreparedExpression
  XQPreparedExpression e =  connection.prepareExpression("declare variable $doc as
                       document-node(element(*, xs:untyped)) external; $doc//foo));

  e.bindDocument(new QName("doc"), xmlReader);

  XQResultSequence result = preparedExpression.executeQuery();

  result.writeSequence(System.out);
  ...
 

Parameters:

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

value - the XMLReader producing SAX events representing the document to bind

Throws:

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

bindDocument

public void bindDocument(QName varName,
                         XMLStreamReader value)
                  throws XQException

Binds a value to the given external variable or the context item. The value represent an XML document (not necessarily well formed), and is converted in a document node. If the value does not represent a well formed XML document then the implementation may raise an XQException. 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

Throws:

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

bindDocument

public void bindDocument(QName varName,
                         Source value)
                  throws XQException

Binds a value to the given external variable or the context item. 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 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

Throws:

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

setImplicitTimeZone

public void setImplicitTimeZone(TimeZone implicitTimeZone)
                         throws XQException

Sets the implicit timezone

Parameters:

implicitTimeZone - time zone to be set

Throws:

XQException - if (1) the argument is or (2) the expression is in a closed state

bindItem

public void bindItem(QName varName,
                     XQItem value)
              throws XQException

Binds a value to the given external variable. The dynamic type of the value is derived from the XQItem. 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

Throws:

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

bindSequence

public void bindSequence(QName varName,
                         XQSequence value)
                  throws XQException

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

Throws:

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

bindObject

public void bindObject(QName varName,
                       Object value,
                       XQItemType type)
                throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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

bindBoolean

public void bindBoolean(QName varName,
                        boolean value,
                        XQItemType type)
                 throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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

bindByte

public void bindByte(QName varName,
                     byte value,
                     XQItemType type)
              throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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

bindDouble

public void bindDouble(QName varName,
                       double value,
                       XQItemType type)
                throws XQException

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 6.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 evaluations.

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 of the value is used in case null is specified

Throws:

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

bindFloat

public void bindFloat(QName varName,
                      float value,
                      XQItemType type)
               throws XQException

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 6.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 evaluations.

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 of the value is used in case null is specified

Throws:

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

bindInt

public void bindInt(QName varName,
                    int value,
                    XQItemType type)
             throws XQException

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 6.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 evaluations.

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 of the value is used in case null is specified

Throws:

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

bindLong

public void bindLong(QName varName,
                     long value,
                     XQItemType type)
              throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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

bindNode

public void bindNode(QName varName,
                     Node value,
                     XQItemType type)
              throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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

bindShort

public void bindShort(QName varName,
                      short value,
                      XQItemType type)
               throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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

bindString

public void bindString(QName varName,
                       String value,
                       XQItemType type)
                throws XQException

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 6.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 of the value is used in case null is specified

Throws:

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