org.xquark.xml.xdbc
Interface XMLConnection

All Known Implementing Classes:
DefaultReadOnlyXMLConnection

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 MEDIATOR_STRING_TYPE
          Defines type for queries: mediator queries (XQuery) in a String.
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.
 PreparedXMLStatement prepareStatement(java.lang.String query, short queryType)
          Creates a prepared statement object for sending parameterized XQuery or XPath (according to the specified type) 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 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

MEDIATOR_STRING_TYPE

public static final short MEDIATOR_STRING_TYPE
Defines type for queries: mediator queries (XQuery) 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.

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.

prepareStatement

public PreparedXMLStatement prepareStatement(java.lang.String query,
                                             short queryType)
                                      throws XMLDBCException,
                                             XMLDBCNotSupportedException
Creates a prepared statement object for sending parameterized XQuery or XPath (according to the specified type) 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 query of the specified type.
queryType - the type of query for this statement (see constants in this interface).
Returns:
a new Pprepared 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


Copyright © 2004 Université de Versailles Saint-Quentin, XQuark Group. All rights reserved.