com.ddtek.xquery3
Interface XQConnection

All Superinterfaces:

XQDataFactory

public interface XQConnection

extends XQDataFactory

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 has the following properties. These properties affect the sequences obtained through the execution of XQuery expressions in the context of the connection.

• Scrollability - indicates if the sequences can be read in a forward only manner, you can iterate through it only once and only from the first item to the last. Or if the produced sequences are scrollable.
• Updatability - indicates if the returned sequences are updatable or not. Note that the current version only supports read-only sequences.
• Holdability - indicates if the result sequence can be held beyond the transaction in which the expression was evaluated.

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.

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(). When the XQConnection is closed any XQExpression and XQPreparedExpression objects obtained from it are also implicitly closed.

Method Summary

void	clearWarnings() Clears the list of warnings associated with this connection.
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 staticContext) 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.
String	getMetaDataProperty(String key) Gets the value of the connection property indicated by the specified key.
XQStaticContext	getStaticContext() Gets an XQStaticContext representing the default values for all expression properties.
String[]	getSupportedMetaDataPropertyNames() Determines the property names supported by this connection.
XQWarning	getWarnings() Gets the first warning in a chained list of warnings associated with this connection.
boolean	isClosed() Checks if the connection is closed.
XQPreparedExpression	prepareExpression(InputStream xquery) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(InputStream xquery, XQStaticContext staticContext) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(Reader xquery) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(Reader xquery, XQStaticContext staticContext) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(String xquery) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(String xquery, XQStaticContext staticContext) 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 staticContext) Sets the default values for all expression properties.

Methods inherited from interface com.ddtek.xquery3.XQDataFactory

createAtomicType, createAttributeType, createAttributeType, createCommentType, createDocumentElementType, createDocumentType, createElementType, createElementType, createItem, createItemFromAtomicValue, createItemFromBoolean, createItemFromByte, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDocument, createItemFromDouble, createItemFromFloat, createItemFromInt, createItemFromLong, createItemFromNode, createItemFromObject, createItemFromShort, createItemFromString, createItemType, createNodeType, createProcessingInstructionType, createSequence, createSequence, createSequenceType, createTextType

Method Detail

close

public void close()
           throws XQException

Closes the connection. This also closes any 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.

Throws:

XQException - if there is an error during closing the connection.

commit

public void commit()
            throws XQException

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, or XQResultItem may be implicitly closed upon commit, if the holdability property of the sequence is set to XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT.

Throws:

XQException - if the connection is in a closed state or this connection is operating in auto-commit mode.

clearWarnings

public void clearWarnings()
                   throws XQException

Clears the list of warnings associated with this connection.

Throws:

XQException - if the connection is in a closed state.

createExpression

public XQExpression createExpression()
                              throws XQException

Creates a new 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.

Returns:

XQExpression that can be used to execute multiple expressions

Throws:

XQException - if the connection is in a closed state

createExpression

public XQExpression createExpression(XQStaticContext staticContext)
                              throws XQException

Creates a new 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.

Parameters:

staticContext - an XQStaticContext representing the default values for this expression

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 is null

getSupportedMetaDataPropertyNames

public String[] getSupportedMetaDataPropertyNames()
                                           throws XQException

Determines the property names supported by this connection. The following keys must be supported by all XQJ implementations. Other properties may also be supported by the implementation.

Key	Description of Associated Value
com.ddtek.xquery3.metadata.ProductVersion	XQuery Product Version
com.ddtek.xquery3.metadata.ProductName	XQuery Product Name
com.ddtek.xquery3.metadata.XQJVersion	XQuery API for Java Version
com.ddtek.xquery3.metadata.SchemaImportSupported	Whether Schema Import feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.StaticTypingSupported	Whether Static Typing feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.FullAxisSupported	Whether Full Axis feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.ModuleSupported	Whether Module feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.PragmaSupported	Whether Pragma feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.MustUnderstandExtensionsSupported	Whether Must Understand Extensions feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.StaticTypingExtensionsSupported	Whether Static Typing Extensions feature is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.XQueryXSupported	Whether XQueryX is supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.CollectionNestingSupported	Whether Nested Collections are supported ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.ReadOnly	Whether the connection is a read only connection ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.TransactionSupported	Whether the connection supports transactions ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.CreatedFromJDBCConnection	Whether the connection was created from an existing JDBC connection ('true' indicates yes and 'false' indicates no)
com.ddtek.xquery3.metadata.MaxExpressionLength	String representation of the maximum length of the xquery string supported on this connection. A value of zero means that there is no limit or the limit is unknown
com.ddtek.xquery3.metadata.MaxUserNameLength	String representing the maximum length of a valid user-name on this connection. A value of zero means that there is no limit or the limit is unknown
com.ddtek.xquery3.metadata.UserName	The user-name of this connection

Returns:

the XQuery implementation properties for this connection

Throws:

XQException - if the connection is in a closed state

getMetaDataProperty

public String getMetaDataProperty(String key)
                           throws XQException

Gets the value of the connection property indicated by the specified key.

Parameters:

key - the name of the connection property

Returns:

the string value of the connection property, or null if there is no property with that key

Throws:

XQException - if the connection is in a closed state

getMetaData

public XQMetaData getMetaData()
                       throws XQException

Gets the metadata for this connection.

Returns:

XQMetadata representing the metadata of this connection

Throws:

XQException - if the connection is in a closed state

getWarnings

public XQWarning getWarnings()
                      throws XQException

Gets the first warning in a chained list of warnings associated with this connection.

Returns:

the first of a chained list of warnings associated with this connection. If there are no warnings returns null.

Throws:

XQException - if the connection is in a closed state

isClosed

public boolean isClosed()

Checks if the connection is closed.

Returns:

true if the connection is in a closed state, false otherwise

prepareExpression

public XQPreparedExpression prepareExpression(String xquery)
                                       throws XQException

Prepares an expression for execution. The properties of the connection's default XQStaticContext are copied to the returned XQPreparedExpression.

Parameters:

xquery - the XQuery expression as an String

Returns:

the prepared XQuery expression

Throws:

XQException - if (1) the connection is in a closed state, or (2) there are errors preparing the expression or (3) the specified argument is null.

prepareExpression

public XQPreparedExpression prepareExpression(String xquery,
                                              XQStaticContext staticContext)
                                       throws XQException

Prepares an expression for execution. The properties of the specified XQStaticContext values are copied to the returned XQPreparedExpression.

Parameters:

xquery - the XQuery expression as an String

staticContext - an XQStaticContext representing the default values for this expression

Returns:

the prepared XQuery expression

Throws:

XQException - if (1) the connection is in a closed state, or (2) there are errors preparing the expression or (3) the specified argument is null.

prepareExpression

public XQPreparedExpression prepareExpression(Reader xquery)
                                       throws XQException

Prepares an expression for execution. The properties of the connection's default XQStaticContext are copied to the returned XQPreparedExpression.

Parameters:

xquery - the XQuery expression as an Reader

Returns:

the prepared XQuery expression

Throws:

XQException - if (1) the connection is in a closed state, or (2) there are errors preparing the expression or (3) the specified argument is null.

prepareExpression

public XQPreparedExpression prepareExpression(Reader xquery,
                                              XQStaticContext staticContext)
                                       throws XQException

Prepares an expression for execution. The properties of the specified XQStaticContext values are copied to the returned XQPreparedExpression.

Parameters:

xquery - the XQuery expression as an Reader

staticContext - an XQStaticContext representing the default values for this expression

Returns:

the prepared XQuery expression

Throws:

XQException - if (1) the connection is in a closed state, or (2) there are errors preparing the expression or (3) the specified argument is null.

prepareExpression

public XQPreparedExpression prepareExpression(InputStream xquery)
                                       throws XQException

Prepares an expression for execution. The properties of the connection's default XQStaticContext are copied to the returned XQPreparedExpression.

Parameters:

xquery - the XQuery expression as an InputStream

Returns:

the prepared XQuery expression

Throws:

XQException - if (1) the connection is in a closed state, or (2) there are errors preparing the expression or (3) tthe specified argument is null.

prepareExpression

public XQPreparedExpression prepareExpression(InputStream xquery,
                                              XQStaticContext staticContext)
                                       throws XQException

Prepares an expression for execution. The properties of the specified XQStaticContext values are copied to the returned XQPreparedExpression.

Parameters:

xquery - the XQuery expression as an InputStream

staticContext - an XQStaticContext representing the default values for this expression

Returns:

the prepared XQuery expression

Throws:

XQException - if (1) the connection is in a closed state, or (2) there are errors preparing the expression or (3) the specified argument is null.

rollback

public void rollback()
              throws XQException

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

public XQStaticContext getStaticContext()
                                 throws XQException

Gets an 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.

Returns:

an XQStaticContext representing the default values for all expression properties.

Throws:

XQException - if the connection is in a closed state.

setStaticContext

public void setStaticContext(XQStaticContext staticContext)
                      throws XQException

Sets the default values for all expression properties. The implementation will read out all expression properties from the specified XQStaticContext and update its private copy.

Parameters:

staticContext - an XQStaticContext representing the default values

Throws:

XQException - if (1) the connection is in a closed state, or (2) if the XQStaticContext is not valid.

getAutoCommit

public boolean getAutoCommit()
                      throws XQException

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; otherwise false.

Throws:

XQException - if the connection is in a closed state

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws XQException

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 calling commit() or rollback().
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 the connection is in a closed state