com.google.cloud.spanner.jdbc

Interface CloudSpannerJdbcConnection

All Superinterfaces:

AutoCloseable, Connection, Wrapper

public interface CloudSpannerJdbcConnection
extends Connection

JDBC connection with a number of additional Cloud Spanner specific methods. JDBC connections that are returned by the Cloud Spanner JdbcDriver will implement this interface.

Calling Wrapper.unwrap(Class) with CloudSpannerJdbcConnection#getClass() as input on a Connection returned by the Cloud Spanner JDBC Driver will return a CloudSpannerJdbcConnection instance.

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Method Summary

Modifier and Type	Method and Description
void	addTransactionRetryListener(TransactionRetryListener listener)
void	bufferedWrite(Iterable<Mutation> mutations) Buffers the given mutations locally on the current transaction of this Connection.
void	bufferedWrite(Mutation mutation) Buffers the given mutation locally on the current transaction of this Connection.
Timestamp	getCommitTimestamp()
String	getConnectionUrl()
Timestamp	getReadTimestamp()
Iterator<TransactionRetryListener>	getTransactionRetryListeners()
boolean	isRetryAbortsInternally()
boolean	removeTransactionRetryListener(TransactionRetryListener listener)
void	setRetryAbortsInternally(boolean retryAbortsInternally) Sets whether this connection will internally retry read/write transactions that abort.
void	write(Iterable<Mutation> mutations) Writes the specified mutations directly to the database and commits the changes.
void	write(Mutation mutation) Writes the specified mutation directly to the database and commits the change.

Methods inherited from interface java.sql.Connection

abort, clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Method Detail

getCommitTimestamp

Timestamp getCommitTimestamp()
                      throws SQLException

Returns:

the commit Timestamp of the last read/write transaction. If the last transaction was not a read/write transaction, or a read/write transaction that did not return a commit timestamp because the transaction was not committed, the method will throw a SQLException.

Throws:

SQLException

getReadTimestamp

Timestamp getReadTimestamp()
                    throws SQLException

Returns:

the read Timestamp of the last read-only transaction. If the last transaction was not a read-only transaction, or a read-only transaction that did not return a read timestamp because no data was read, the method will throw a SQLException.

Throws:

SQLException

isRetryAbortsInternally

boolean isRetryAbortsInternally()
                         throws SQLException

Returns:

true if this connection will automatically retry read/write transactions that abort. This method may only be called when the connection is in read/write transactional mode and no transaction has been started yet.

Throws:

SQLException

setRetryAbortsInternally

void setRetryAbortsInternally(boolean retryAbortsInternally)
                       throws SQLException

Sets whether this connection will internally retry read/write transactions that abort. The default is true. When internal retry is enabled, the Connection will keep track of a running SHA256 checksum of all ResultSets that have been returned from Cloud Spanner. If the checksum that is calculated during an internal retry differs from the original checksum, the transaction will abort with an AbortedDueToConcurrentModificationException.

Note that retries of a read/write transaction that calls a non-deterministic function on Cloud Spanner, such as CURRENT_TIMESTAMP(), will never be successful, as the data returned during the retry will always be different from the original transaction.

It is also highly recommended that all queries in a read/write transaction have an ORDER BY clause that guarantees that the data is returned in the same order as in the original transaction if the transaction is internally retried. The most efficient way to achieve this is to always include the primary key columns at the end of the ORDER BY clause.

This method may only be called when the connection is in read/write transactional mode and no transaction has been started yet.

Parameters:

retryAbortsInternally - Set to true to internally retry transactions that are aborted by Spanner. When set to false, any database call on a transaction that has been aborted by Cloud Spanner will throw an AbortedException instead of being retried. Set this to false if your application already uses retry loops to handle AbortedExceptions.

Throws:

SQLException

write

void write(Mutation mutation)
    throws SQLException

Writes the specified mutation directly to the database and commits the change. The value is readable after the successful completion of this method. Writing multiple mutations to a database by calling this method multiple times mode is inefficient, as each call will need a round trip to the database. Instead, you should consider writing the mutations together by calling write(Iterable).

Calling this method is only allowed in autocommit mode. See bufferedWrite(Iterable) for writing mutations in transactions.

Parameters:

mutation - The Mutation to write to the database.

Throws:

SQLException - if the Connection is not in autocommit mode or if the Connection is closed.

write

void write(Iterable<Mutation> mutations)
    throws SQLException

Writes the specified mutations directly to the database and commits the changes. The values are readable after the successful completion of this method.

Calling this method is only allowed in autocommit mode. See bufferedWrite(Iterable) for writing mutations in transactions.

Parameters:

mutations - The Mutations to write to the database.

Throws:

SQLException - if the Connection is not in autocommit mode or if the Connection is closed.

bufferedWrite

void bufferedWrite(Mutation mutation)
            throws SQLException

Buffers the given mutation locally on the current transaction of this Connection. The mutation will be written to the database at the next call to Connection.commit(). The value will not be readable on this Connection before the transaction is committed.

Calling this method is only allowed when not in autocommit mode. See write(Mutation) for writing mutations in autocommit mode.

Parameters:

mutation - the Mutation to buffer for writing to the database on the next commit.

Throws:

SQLException - if the Connection is in autocommit mode or the Connection is closed.

bufferedWrite

void bufferedWrite(Iterable<Mutation> mutations)
            throws SQLException

Buffers the given mutations locally on the current transaction of this Connection. The mutations will be written to the database at the next call to Connection.commit(). The values will not be readable on this Connection before the transaction is committed.

Calling this method is only allowed when not in autocommit mode. See write(Iterable) for writing mutations in autocommit mode.

Parameters:

mutations - the Mutations to buffer for writing to the database on the next commit.

Throws:

SQLException - if the Connection is in autocommit mode or the Connection is closed.

getConnectionUrl

String getConnectionUrl()

Returns:

a connection URL that can be used to create a new Connection that is equal to the initial state of this connection. If this connection was initially opened in read-only mode, and later changed to read-write, this will not be reflected in the connection URL that is returned.

addTransactionRetryListener

void addTransactionRetryListener(TransactionRetryListener listener)
                          throws SQLException

Throws:

SQLException - if the Connection is closed.

See Also:

Connection.addTransactionRetryListener(TransactionRetryListener)

removeTransactionRetryListener

boolean removeTransactionRetryListener(TransactionRetryListener listener)
                                throws SQLException

Throws:

SQLException - if the Connection is closed.

See Also:

Connection.removeTransactionRetryListener(TransactionRetryListener)

getTransactionRetryListeners

Iterator<TransactionRetryListener> getTransactionRetryListeners()
                                                         throws SQLException

Throws:

SQLException - if the Connection is closed.

See Also:

Connection.getTransactionRetryListeners()