com.marklogic.xdbc
Interface XDBCConnection

All Known Implementing Classes:

XDMPConnection

public interface XDBCConnection

A connection (session) with a specific database. Within the context of an XDBCConnection, XQuery statements are executed and results are returned.

An XDBCConnection's database will provide information describing its XQuery compliance level and the capabilities of the connection with the getMetaData method.

Note: By default the XDBCConnection automatically commits changes after executing each statement. Unsetting autocommit mode is currently NOT supported.

Field Summary

static int	XDBC_TRANSACTION_NONE Transaction isolation level: Indicates that transactions are not supported.
static int	XDBC_TRANSACTION_READ_COMMITTED Transaction isolation level: Dirty reads are prevented; non-repeatable reads and phantom reads can occur.
static int	XDBC_TRANSACTION_READ_UNCOMMITTED Transaction isolation level: Dirty reads, non-repeatable reads and phantom reads can occur.
static int	XDBC_TRANSACTION_REPEATABLE_READ Transaction isolation level: Dirty reads and non-repeatable reads are prevented; phantom reads can occur.
static int	XDBC_TRANSACTION_SERIALIZABLE Transaction isolation level: Dirty reads, non-repeatable reads and phantom reads are prevented.

Method Summary

void	clearWarnings() Clears all warnings reported for this XDBCConnection object.
void	close() Releases a XDBCConnection's database and XDBC resources immediately instead of waiting for this to be done by the Java runtime.
void	commit() NOTE: This method is NOT currently supported.
XDBCStatement	createStatement() Creates a XDBCStatement object for sending XQuery expressions to the database.
boolean	getAutoCommit() Gets the current auto-commit state.
String	getHost() Gets the host associated with this connection.
Locale	getLocale() Gets the locale associated with this database connection.
XDBCDatabaseMetaData	getMetaData() Gets the metadata regarding this connection's database.
int	getPort() Gets the port number of this connection.
TimeZone	getTimeZone() Gets the timezone associated with this database connection.
int	getTransactionIsolation() Gets this XDBCConnection's current transaction isolation level.
XDBCWarning	getWarnings() Returns the first warning reported by calls on this Connection.
boolean	isClosed() Tests if this XDBCConnection is closed.
boolean	isReadOnly() Tests if this XDBCConnection is in read-only mode.
void	rollback() NOTE: This method is NOT currently supported.
void	setAutoCommit(boolean autoCommit) NOTE: This method is NOT currently supported.
void	setLocale(Locale locale) Sets the locale for this connection object.
void	setReadOnly(boolean readOnly) NOTE: This method is NOT currently supported.
void	setTimeZone(TimeZone tz) Sets the timezone for this connection object.
void	setTransactionIsolation(int level) NOTE: This method is NOT currently supported.

Field Detail

XDBC_TRANSACTION_NONE

public static final int XDBC_TRANSACTION_NONE

Transaction isolation level: Indicates that transactions are not supported.

See Also:

Constant Field Values

XDBC_TRANSACTION_READ_UNCOMMITTED

public static final int XDBC_TRANSACTION_READ_UNCOMMITTED

Transaction isolation level: Dirty reads, non-repeatable reads and phantom reads can occur. This level allows a node changed by one transaction to be read by another transaction before any changes to that node have been committed (a "dirty read"). If any of the changes are rolled back, the second transaction will have retrieved an invalid node.

READ UNCOMMITTED allows queries in the transaction to read data without acquiring any lock.

See Also:

Constant Field Values

XDBC_TRANSACTION_READ_COMMITTED

public static final int XDBC_TRANSACTION_READ_COMMITTED

Transaction isolation level: Dirty reads are prevented; non-repeatable reads and phantom reads can occur. This level only prohibits a transaction from reading a row with uncommitted changes in it.

A transaction may issue the same query several times and get different answers. For example, a reservation system could be READ_COMMITTED; the transaction could repeatably poll to see if a seat was available, hoping for a cancellation.

See Also:

Constant Field Values

XDBC_TRANSACTION_REPEATABLE_READ

public static final int XDBC_TRANSACTION_REPEATABLE_READ

Transaction isolation level: Dirty reads and non-repeatable reads are prevented; phantom reads can occur. This level prohibits a transaction from reading a node with uncommitted changes in it, and it also prohibits the situation where one transaction reads a node, a second transaction alters the node, and the first transaction rereads the node, getting different values the second time (a "non-repeatable read").

See Also:

Constant Field Values

XDBC_TRANSACTION_SERIALIZABLE

public static final int XDBC_TRANSACTION_SERIALIZABLE

Transaction isolation level: Dirty reads, non-repeatable reads and phantom reads are prevented. This level includes the prohibitions in TRANSACTION_REPEATABLE_READ and further prohibits the situation where one transaction reads all nodes that satisfy a WHERE condition, a second transaction inserts a node that satisfies that WHERE condition, and the first transaction rereads for the same condition, retrieving the additional "phantom" nodes in the second read.

See Also:

Constant Field Values

Method Detail

close

public void close()
           throws XDBCException

Releases a XDBCConnection's database and XDBC resources immediately instead of waiting for this to be done by the Java runtime.

Calling this method frees up resources immediately and its use is strongly encouraged.

Throws:

XDBCException - if a database access error occurs

commit

public void commit()
            throws XDBCException

NOTE: This method is NOT currently supported.

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the connection.

Throws:

XDBCException - if a database access error occurs

createStatement

public XDBCStatement createStatement()
                              throws XDBCException

Creates a XDBCStatement object for sending XQuery expressions to the database.

Returns:

a new XDBCStatement object.

Throws:

XDBCException - if a database access error occurs

getAutoCommit

public boolean getAutoCommit()
                      throws XDBCException

Gets the current auto-commit state. Note: The auto-commit level is currently ignored by the server

Returns:

true if auto-commit mode is enabled, false if auto-commit is disabled.

Throws:

XDBCException - if a database access error occurs

getHost

public String getHost()
               throws XDBCException

Gets the host associated with this connection. This host may be hostname or internet address.

Returns:

the String hostname of the connection object.

Throws:

XDBCException - if a database access error occurs

getLocale

public Locale getLocale()
                 throws XDBCException

Gets the locale associated with this database connection. The default locale setting for a connection is inherited from the Java runtime environment.

Returns:

the java.util.Locale object describing this connection's locale.

Throws:

XDBCException - if a database access error occurs

See Also:

java.util.Locale

getTimeZone

public TimeZone getTimeZone()
                     throws XDBCException

Gets the timezone associated with this database connection. The default timezone setting for a connection is inherited from the Java runtime environment.

Returns:

the java.util.Timezone object describing this connection's timezone.

Throws:

XDBCException - if a database access error occurs

See Also:

java.util.TimeZone

getMetaData

public XDBCDatabaseMetaData getMetaData()
                                 throws XDBCException

Gets the metadata regarding this connection's database.

Returns:

an XDBCDatabaseMetaData object which describes the database that this connection is connected to.

Throws:

XDBCException - if a database access error occurs

getPort

public int getPort()
            throws XDBCException

Gets the port number of this connection.

Returns:

the int port number of this connection.

Throws:

XDBCException - if a database access error occurs

getTransactionIsolation

public int getTransactionIsolation()
                            throws XDBCException

Gets this XDBCConnection's current transaction isolation level. Note: The transaction isolation level is currently ignored by the server

Returns:

the integer transaction isolation level of this XDBCConnection.

Throws:

XDBCException - if a database access error occurs

See Also:

XDBC_TRANSACTION_NONE, XDBC_TRANSACTION_READ_UNCOMMITTED, XDBC_TRANSACTION_READ_COMMITTED, XDBC_TRANSACTION_REPEATABLE_READ, XDBC_TRANSACTION_SERIALIZABLE

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws XDBCException

NOTE: This method is NOT currently supported.

Attempts to change the transaction isolation level to the one given.

Parameters:

level - the integer transaction isolation level to set on this XDBCConnection

Throws:

XDBCException - if a database access error occurs

See Also:

XDBC_TRANSACTION_NONE, XDBC_TRANSACTION_READ_UNCOMMITTED, XDBC_TRANSACTION_READ_COMMITTED, XDBC_TRANSACTION_REPEATABLE_READ, XDBC_TRANSACTION_SERIALIZABLE

getWarnings

public XDBCWarning getWarnings()
                        throws XDBCException

Returns the first warning reported by calls on this Connection.

Returns:

an XDBCWarning object containing the database warning.

Throws:

XDBCException - if a database access error occurs

clearWarnings

public void clearWarnings()
                   throws XDBCException

Clears all warnings reported for this XDBCConnection object. After a call to this method, the method getWarnings returns null until a new warning is reported for this XDBCConnection.

Throws:

XDBCException - if a database access error occurs

isClosed

public boolean isClosed()
                 throws XDBCException

Tests if this XDBCConnection is closed.

Returns:

true if this XDBCConnection is closed, false if it is still open.

Throws:

XDBCException - if a database access error occurs

isReadOnly

public boolean isReadOnly()
                   throws XDBCException

Tests if this XDBCConnection is in read-only mode.

Returns:

true if this XDBCConnection is in read-only mode, false if it is not in read-only mode.

Throws:

XDBCException - if a database access error occurs

rollback

public void rollback()
              throws XDBCException

NOTE: This method is NOT currently supported.

Drops all changes made since the previous commit/rollback and releases any database locks currently held by this XDBCConnection.

Throws:

XDBCException - if a database access error occurs

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws XDBCException

NOTE: This method is NOT currently supported.

Sets this connection's auto-commit mode.

Parameters:

autoCommit - true to enable auto-commit mode for this XDBCConnection; false to disable auto-commit mode.

Throws:

XDBCException - if a database access error occurs

setLocale

public void setLocale(Locale locale)
               throws XDBCException

Sets the locale for this connection object. The locale is used for all operations on this connection and subordinate objects such as XDBCStatements and XDBCResultSequences.

Generally, the locale needs to be changed before creating a statement or other operation, for which the new locale is needed.

Parameters:

locale - the java.util.Locale object to use for with this connection object.

Throws:

XDBCException - if a database access error occurs

See Also:

Locale

setTimeZone

public void setTimeZone(TimeZone tz)
                 throws XDBCException

Sets the timezone for this connection object. The timezone is used for all operations on this connection and subordinate objects such as XDBCStatements and XDBCResultSequences.

Generally, the timezone needs to be changed before creating a statement or other operation, for which the new timezone is needed.

Parameters:

tz - the java.util.TimeZone object to use for with this connection object.

Throws:

XDBCException - if a database access error occurs

See Also:

TimeZone

setReadOnly

public void setReadOnly(boolean readOnly)
                 throws XDBCException

NOTE: This method is NOT currently supported.

Puts this connection in read-only mode as a hint to enable database optimizations.

Parameters:

readOnly - true to enable read-only mode for this XDBCConnection; false to disable read-only mode.

Throws:

XDBCException - if a database access error occurs