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

All Methods Instance Methods Abstract Methods
`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 `ResultSet`s 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 `AbortedException`s.
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 `Mutation`s 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 `Mutation`s 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()`