Package javax.xml.xquery
Interface XQConnection
-
- All Superinterfaces:
XQDataFactory
- All Known Implementing Classes:
SaxonXQConnection
public interface XQConnection extends XQDataFactory
A connection (session) with a specific XQuery engine. Connections are obtained through anXQDataSourceobject. XQuery expressions are executed and results are returned within the context of a connection. They are either executed throughXQExpressionorXQPreparedExpressionobjects.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 forXQExpressionandXQPreparedExpressionproperties. An application can override these defaults by passing anXQStaticContextobject to thesetStaticContext()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 callingcommit()orrollback(). AnXQConnectionobject can be created on top of an existing JDBC connection. If anXQConnectionis 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 theXQConnectionis closed anyXQExpressionandXQPreparedExpressionobjects obtained from it are also implicitly closed.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidclose()Closes the connection.voidcommit()Makes all changes made in the current transaction permanent and releases any locks held by the datasource.XQExpressioncreateExpression()Creates a newXQExpressionobject that can be used to perform execute immediate operations with XQuery expressions.XQExpressioncreateExpression(XQStaticContext properties)Creates a newXQExpressionobject that can be used to perform execute immediate operations with XQuery expressions.booleangetAutoCommit()Gets the auto-commit attribute of this connectionXQMetaDatagetMetaData()Gets the metadata for this connection.XQStaticContextgetStaticContext()Gets anXQStaticContextrepresenting the default values for all expression properties.booleanisClosed()Checks if the connection is closed.XQPreparedExpressionprepareExpression(java.io.InputStream xquery)Prepares an expression for execution.XQPreparedExpressionprepareExpression(java.io.InputStream xquery, XQStaticContext properties)Prepares an expression for execution.XQPreparedExpressionprepareExpression(java.io.Reader xquery)Prepares an expression for execution.XQPreparedExpressionprepareExpression(java.io.Reader xquery, XQStaticContext properties)Prepares an expression for execution.XQPreparedExpressionprepareExpression(java.lang.String xquery)Prepares an expression for execution.XQPreparedExpressionprepareExpression(java.lang.String xquery, XQStaticContext properties)Prepares an expression for execution.voidrollback()Undoes all changes made in the current transaction and releases any locks held by the datasource.voidsetAutoCommit(boolean autoCommit)Sets the auto-commit attribute to the given state.voidsetStaticContext(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 Detail
-
close
void close() throws XQExceptionCloses the connection. This also closes anyXQExpressionandXQPreparedExpressionobtained from this connection. Once the connection is closed, no method other thancloseor theisClosedmethod may be called on the connection object. Calling close on anXQConnectionobject 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
void setAutoCommit(boolean autoCommit) throws XQExceptionSets 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. IfsetAutoCommitis called and the auto-commit attribute is not changed from its current value, the request is treated as a no-op.- Parameters:
autoCommit-trueto enable auto-commit mode;falseto 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
boolean getAutoCommit() throws XQExceptionGets the auto-commit attribute of this connection- Returns:
- the auto-commit attribute of this connection.
trueif the connection operates in auto-commit mode; otherwisefalse - Throws:
XQException- if the connection is in a closed state
-
commit
void commit() throws XQExceptionMakes 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. AnyXQResultSequence, orXQResultItemmay 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
XQExpression createExpression() throws XQException
Creates a newXQExpressionobject that can be used to perform execute immediate operations with XQuery expressions. The properties of the connection's defaultXQStaticContextare copied to the returnedXQExpression.- Returns:
XQExpressionthat can be used to execute multiple expressions- Throws:
XQException- if the connection is in a closed state
-
createExpression
XQExpression createExpression(XQStaticContext properties) throws XQException
Creates a newXQExpressionobject that can be used to perform execute immediate operations with XQuery expressions. The properties of the specifiedXQStaticContextvalues are copied to the returnedXQExpression.- Parameters:
properties-XQStaticContextcontaining values of expression properties- Returns:
XQExpressionthat 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
XQMetaData getMetaData() throws XQException
Gets the metadata for this connection.- Returns:
XQMetadatarepresenting 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:
trueif the connection is in a closed state,falseotherwise
-
prepareExpression
XQPreparedExpression prepareExpression(java.lang.String xquery) throws XQException
Prepares an expression for execution.
The properties of the connection's defaultXQStaticContextare 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(java.lang.String xquery, XQStaticContext properties) throws XQException
Prepares an expression for execution.
The properties of the specifiedXQStaticContextvalues are copied to the returnedXQPreparedExpression.- Parameters:
xquery- the XQuery expression as aString. Cannot benullproperties-XQStaticContextcontaining 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
XQPreparedExpression prepareExpression(java.io.Reader xquery) throws XQException
Prepares an expression for execution.
The properties of the connection's defaultXQStaticContextare 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(java.io.Reader xquery, XQStaticContext properties) throws XQException
Prepares an expression for execution.
The properties of the specifiedXQStaticContextvalues are copied to the returnedXQPreparedExpression.- Parameters:
xquery- the XQuery expression as aReader. Cannot benullproperties-XQStaticContextcontaining 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
XQPreparedExpression prepareExpression(java.io.InputStream xquery) throws XQException
Prepares an expression for execution.
The properties of the connection's defaultXQStaticContextare 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(java.io.InputStream xquery, XQStaticContext properties) throws XQException
Prepares an expression for execution.
The properties of the specifiedXQStaticContextvalues are copied to the returnedXQPreparedExpression.- Parameters:
xquery- the XQuery expression as anInputStream. Cannot benullproperties-XQStaticContextcontaining 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
void rollback() throws XQExceptionUndoes 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
XQStaticContext getStaticContext() throws XQException
Gets anXQStaticContextrepresenting the default values for all expression properties. In order to modify the defaults, it is not sufficient to modify the values in the returnedXQStaticContextobject; in additionsetStaticContextshould be called to make those new values effective.- Returns:
XQStaticContextrepresenting the default values for all expression properties- Throws:
XQException- if the connection is in a closed state
-
setStaticContext
void setStaticContext(XQStaticContext properties) throws XQException
Sets the default values for all expression properties. The implementation will read out all expression properties from the specifiedXQStaticContextand update its private copy.- Parameters:
properties-XQStaticContextcontaining values of expression properties- Throws:
XQException- if the connection is in a closed state
-
-