Interface XQConnection
- All Superinterfaces:
XQDataFactory
- All Known Implementing Classes:
SaxonXQConnection
XQDataSource
object.
XQuery expressions are executed and results are returned within the
context of a connection. They are either executed through XQExpression
or XQPreparedExpression
objects.
XQDataSource ds;// obtain the XQuery datasource ... XQConnection conn = ds.getConnection(); XQPreparedExpression expr = conn.prepareExpression("for $i in ..."); XQResultSequence result = expr.executeQuery(); // - or - XQExpression expr = conn.createExpression(); XQSequence result = expr.executeQuery("for $i in.."); // The sequence can now be iterated while (result.next()) { String str = result.getItemAsString(); System.out.println(" output "+ str); } result.close(); expr.close(); conn.close(); // close the connection and free all resources..
A connection holds also default values for XQExpression
and
XQPreparedExpression
properties. An application can
override these defaults by passing an XQStaticContext
object to the setStaticContext()
method.
By default a connection operates in auto-commit mode, which means that
each xquery is executed and committed in an individual transaction. If
auto-commit mode is disabled, a transaction must be ended explicitly by
the application calling commit()
or
rollback()
.
An XQConnection
object can be created on top of an
existing JDBC connection. If an XQConnection
is
created on top of the JDBC connection, it inherits the transaction context
from the JDBC connection. Also, in this case, if the auto-commit mode is
changed, or a transaction is ended using commit or rollback,
it also changes the underlying JDBC connection.
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 explicitly might result in serious memory leaks.
When the XQConnection
is closed any XQExpression
and XQPreparedExpression
objects obtained from it are also
implicitly closed.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Closes the connection.void
commit()
Makes all changes made in the current transaction permanent and releases any locks held by the datasource.Creates a newXQExpression
object that can be used to perform execute immediate operations with XQuery expressions.createExpression
(XQStaticContext properties) Creates a newXQExpression
object that can be used to perform execute immediate operations with XQuery expressions.boolean
Gets the auto-commit attribute of this connectionGets the metadata for this connection.Gets anXQStaticContext
representing the default values for all expression properties.boolean
isClosed()
Checks if the connection is closed.prepareExpression
(InputStream xquery) Prepares an expression for execution.prepareExpression
(InputStream xquery, XQStaticContext properties) Prepares an expression for execution.prepareExpression
(Reader xquery) Prepares an expression for execution.prepareExpression
(Reader xquery, XQStaticContext properties) Prepares an expression for execution.prepareExpression
(String xquery) Prepares an expression for execution.prepareExpression
(String xquery, XQStaticContext properties) Prepares an expression for execution.void
rollback()
Undoes all changes made in the current transaction and releases any locks held by the datasource.void
setAutoCommit
(boolean autoCommit) Sets the auto-commit attribute to the given state.void
setStaticContext
(XQStaticContext properties) Sets the default values for all expression properties.Methods inherited from interface javax.xml.xquery.XQDataFactory
createAtomicType, createAtomicType, createAttributeType, createAttributeType, createCommentType, createDocumentElementType, createDocumentSchemaElementType, createDocumentType, createElementType, createElementType, createItem, createItemFromAtomicValue, createItemFromBoolean, createItemFromByte, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDouble, createItemFromFloat, createItemFromInt, createItemFromLong, createItemFromNode, createItemFromObject, createItemFromShort, createItemFromString, createItemType, createNodeType, createProcessingInstructionType, createSchemaAttributeType, createSchemaElementType, createSequence, createSequence, createSequenceType, createTextType
-
Method Details
-
close
Closes the connection. This also closes anyXQExpression
andXQPreparedExpression
obtained from this connection. Once the connection is closed, no method other thanclose
or theisClosed
method may be called on the connection object. Calling close on anXQConnection
object that is already closed has no effect.Note that an XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call this 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.
- Throws:
XQException
- if there is an error during closing the connection.
-
setAutoCommit
Sets the auto-commit attribute to the given state. If a connection is in auto-commit mode, each xquery is executed and committed in an individual transaction. When auto-commit mode is disabled, xqueries are grouped in a transaction that must be ended explicitly by the application callingcommit()
orrollback()
.
By default, new connections are in auto-commit mode.
If the value of auto-commit is changed in the middle of a transaction, the transaction is committed. If
setAutoCommit
is called and the auto-commit attribute is not changed from its current value, the request is treated as a no-op.- Parameters:
autoCommit
-true
to enable auto-commit mode;false
to disable it- Throws:
XQException
- if (1) the connection is in a closed state, or (2) auto-commit is turned off but the implementation doesn't support transactions
-
getAutoCommit
Gets the auto-commit attribute of this connection- Returns:
- the auto-commit attribute of this connection.
true
if the connection operates in auto-commit mode; otherwisefalse
- Throws:
XQException
- if the connection is in a closed state
-
commit
Makes all changes made in the current transaction permanent and releases any locks held by the datasource. This method should be used only when auto-commit mode is disabled.Any
XQResultSequence
, orXQResultItem
may be implicitly closed upon commit, if the holdability property of the sequence is set toXQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT
.- Throws:
XQException
- if the connection is in a closed state or this connection is operating in auto-commit mode
-
createExpression
Creates a newXQExpression
object that can be used to perform execute immediate operations with XQuery expressions. The properties of the connection's defaultXQStaticContext
are copied to the returnedXQExpression
.- Returns:
XQExpression
that can be used to execute multiple expressions- Throws:
XQException
- if the connection is in a closed state
-
createExpression
Creates a newXQExpression
object that can be used to perform execute immediate operations with XQuery expressions. The properties of the specifiedXQStaticContext
values are copied to the returnedXQExpression
.- Parameters:
properties
-XQStaticContext
containing values of expression properties- Returns:
XQExpression
that can be used to execute multiple expressions- Throws:
XQException
- if (1) the connection is in a closed state, or (2) the specified argument isnull
-
getMetaData
Gets the metadata for this connection.- Returns:
XQMetadata
representing the metadata of this connection- Throws:
XQException
- if the connection is in a closed state
-
isClosed
boolean isClosed()Checks if the connection is closed.- Returns:
true
if the connection is in a closed state,false
otherwise
-
prepareExpression
Prepares an expression for execution.The properties of the connection's default
XQStaticContext
are copied to the returnedXQPreparedExpression
.- Parameters:
xquery
- the XQuery expression as aString
. Cannot benull
- Returns:
- the prepared XQuery expression
- Throws:
XQException
- if (1) the connection is in a closed state, (2) there are errors preparing the expression, or (3) the xquery parameter isnull
-
prepareExpression
XQPreparedExpression prepareExpression(String xquery, XQStaticContext properties) throws XQException Prepares an expression for execution.The properties of the specified
XQStaticContext
values are copied to the returnedXQPreparedExpression
.- Parameters:
xquery
- the XQuery expression as aString
. Cannot benull
properties
-XQStaticContext
containing values of expression properties.- Returns:
- the prepared XQuery expression
- Throws:
XQException
- if (1) the connection is in a closed state, or (2) the specified argument isnull
-
prepareExpression
Prepares an expression for execution.The properties of the connection's default
XQStaticContext
are copied to the returnedXQPreparedExpression
.- Parameters:
xquery
- the XQuery expression as aReader
. Cannot benull
- Returns:
- the prepared XQuery expression
- Throws:
XQException
- if (1) the connection is in a closed state, (2) there are errors preparing the expression, or (3) the xquery parameter isnull
-
prepareExpression
XQPreparedExpression prepareExpression(Reader xquery, XQStaticContext properties) throws XQException Prepares an expression for execution.The properties of the specified
XQStaticContext
values are copied to the returnedXQPreparedExpression
.- Parameters:
xquery
- the XQuery expression as aReader
. Cannot benull
properties
-XQStaticContext
containing values of expression properties- Returns:
- the prepared XQuery expression
- Throws:
XQException
- if (1) the connection is in a closed state, or (2) the specified argument isnull
-
prepareExpression
Prepares an expression for execution.The properties of the connection's default
XQStaticContext
are copied to the returnedXQPreparedExpression
.- Parameters:
xquery
- the XQuery expression as anInputStream
. Cannot benull
- Returns:
- the prepared XQuery expression
- Throws:
XQException
- if (1) the connection is in a closed state, (2) there are errors preparing the expression or (3) the xquery parameter isnull
-
prepareExpression
XQPreparedExpression prepareExpression(InputStream xquery, XQStaticContext properties) throws XQException Prepares an expression for execution.The properties of the specified
XQStaticContext
values are copied to the returnedXQPreparedExpression
.- Parameters:
xquery
- the XQuery expression as anInputStream
. Cannot benull
properties
-XQStaticContext
containing values of expression properties- Returns:
- the prepared XQuery expression
- Throws:
XQException
- if (1) the connection is in a closed state, or (2) the specified argument isnull
-
rollback
Undoes all changes made in the current transaction and releases any locks held by the datasource. This method should be used only when auto-commit mode is disabled.- Throws:
XQException
- if the connection is in a closed state or this connection is operating in auto-commit mode
-
getStaticContext
Gets anXQStaticContext
representing the default values for all expression properties. In order to modify the defaults, it is not sufficient to modify the values in the returnedXQStaticContext
object; in additionsetStaticContext
should be called to make those new values effective.- Returns:
XQStaticContext
representing the default values for all expression properties- Throws:
XQException
- if the connection is in a closed state
-
setStaticContext
Sets the default values for all expression properties. The implementation will read out all expression properties from the specifiedXQStaticContext
and update its private copy.- Parameters:
properties
-XQStaticContext
containing values of expression properties- Throws:
XQException
- if the connection is in a closed state
-