|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface XQConnection
A connection (session) with a specific XQuery engine. Connections are
obtained through an 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 | |
---|---|
void |
close()
Closes the connection. |
void |
commit()
Makes all changes made in the current transaction permanent and releases any locks held by the datasource. |
XQExpression |
createExpression()
Creates a new XQExpression object that can be used
to perform execute immediate operations with XQuery expressions. |
XQExpression |
createExpression(XQStaticContext properties)
Creates a new XQExpression object that can be used to
perform execute immediate operations with XQuery expressions. |
boolean |
getAutoCommit()
Gets the auto-commit attribute of this connection |
XQMetaData |
getMetaData()
Gets the metadata for this connection. |
XQStaticContext |
getStaticContext()
Gets an XQStaticContext representing the default values for
all expression properties. |
boolean |
isClosed()
Checks if the connection is closed. |
XQPreparedExpression |
prepareExpression(InputStream xquery)
Prepares an expression for execution. |
XQPreparedExpression |
prepareExpression(InputStream xquery,
XQStaticContext properties)
Prepares an expression for execution. |
XQPreparedExpression |
prepareExpression(Reader xquery)
Prepares an expression for execution. |
XQPreparedExpression |
prepareExpression(Reader xquery,
XQStaticContext properties)
Prepares an expression for execution. |
XQPreparedExpression |
prepareExpression(String xquery)
Prepares an expression for execution. |
XQPreparedExpression |
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. |
Method Detail |
---|
void close() throws XQException
XQExpression
and
XQPreparedExpression
obtained from this connection.
Once the connection is closed, no method other than close
or the isClosed
method may be called on the connection object.
Calling close on an XQConnection
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.
XQException
- if there is an error during closing the connection.void setAutoCommit(boolean autoCommit) throws XQException
commit()
or rollback()
.setAutoCommit
is called and the auto-commit attribute is not changed from its
current value, the request is treated as a no-op.
autoCommit
- true
to enable auto-commit mode;
false
to disable it
XQException
- if (1) the connection is in a closed state,
or (2) auto-commit is turned off but the
implementation doesn't support transactionsboolean getAutoCommit() throws XQException
true
if the connection operates
in auto-commit mode; otherwise false
XQException
- if the connection is in a closed statevoid commit() throws XQException
XQResultSequence
, or XQResultItem
may be
implicitly closed upon commit, if the holdability property of the
sequence is set to XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT
.
XQException
- if the connection is in a closed state
or this connection is operating in auto-commit modeXQExpression createExpression() throws XQException
XQExpression
object that can be used
to perform execute immediate operations with XQuery expressions.
The properties of the connection's default XQStaticContext
are
copied to the returned XQExpression
.
XQExpression
that can be used to execute
multiple expressions
XQException
- if the connection is in a closed stateXQExpression createExpression(XQStaticContext properties) throws XQException
XQExpression
object that can be used to
perform execute immediate operations with XQuery expressions. The
properties of the specified XQStaticContext
values are
copied to the returned XQExpression
.
properties
- XQStaticContext
containing
values of expression properties
XQExpression
that can be used to execute
multiple expressions
XQException
- if (1) the connection is in a closed state, or
(2) the specified argument is null
XQMetaData getMetaData() throws XQException
XQMetadata
representing the metadata of
this connection
XQException
- if the connection is in a closed stateboolean isClosed()
true
if the connection is in a closed state,
false
otherwiseXQPreparedExpression prepareExpression(String xquery) throws XQException
The properties of the connection's default XQStaticContext
are
copied to the returned XQPreparedExpression
.
xquery
- the XQuery expression as a String
.
Cannot be null
XQException
- if (1) the connection is in a closed state,
(2) there are errors preparing the expression,
or (3) the xquery parameter is null
XQPreparedExpression prepareExpression(String xquery, XQStaticContext properties) throws XQException
The properties of the specified XQStaticContext
values are
copied to the returned XQPreparedExpression
.
xquery
- the XQuery expression as a String
.
Cannot be null
properties
- XQStaticContext
containing
values of expression properties.
XQException
- if (1) the connection is in a closed state, or
(2) the specified argument is null
XQPreparedExpression prepareExpression(Reader xquery) throws XQException
The properties of the connection's default XQStaticContext
are
copied to the returned XQPreparedExpression
.
xquery
- the XQuery expression as a Reader
.
Cannot be null
XQException
- if (1) the connection is in a closed state,
(2) there are errors preparing the expression,
or (3) the xquery parameter is null
XQPreparedExpression prepareExpression(Reader xquery, XQStaticContext properties) throws XQException
The properties of the specified XQStaticContext
values are
copied to the returned XQPreparedExpression
.
xquery
- the XQuery expression as a Reader
.
Cannot be null
properties
- XQStaticContext
containing
values of expression properties
XQException
- if (1) the connection is in a closed state, or
(2) the specified argument is null
XQPreparedExpression prepareExpression(InputStream xquery) throws XQException
The properties of the connection's default XQStaticContext
are
copied to the returned XQPreparedExpression
.
xquery
- the XQuery expression as an InputStream
.
Cannot be null
XQException
- if (1) the connection is in a closed state,
(2) there are errors preparing the expression
or (3) the xquery parameter is null
XQPreparedExpression prepareExpression(InputStream xquery, XQStaticContext properties) throws XQException
The properties of the specified XQStaticContext
values are
copied to the returned XQPreparedExpression
.
xquery
- the XQuery expression as an InputStream
.
Cannot be null
properties
- XQStaticContext
containing
values of expression properties
XQException
- if (1) the connection is in a closed state, or
(2) the specified argument is null
void rollback() throws XQException
XQException
- if the connection is in a closed state
or this connection is operating
in auto-commit modeXQStaticContext getStaticContext() throws XQException
XQStaticContext
representing the default values for
all expression properties. In order to modify the defaults, it is not
sufficient to modify the values in the returned
XQStaticContext
object; in addition
setStaticContext
should be called to make those new values
effective.
XQStaticContext
representing the
default values for all expression properties
XQException
- if the connection is in a closed statevoid setStaticContext(XQStaticContext properties) throws XQException
XQStaticContext
and update its private copy.
properties
- XQStaticContext
containing
values of expression properties
XQException
- if the connection is in a closed state
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |