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

Modifier and Type	Method and Description
<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.
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.

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