com.xqj2
Interface XQConnection2

All Superinterfaces:
XQConnection, XQDataFactory

public interface XQConnection2
extends XQConnection

Extended interface which implements functionality that is missing from XQConnection, based on findings whilst trying to implement XQJ API v1.0.


Method Summary
<T> T
createModuleProxy(String namespaceUri, String moduleUri, Class<T> clazz)
          Creates a Module Proxy, a Java Facade of an XQuery Library Module.
<T> T
createModuleProxy(String namespaceUri, String moduleUri, Class<T> clazz, XQStaticContext properties)
          Creates a Module Proxy, a Java Facade of an XQuery Library Module.
 int getTransactionTimeout()
          Gets the transaction timeout of the connection, in seconds.
 XAResource getXAResource()
          Gets the XAResource associated with the connection.
 void insertItem(String uri, XQItem item, XQInsertOptions options)
          Inserts an item into the XML DataSource with a given URI.
 boolean isReadOnly()
          Retrieves whether the connection object is in read-only mode.
 void setReadOnly(boolean readOnly)
          Puts this connection in read-only mode as a hint to the driver to enable database optimizations.
 void setTransactionTimeout(int seconds)
          Sets the transaction timeout of the connection, in seconds.
 
Methods inherited from interface javax.xml.xquery.XQConnection
close, commit, createExpression, createExpression, getAutoCommit, getMetaData, getStaticContext, isClosed, prepareExpression, prepareExpression, prepareExpression, prepareExpression, prepareExpression, prepareExpression, rollback, setAutoCommit, setStaticContext
 
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

createModuleProxy

<T> T createModuleProxy(String namespaceUri,
                        String moduleUri,
                        Class<T> clazz)
                    throws XQException
Creates a Module Proxy, a Java Facade of an XQuery Library Module.

Invoking methods on the returned instance will manifest in the implementation calling XQuery functions contained within the specified XQuery Library Module.

Java method parameters are mapped to XQuery function parameters according to the mapping rules outlined in the XQJ2 specification.

The XDM result of calling the XQuery function will be mapped into the Java interface's expected return type for that method, if possible.

Invoking Module Proxy methods will implicitly close any previous result sequences obtained from the connection.

Invoking XQuery Functions from Java in this manner was described in the presentation Building Bridges from Java to XQuery at XML Prague 2012.

Parameters:
namespaceUri - The Namespace URI of the XQuery Library Module, required parameter.
moduleUri - The URI of the XQuery Library Module, null is permitted.
clazz - A regular Java interface class, acting as the Facade for the XQuery Library Module.
Returns:
An instance of the interface class supplied in the clazz parameter.
Throws:
XQException

createModuleProxy

<T> T createModuleProxy(String namespaceUri,
                        String moduleUri,
                        Class<T> clazz,
                        XQStaticContext properties)
                    throws XQException
Creates a Module Proxy, a Java Facade of an XQuery Library Module.

Invoking methods on the returned instance will manifest in the implementation calling XQuery functions contained within the specified XQuery Library Module.

Java method parameters are mapped to XQuery function parameters according to the mapping rules outlined in the XQJ2 specification.

The XDM result of calling the XQuery function will be mapped into the Java interface's expected return type for that method, if possible.

Invoking Module Proxy methods will implicitly close any previous result sequences obtained from the connection.

Invoking XQuery Functions from Java in this manner was described in the presentation Building Bridges from Java to XQuery at XML Prague 2012.

Parameters:
namespaceUri - The Namespace URI of the XQuery Library Module, required parameter.
moduleUri - The URI of the XQuery Library Module, null is permitted.
clazz - A regular Java interface class, acting as the Facade for the XQuery Library Module.
properties - The static context properties, which the XQuery Module Proxy should run against.
Returns:
An instance of the interface class supplied in the clazz parameter.
Throws:
XQException

insertItem

void insertItem(String uri,
                XQItem item,
                XQInsertOptions options)
                throws XQException
Inserts an item into the XML DataSource with a given URI.

The item must be a document node.

This method pays respect to the state of the auto-commit attribute.

If auto-commit is set to false, an item or items will only be committed once the commit method has been invoked.

Parameters:
uri - The absolute URI of the item. Can not be null.
item - The item to insert. Must be a document node. Can not be null.
options - Gives hints to the implementation regarding how to ingest the item. Can be null.
Throws:
XQException - if any of the following is true
  1. the specified uri or item is null
  2. the item is not a document node
  3. the underlying object implementing the interface is closed
  4. the specified item is closed
  5. an implementation issue occurred whilst inserting the item

setReadOnly

void setReadOnly(boolean readOnly)
                 throws XQException
Puts this connection in read-only mode as a hint to the driver to enable database optimizations.

Note: This method cannot be called during a transaction.

Parameters:
readOnly - true enables read-only mode; false disables it
Throws:
XQException - if any of the following is true
  1. If this connection object is currently in the process of executing a transaction
  2. the connection object has been closed
  3. the vendor does not support transactions in the manner requested
  4. an implementation issue occurred whilst changing the transaction mode

isReadOnly

boolean isReadOnly()
                   throws XQException
Retrieves whether the connection object is in read-only mode.

Returns:
true if the connection object is read-only; false otherwise
Throws:
XQException - if this connection object is closed

setTransactionTimeout

void setTransactionTimeout(int seconds)
                           throws XQException
Sets the transaction timeout of the connection, in seconds.

When the auto-commit mode is set to false and a transaction is manually started by the user, the transaction will remain alive up to the number of seconds specified by the parameter seconds before timing out and being rolled back.

Parameters:
seconds - The number of seconds to wait before a manual transaction times out. 0 to wait indefinitely.
Throws:
XQException - if any of the following is true
  1. the connection object is closed
  2. the seconds parameter is a negative value
  3. the implementation does not support a manual transaction time out mechanism

getTransactionTimeout

int getTransactionTimeout()
                          throws XQException
Gets the transaction timeout of the connection, in seconds.

If the value returned is 0, then manual transactions will wait indefinitely.

Returns:
the transaction timeout of the connection, in seconds.
Throws:
XQException - if any of the following is true
  1. the connection object is closed
  2. the implementation does not support a manual transaction time out mechanism

getXAResource

XAResource getXAResource()
                         throws XQException
Gets the XAResource associated with the connection.

Returns:
a XAResource object, associated with this connection.
Throws:
XQException - if any of the following is true
  1. the connection object is closed
  2. the implementation does not support XA transactions