/
Session.java
57 lines (53 loc) · 2.58 KB
/
Session.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
/*
* 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 com.google.cloud.spanner;
/**
* A {@code Session} can be used to perform transactions that read and/or modify data in a Cloud
* Spanner database.
*
* <p>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.
*
* <p>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}.
*
* <p>Idle sessions can be kept alive by sending a trivial SQL query periodically, for example,
* {@code SELECT 1}.
*
* <p>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.
*
* <p>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();
}