javax.xml.xquery
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:
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");
bindXXX()
method, use
XQConstants.CONTEXT_ITEM
as the first
argument.
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();
// BINDING_MODE_IMMEDIATE is the default, change it to // BINDING_MODE_DEFERRED XQStaticContext cntxt = c.getStaticContext(); cntxt.setBindingMode(XQConstants.BINDING_MODE_DEFERRED); c.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, 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
from the given Source . |
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
|
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
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 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
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
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 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
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
null
,
XQITEMKIND_DOCUMENT_ELEMENT
, or
XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT
.
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,
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))
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
null
,
XQITEMKIND_DOCUMENT_ELEMENT
, or
XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT
.
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,
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))
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
null
,
XQITEMKIND_DOCUMENT_ELEMENT
, or
XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT
.
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,
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))
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
null
,
XQITEMKIND_DOCUMENT_ELEMENT
or XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT
.
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 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))
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
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
null
,
XQITEMKIND_DOCUMENT_ELEMENT
, or
XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT
.
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 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))
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
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 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
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
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 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
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
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 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
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
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, (4) the expression is in a closed state,
or (5) the specified item is closed
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 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
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
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
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
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, (4) the expression is in a closed
state, or (5) the specified sequence is closed
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 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
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
xs:string
or a type derived by restriction
from xs:string
. If the specified type is null
,
it defaults to xs:string
.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
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
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
Parameters: implicitTimeZone time zone to be set
Throws: XQException if the expression is in a closed state