com.saxonica.xqj

Class SaxonXQConnection

java.lang.Object

com.saxonica.xqj.Closable

com.saxonica.xqj.SaxonXQDataFactory

com.saxonica.xqj.SaxonXQConnection

All Implemented Interfaces:

XQConnection, XQDataFactory

public class SaxonXQConnection
extends SaxonXQDataFactory
implements XQConnection

Saxon implementation of the XQL interface XQConnection. This interface represents a "connection" between an XQuery application and an XQuery server. In Saxon the client and server run in the same process so the concept of a connection is rather notional, and some of the properties have little meaning. However, the connection is the factory object used to compile queries.

For Javadoc descriptions of the public methors, see the XQJ documentation.

Method Summary

Modifier and Type	Method and Description
void	commit() Makes all changes made in the current transaction permanent and releases any locks held by the datasource.
XQPreparedExpression	copyPreparedExpression(XQPreparedExpression expression) Copy a prepared expression to create a new prepared expression.
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
Configuration	getConfiguration() Get the Saxon Configuration in use.
XQMetaData	getMetaData() Gets the metadata for this connection.
XQStaticContext	getStaticContext() Gets an XQStaticContext representing the default values for all expression properties.
XQPreparedExpression	prepareExpression(java.io.InputStream xquery) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(java.io.InputStream xquery, XQStaticContext properties) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(java.io.Reader xquery) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(java.io.Reader xquery, XQStaticContext properties) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(java.lang.String xquery) Prepares an expression for execution.
XQPreparedExpression	prepareExpression(java.lang.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 class com.saxonica.xqj.SaxonXQDataFactory

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, getObjectConverter, init, setObjectConverter

Methods inherited from class com.saxonica.xqj.Closable

close, isClosed, setClosableContainer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.xml.xquery.XQConnection

close, isClosed

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

getConfiguration

public Configuration getConfiguration()

Get the Saxon Configuration in use. Changes made to this Configuration will affect this data source and XQJ connections created from it (either before or afterwards).

Returns:

the configuration in use.

commit

public void commit()
            throws XQException

Description copied from interface: XQConnection

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.

Specified by:

commit in interface XQConnection

Throws:

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

createExpression

public XQExpression createExpression()
                              throws XQException

Description copied from interface: XQConnection

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.

Specified by:

createExpression in interface XQConnection

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 properties)
                              throws XQException

Description copied from interface: XQConnection

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.

Specified by:

createExpression in interface XQConnection

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

getAutoCommit

public boolean getAutoCommit()
                      throws XQException

Description copied from interface: XQConnection

Gets the auto-commit attribute of this connection

Specified by:

getAutoCommit in interface XQConnection

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

getMetaData

public XQMetaData getMetaData()
                       throws XQException

Description copied from interface: XQConnection

Gets the metadata for this connection.

Specified by:

getMetaData in interface XQConnection

Returns:

XQMetadata representing the metadata of this connection

Throws:

XQException - if the connection is in a closed state

getStaticContext

public XQStaticContext getStaticContext()
                                 throws XQException

Description copied from interface: XQConnection

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.

Specified by:

getStaticContext in interface XQConnection

Returns:

XQStaticContext representing the default values for all expression properties

Throws:

XQException - if the connection is in a closed state

prepareExpression

public XQPreparedExpression prepareExpression(java.io.InputStream xquery)
                                       throws XQException

Description copied from interface: XQConnection

Prepares an expression for execution.

The properties of the connection's default XQStaticContext are copied to the returned XQPreparedExpression.

Specified by:

prepareExpression in interface XQConnection

Parameters:

xquery - the XQuery expression as an InputStream. Cannot be null

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

prepareExpression

public XQPreparedExpression prepareExpression(java.io.InputStream xquery,
                                              XQStaticContext properties)
                                       throws XQException

Description copied from interface: XQConnection

Prepares an expression for execution.

The properties of the specified XQStaticContext values are copied to the returned XQPreparedExpression.

Specified by:

prepareExpression in interface XQConnection

Parameters:

xquery - the XQuery expression as an InputStream. Cannot be null

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

prepareExpression

public XQPreparedExpression prepareExpression(java.io.Reader xquery)
                                       throws XQException

Description copied from interface: XQConnection

Prepares an expression for execution.

The properties of the connection's default XQStaticContext are copied to the returned XQPreparedExpression.

Specified by:

prepareExpression in interface XQConnection

Parameters:

xquery - the XQuery expression as a Reader. Cannot be null

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

prepareExpression

public XQPreparedExpression prepareExpression(java.io.Reader xquery,
                                              XQStaticContext properties)
                                       throws XQException

Description copied from interface: XQConnection

Prepares an expression for execution.

The properties of the specified XQStaticContext values are copied to the returned XQPreparedExpression.

Specified by:

prepareExpression in interface XQConnection

Parameters:

xquery - the XQuery expression as a Reader. Cannot be null

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

prepareExpression

public XQPreparedExpression prepareExpression(java.lang.String xquery)
                                       throws XQException

Description copied from interface: XQConnection

Prepares an expression for execution.

The properties of the connection's default XQStaticContext are copied to the returned XQPreparedExpression.

Specified by:

prepareExpression in interface XQConnection

Parameters:

xquery - the XQuery expression as a String. Cannot be null

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

prepareExpression

public XQPreparedExpression prepareExpression(java.lang.String xquery,
                                              XQStaticContext properties)
                                       throws XQException

Description copied from interface: XQConnection

Prepares an expression for execution.

The properties of the specified XQStaticContext values are copied to the returned XQPreparedExpression.

Specified by:

prepareExpression in interface XQConnection

Parameters:

xquery - the XQuery expression as a String. Cannot be null

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

copyPreparedExpression

public XQPreparedExpression copyPreparedExpression(XQPreparedExpression expression)
                                            throws XQException

Copy a prepared expression to create a new prepared expression. The prepared expression to be copied may belong to a different connection. This method (which is a Saxon extension to the XQJ interface) allows a query to be compiled once, and reused concurrently under multiple connections in multiple threads. The compiled code of the existing query and its static context are shared with the original query, but a new dynamic context is established, so that the two expressions can safely be used in parallel.

Parameters:

expression - the XQPreparedExpression to be copied. This must have been created using Saxon, and it must have been created with an XQConnection derived from the same XQDataSource as this connection.

Returns:

a copy of the supplied expression, that can be used in a different connection or thread with its own dynamic context. The new copy of the expression belongs to this connection, and can be used in the same way as an expression created using any of the prepareExpression() methods on this class.

Throws:

XQException, - for example if either of the connections has been closed

XQException

rollback

public void rollback()
              throws XQException

Description copied from interface: XQConnection

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.

Specified by:

rollback in interface XQConnection

Throws:

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

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws XQException

Description copied from interface: XQConnection

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.

Specified by:

setAutoCommit in interface XQConnection

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

setStaticContext

public void setStaticContext(XQStaticContext properties)
                      throws XQException

Description copied from interface: XQConnection

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.

Specified by:

setStaticContext in interface XQConnection

Parameters:

properties - XQStaticContext containing values of expression properties

Throws:

XQException - if the connection is in a closed state