nl.topicus.jdbc.shaded.com.google.cloud.spanner.Session Maven / Gradle / Ivy
Show all versions of spanner-jdbc Show documentation
/*
* Copyright 2017 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package nl.topicus.jdbc.shaded.com.google.cloud.spanner;
/**
* A {@code Session} can be used to perform transactions that read and/or modify data in a Cloud
* Spanner database.
*
* Sessions can only execute one transaction at a time. To execute multiple concurrent
* read-write/write-only transactions, create multiple sessions. Note that standalone reads and
* queries use a transaction internally, and count toward the one transaction limit.
*
*
Cloud Spanner limits the number of sessions that can exist at any given time; thus, it is a
* good idea to delete idle and/or unneeded sessions. Aside from explicit deletes, Cloud Spanner can
* delete sessions for which no operations are sent for more than an hour, or due to internal
* errors. If a session is deleted, requests to it return {@link ErrorCode#NOT_FOUND}.
*
*
Idle sessions can be kept alive by sending a trivial SQL query periodically, for example,
* {@code SELECT 1}.
*
*
Sessions are long-lived objects intended to be reused for many consecutive operations; a
* typical application will maintain a pool of sessions to use during its lifetime.
*
*
Since only one transaction can be performed at a time within any given session, instances
* require external synchronization; {@code Session} implementations are not required to be
* thread-safe.
*/
public interface Session extends DatabaseClient, AutoCloseable {
/** Returns the resource name associated with this session. */
String getName();
/**
* Prepares a transaction for use by a subsequent {@link #readWriteTransaction()} or {@link
* #write(Iterable)} call. It is not necessary to call this method before running a transaction or
* performing a write, but doing so may allow one round trip of the protocol to be performed in
* advance; calling this method on an idle session that is expected to execute a transaction or
* write in the near future may reduce the latency of the subsequent transaction/write.
*/
void prepareReadWriteTransaction();
@Override
void close();
}