org.xquark.xml.xdbc
Interface XMLConnection

All Known Implementing Classes:

DefaultReadOnlyXMLConnection, MediatorConnection

public interface XMLConnection

This interface represents a connection with a specific XML data source. Within the context of an XMLConnection, XQuery or XPath statements are executed and XML results are returned.
This interface is used by both read-only connections and storage connections, which require access to a larger set of interfaces, such as interfaces representing XML collections and documents. Classes providing read-only access to XML data sources can avoid implementing the optional interfaces for XML storage management, by deriving from the abstract class DefautReadOnlyXMLConnection.

Field Summary

static short	TRANSACTION_NONE Indicates that transactions are not supported.
static short	TRANSACTION_READ_COMMITTED Indicates that transactions are supported and dirty reads are prevented but non-repeatable reads and phantom reads can occur.
static short	TRANSACTION_READ_UNCOMMITTED Indicates that transactions are supported but dirty reads, non-repeatable reads and phantom reads can occur.
static short	TRANSACTION_REPEATABLE_READ Indicates that transactions are supported, dirty reads and non-repeatable reads are prevented but phantom reads can occur.
static short	TRANSACTION_SERIALIZABLE Indicates that transactions are supported but and dirty reads, non-repeatable reads and phantom reads are prevented.
static short	XPATH_STRING_TYPE Defines type for queries: XPath in a String.
static short	XQUERY_STRING_TYPE Defines type for queries: XQuery in a String.

Method Summary

void	close() To close the current data source connection.
void	commit() Makes all changes made since the previous commit/rollback permanent and releases any data source locks currently held by the Connection.
XMLCollection	createCollection(java.lang.String name, java.lang.String description, Configurable config) Creates a new XML collection.
Configurable	createCollectionConfig() Creates a new XML Collection configuration for set features and properties before create a XML Collection.
XMLStatement	createStatement() Creates a statement object for sending XQuery (query type by default) statements to the data source.
XMLStatement	createStatement(short queryType) Creates a statement object for sending XQuery or XPath (according to the specified type) statements to the data source.
int	deleteAllCollections() Deletes all XML collections of this connection.
void	deleteCollection(java.lang.String name) Deletes an XML collection by its name.
boolean	getAutoCommit() To know the current auto-commit state.
XMLCollection	getCollection(java.lang.String name) Creates an XMLcollection object featuring the XML documents collection.
XMLDataSourceMetaData	getMetaData() Gets the metadata regarding this connection's data source.
XMLDataSourceMetaData	getMetaData(boolean refresh) Gets the metadata regarding this connection's data source.
short	getTransactionIsolation() Gets this Connection's current transaction isolation level.
java.lang.String	getURL() To get the current URL of this connection.
java.lang.String	getUserName() To get the current user name.
boolean	isClosed() To know the connection state (opened or closed).
boolean	isReadOnly() To know the read/write mode of the current connection.
PreparedXMLStatement	prepareStatement(java.lang.String query) Creates a prepared statement object for sending parameterized XQuery (query type by default) statements to the data source.
void	renameCollection(java.lang.String oldname, java.lang.String newname) Renames an XML collection by its name.
void	rollback() Drops all changes made since the previous commit/rollback and releases any data source locks currently held by this Connection.
void	setAutoCommit(boolean autoCommitMode) Sets this connection's auto-commit mode.
void	setBaseURI(java.lang.String baseURI) Sets the base URI for documents.
void	setReadOnly(boolean readOnlyMode) To change the read/write mode of the connection.
void	setTransactionIsolation(short level) Attempts to change the transaction isolation level to the one given.

Field Detail

TRANSACTION_NONE

public static final short TRANSACTION_NONE

Indicates that transactions are not supported.

See Also:

Constant Field Values

TRANSACTION_READ_UNCOMMITTED

public static final short TRANSACTION_READ_UNCOMMITTED

Indicates that transactions are supported but dirty reads, non-repeatable reads and phantom reads can occur.

See Also:

Constant Field Values

TRANSACTION_READ_COMMITTED

public static final short TRANSACTION_READ_COMMITTED

Indicates that transactions are supported and dirty reads are prevented but non-repeatable reads and phantom reads can occur.

See Also:

Constant Field Values

TRANSACTION_REPEATABLE_READ

public static final short TRANSACTION_REPEATABLE_READ

Indicates that transactions are supported, dirty reads and non-repeatable reads are prevented but phantom reads can occur.

See Also:

Constant Field Values

TRANSACTION_SERIALIZABLE

public static final short TRANSACTION_SERIALIZABLE

Indicates that transactions are supported but and dirty reads, non-repeatable reads and phantom reads are prevented.

See Also:

Constant Field Values

XQUERY_STRING_TYPE

public static final short XQUERY_STRING_TYPE

Defines type for queries: XQuery in a String.

See Also:

Constant Field Values

XPATH_STRING_TYPE

public static final short XPATH_STRING_TYPE

Defines type for queries: XPath in a String.

See Also:

Constant Field Values

Method Detail

close

public void close()
           throws XMLDBCException

To close the current data source connection.

Throws:

XMLDBCException - if a data source access error occurs.

isClosed

public boolean isClosed()
                 throws XMLDBCException

To know the connection state (opened or closed).

Returns:

true if the current connection is closed, else false.

Throws:

XMLDBCException - if a data source access error occurs.

isReadOnly

public boolean isReadOnly()
                   throws XMLDBCException

To know the read/write mode of the current connection.

Returns:

true if connection is read-only, else false.

Throws:

XMLDBCException - if a data source access error occurs.

setReadOnly

public void setReadOnly(boolean readOnlyMode)
                 throws XMLDBCException,
                        XMLDBCNotSupportedException

To change the read/write mode of the connection. Some data sources can make optimisations if the connection is in read-only mode.

Parameters:

readOnlyMode - if true, the connection will pass in read-only mode, else in read/write mode.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source is read-only and the parameter is false.

getMetaData

public XMLDataSourceMetaData getMetaData()
                                  throws XMLDBCException

Gets the metadata regarding this connection's data source. A connection's data source is able to provide information describing itself. By default, metadata is loaded one time and cached. Use getMetaData(boolean) to enforce refresh.

Returns:

an XMLDataSourceMetaData object for this connection. #see #getMetaData(boolean)

Throws:

XMLDBCException - if a data source access error occurs.

getMetaData

public XMLDataSourceMetaData getMetaData(boolean refresh)
                                  throws XMLDBCException

Gets the metadata regarding this connection's data source. A connection's data source is able to provide information describing itself.

Parameters:

refresh - if true, reload metadata.

Returns:

an XMLDataSourceMetaData object for this connection.

Throws:

XMLDBCException - if a data source access error occurs.

getUserName

public java.lang.String getUserName()
                             throws XMLDBCException

To get the current user name.

Returns:

the current user name.

Throws:

XMLDBCException - if a data source access error occurs.

getURL

public java.lang.String getURL()
                        throws XMLDBCException

To get the current URL of this connection.

Returns:

the current URL of this connection.

Throws:

XMLDBCException - if a data source access error occurs.

createStatement

public XMLStatement createStatement()
                             throws XMLDBCException

Creates a statement object for sending XQuery (query type by default) statements to the data source.

Returns:

a new statement.

Throws:

XMLDBCException - if a data source access error occurs.

createStatement

public XMLStatement createStatement(short queryType)
                             throws XMLDBCException

Creates a statement object for sending XQuery or XPath (according to the specified type) statements to the data source.

Parameters:

queryType - the type of query for this statement (see constants in this interface).

Returns:

a new statement.

Throws:

XMLDBCException - if a data source access error occurs.

prepareStatement

public PreparedXMLStatement prepareStatement(java.lang.String query)
                                      throws XMLDBCException,
                                             XMLDBCNotSupportedException

Creates a prepared statement object for sending parameterized XQuery (query type by default) statements to the data source. The advantage of prepared statements over statements is that the request may be precompiled once and executed several times. Note: this interface is optional.

Parameters:

query - a parameterized XQuery.

Returns:

a new prepared statement containing the pre-compiled statement.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the method is not supported.

createCollectionConfig

public Configurable createCollectionConfig()
                                    throws XMLDBCException,
                                           XMLDBCNotSupportedException

Creates a new XML Collection configuration for set features and properties before create a XML Collection.

Returns:

a Configurable object which properties and features are vendor-dependant.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support this operation (typically, when the data source is read-only)

createCollection

public XMLCollection createCollection(java.lang.String name,
                                      java.lang.String description,
                                      Configurable config)
                               throws XMLDBCException,
                                      XMLDBCNotSupportedException

Creates a new XML collection. Each XML collections can be configured.

Parameters:

name - the unique name of the new XML collection.

description - the description of the new XML collection (optional).

config - a XML collection configuration. If null, the XML collection will be created with default configuration.

Returns:

an instance of XML collection.

Throws:

XMLDBCException - if a data source access error occurs or if the XML collection name already exists.

XMLDBCNotSupportedException - if the data source does not support this operation (typically, when the data source is read-only)

deleteCollection

public void deleteCollection(java.lang.String name)
                      throws XMLDBCException,
                             XMLDBCNotSupportedException

Deletes an XML collection by its name.

Parameters:

name - the unique name of an existing XML collection.

Throws:

XMLDBCException - if a data source access error occurs or if the XML collection does not exist.

XMLDBCNotSupportedException - if the data source does not support this operation (typically, when the data source is read-only)

renameCollection

public void renameCollection(java.lang.String oldname,
                             java.lang.String newname)
                      throws XMLDBCException,
                             XMLDBCNotSupportedException

Renames an XML collection by its name.

Parameters:

oldname - the unique name of an existing XML collection.

newname - the new unique name of an existing XML collection.

Throws:

XMLDBCException - if a data source access error errors, if the collection does not exist, or if the new name is not unique.

XMLDBCNotSupportedException - if the data source does not support this operation (typically, when the data source is read-only)

deleteAllCollections

public int deleteAllCollections()
                         throws XMLDBCException,
                                XMLDBCNotSupportedException

Deletes all XML collections of this connection.

Returns:

the number of XML collections deleted.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support this operation (typically, when the data source is read-only)

getCollection

public XMLCollection getCollection(java.lang.String name)
                            throws XMLDBCException,
                                   XMLDBCNotSupportedException

Creates an XMLcollection object featuring the XML documents collection.

The returned object may hold resources and should be closed after use.

Parameters:

name - a name of an XML documents collection.

Returns:

the XML collection that has the specified name or 'null' if there is no XML collection with this name.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support this operation (typically, when the data source is read-only)

commit

public void commit()
            throws XMLDBCException,
                   XMLDBCNotSupportedException

Makes all changes made since the previous commit/rollback permanent and releases any data source locks currently held by the Connection. This method has no effect when auto-commit mode has been enabled.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support transactions

setAutoCommit

public void setAutoCommit(boolean autoCommitMode)
                   throws XMLDBCException,
                          XMLDBCNotSupportedException

Sets this connection's auto-commit mode. If the parameter is true, a commit will be done after each statement execution, else otherwise a commit will have to be made explicitly by calling the commit method.

Parameters:

autoCommitMode - if true, the connection will pass in auto-commit mode, else in manual commit mode.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support transactions

getAutoCommit

public boolean getAutoCommit()
                      throws XMLDBCException,
                             XMLDBCNotSupportedException

To know the current auto-commit state.

Returns:

true if the current connection is in auto-commit mode, else false.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support transactions

rollback

public void rollback()
              throws XMLDBCException,
                     XMLDBCNotSupportedException

Drops all changes made since the previous commit/rollback and releases any data source locks currently held by this Connection. This method should be used only when auto-commit has been disabled.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support transactions

getTransactionIsolation

public short getTransactionIsolation()
                              throws XMLDBCException,
                                     XMLDBCNotSupportedException

Gets this Connection's current transaction isolation level.

Returns:

the current TRANSACTION_* mode value (see fields summary).

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support transactions

setTransactionIsolation

public void setTransactionIsolation(short level)
                             throws XMLDBCException,
                                    XMLDBCNotSupportedException

Attempts to change the transaction isolation level to the one given. The constants defined in the interface Connection are the possible transaction isolation levels. This method cannot be called while in the middle of a transaction.

Parameters:

level - one of the TRANSACTION_* (see field summary) isolation values with the exception of TRANSACTION_NONE; some data sources may not support other values.

Throws:

XMLDBCException - if a data source access error occurs.

XMLDBCNotSupportedException - if the data source does not support transactions

setBaseURI

public void setBaseURI(java.lang.String baseURI)

Sets the base URI for documents.

Returns:

nothing