1<?php
2/*
3 * Copyright 2014 Google Inc.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
6 * use this file except in compliance with the License. You may obtain a copy of
7 * the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14 * License for the specific language governing permissions and limitations under
15 * the License.
16 */
17
18namespace Google\Service\Spanner\Resource;
19
20use Google\Service\Spanner\BatchCreateSessionsRequest;
21use Google\Service\Spanner\BatchCreateSessionsResponse;
22use Google\Service\Spanner\BeginTransactionRequest;
23use Google\Service\Spanner\CommitRequest;
24use Google\Service\Spanner\CommitResponse;
25use Google\Service\Spanner\CreateSessionRequest;
26use Google\Service\Spanner\ExecuteBatchDmlRequest;
27use Google\Service\Spanner\ExecuteBatchDmlResponse;
28use Google\Service\Spanner\ExecuteSqlRequest;
29use Google\Service\Spanner\ListSessionsResponse;
30use Google\Service\Spanner\PartialResultSet;
31use Google\Service\Spanner\PartitionQueryRequest;
32use Google\Service\Spanner\PartitionReadRequest;
33use Google\Service\Spanner\PartitionResponse;
34use Google\Service\Spanner\ReadRequest;
35use Google\Service\Spanner\ResultSet;
36use Google\Service\Spanner\RollbackRequest;
37use Google\Service\Spanner\Session;
38use Google\Service\Spanner\SpannerEmpty;
39use Google\Service\Spanner\Transaction;
40
41/**
42 * The "sessions" collection of methods.
43 * Typical usage is:
44 *  <code>
45 *   $spannerService = new Google\Service\Spanner(...);
46 *   $sessions = $spannerService->sessions;
47 *  </code>
48 */
49class ProjectsInstancesDatabasesSessions extends \Google\Service\Resource
50{
51  /**
52   * Creates multiple new sessions. This API can be used to initialize a session
53   * cache on the clients. See https://goo.gl/TgSFN2 for best practices on session
54   * cache management. (sessions.batchCreate)
55   *
56   * @param string $database Required. The database in which the new sessions are
57   * created.
58   * @param BatchCreateSessionsRequest $postBody
59   * @param array $optParams Optional parameters.
60   * @return BatchCreateSessionsResponse
61   */
62  public function batchCreate($database, BatchCreateSessionsRequest $postBody, $optParams = [])
63  {
64    $params = ['database' => $database, 'postBody' => $postBody];
65    $params = array_merge($params, $optParams);
66    return $this->call('batchCreate', [$params], BatchCreateSessionsResponse::class);
67  }
68  /**
69   * Begins a new transaction. This step can often be skipped: Read, ExecuteSql
70   * and Commit can begin a new transaction as a side-effect.
71   * (sessions.beginTransaction)
72   *
73   * @param string $session Required. The session in which the transaction runs.
74   * @param BeginTransactionRequest $postBody
75   * @param array $optParams Optional parameters.
76   * @return Transaction
77   */
78  public function beginTransaction($session, BeginTransactionRequest $postBody, $optParams = [])
79  {
80    $params = ['session' => $session, 'postBody' => $postBody];
81    $params = array_merge($params, $optParams);
82    return $this->call('beginTransaction', [$params], Transaction::class);
83  }
84  /**
85   * Commits a transaction. The request includes the mutations to be applied to
86   * rows in the database. `Commit` might return an `ABORTED` error. This can
87   * occur at any time; commonly, the cause is conflicts with concurrent
88   * transactions. However, it can also happen for a variety of other reasons. If
89   * `Commit` returns `ABORTED`, the caller should re-attempt the transaction from
90   * the beginning, re-using the same session. On very rare occasions, `Commit`
91   * might return `UNKNOWN`. This can happen, for example, if the client job
92   * experiences a 1+ hour networking failure. At that point, Cloud Spanner has
93   * lost track of the transaction outcome and we recommend that you perform
94   * another read from the database to see the state of things as they are now.
95   * (sessions.commit)
96   *
97   * @param string $session Required. The session in which the transaction to be
98   * committed is running.
99   * @param CommitRequest $postBody
100   * @param array $optParams Optional parameters.
101   * @return CommitResponse
102   */
103  public function commit($session, CommitRequest $postBody, $optParams = [])
104  {
105    $params = ['session' => $session, 'postBody' => $postBody];
106    $params = array_merge($params, $optParams);
107    return $this->call('commit', [$params], CommitResponse::class);
108  }
109  /**
110   * Creates a new session. A session can be used to perform transactions that
111   * read and/or modify data in a Cloud Spanner database. Sessions are meant to be
112   * reused for many consecutive transactions. Sessions can only execute one
113   * transaction at a time. To execute multiple concurrent read-write/write-only
114   * transactions, create multiple sessions. Note that standalone reads and
115   * queries use a transaction internally, and count toward the one transaction
116   * limit. Active sessions use additional server resources, so it is a good idea
117   * to delete idle and unneeded sessions. Aside from explicit deletes, Cloud
118   * Spanner may delete sessions for which no operations are sent for more than an
119   * hour. If a session is deleted, requests to it return `NOT_FOUND`. Idle
120   * sessions can be kept alive by sending a trivial SQL query periodically, e.g.,
121   * `"SELECT 1"`. (sessions.create)
122   *
123   * @param string $database Required. The database in which the new session is
124   * created.
125   * @param CreateSessionRequest $postBody
126   * @param array $optParams Optional parameters.
127   * @return Session
128   */
129  public function create($database, CreateSessionRequest $postBody, $optParams = [])
130  {
131    $params = ['database' => $database, 'postBody' => $postBody];
132    $params = array_merge($params, $optParams);
133    return $this->call('create', [$params], Session::class);
134  }
135  /**
136   * Ends a session, releasing server resources associated with it. This will
137   * asynchronously trigger cancellation of any operations that are running with
138   * this session. (sessions.delete)
139   *
140   * @param string $name Required. The name of the session to delete.
141   * @param array $optParams Optional parameters.
142   * @return SpannerEmpty
143   */
144  public function delete($name, $optParams = [])
145  {
146    $params = ['name' => $name];
147    $params = array_merge($params, $optParams);
148    return $this->call('delete', [$params], SpannerEmpty::class);
149  }
150  /**
151   * Executes a batch of SQL DML statements. This method allows many statements to
152   * be run with lower latency than submitting them sequentially with ExecuteSql.
153   * Statements are executed in sequential order. A request can succeed even if a
154   * statement fails. The ExecuteBatchDmlResponse.status field in the response
155   * provides information about the statement that failed. Clients must inspect
156   * this field to determine whether an error occurred. Execution stops after the
157   * first failed statement; the remaining statements are not executed.
158   * (sessions.executeBatchDml)
159   *
160   * @param string $session Required. The session in which the DML statements
161   * should be performed.
162   * @param ExecuteBatchDmlRequest $postBody
163   * @param array $optParams Optional parameters.
164   * @return ExecuteBatchDmlResponse
165   */
166  public function executeBatchDml($session, ExecuteBatchDmlRequest $postBody, $optParams = [])
167  {
168    $params = ['session' => $session, 'postBody' => $postBody];
169    $params = array_merge($params, $optParams);
170    return $this->call('executeBatchDml', [$params], ExecuteBatchDmlResponse::class);
171  }
172  /**
173   * Executes an SQL statement, returning all results in a single reply. This
174   * method cannot be used to return a result set larger than 10 MiB; if the query
175   * yields more data than that, the query fails with a `FAILED_PRECONDITION`
176   * error. Operations inside read-write transactions might return `ABORTED`. If
177   * this occurs, the application should restart the transaction from the
178   * beginning. See Transaction for more details. Larger result sets can be
179   * fetched in streaming fashion by calling ExecuteStreamingSql instead.
180   * (sessions.executeSql)
181   *
182   * @param string $session Required. The session in which the SQL query should be
183   * performed.
184   * @param ExecuteSqlRequest $postBody
185   * @param array $optParams Optional parameters.
186   * @return ResultSet
187   */
188  public function executeSql($session, ExecuteSqlRequest $postBody, $optParams = [])
189  {
190    $params = ['session' => $session, 'postBody' => $postBody];
191    $params = array_merge($params, $optParams);
192    return $this->call('executeSql', [$params], ResultSet::class);
193  }
194  /**
195   * Like ExecuteSql, except returns the result set as a stream. Unlike
196   * ExecuteSql, there is no limit on the size of the returned result set.
197   * However, no individual row in the result set can exceed 100 MiB, and no
198   * column value can exceed 10 MiB. (sessions.executeStreamingSql)
199   *
200   * @param string $session Required. The session in which the SQL query should be
201   * performed.
202   * @param ExecuteSqlRequest $postBody
203   * @param array $optParams Optional parameters.
204   * @return PartialResultSet
205   */
206  public function executeStreamingSql($session, ExecuteSqlRequest $postBody, $optParams = [])
207  {
208    $params = ['session' => $session, 'postBody' => $postBody];
209    $params = array_merge($params, $optParams);
210    return $this->call('executeStreamingSql', [$params], PartialResultSet::class);
211  }
212  /**
213   * Gets a session. Returns `NOT_FOUND` if the session does not exist. This is
214   * mainly useful for determining whether a session is still alive.
215   * (sessions.get)
216   *
217   * @param string $name Required. The name of the session to retrieve.
218   * @param array $optParams Optional parameters.
219   * @return Session
220   */
221  public function get($name, $optParams = [])
222  {
223    $params = ['name' => $name];
224    $params = array_merge($params, $optParams);
225    return $this->call('get', [$params], Session::class);
226  }
227  /**
228   * Lists all sessions in a given database.
229   * (sessions.listProjectsInstancesDatabasesSessions)
230   *
231   * @param string $database Required. The database in which to list sessions.
232   * @param array $optParams Optional parameters.
233   *
234   * @opt_param string filter An expression for filtering the results of the
235   * request. Filter rules are case insensitive. The fields eligible for filtering
236   * are: * `labels.key` where key is the name of a label Some examples of using
237   * filters are: * `labels.env:*` --> The session has the label "env". *
238   * `labels.env:dev` --> The session has the label "env" and the value of the
239   * label contains the string "dev".
240   * @opt_param int pageSize Number of sessions to be returned in the response. If
241   * 0 or less, defaults to the server's maximum allowed page size.
242   * @opt_param string pageToken If non-empty, `page_token` should contain a
243   * next_page_token from a previous ListSessionsResponse.
244   * @return ListSessionsResponse
245   */
246  public function listProjectsInstancesDatabasesSessions($database, $optParams = [])
247  {
248    $params = ['database' => $database];
249    $params = array_merge($params, $optParams);
250    return $this->call('list', [$params], ListSessionsResponse::class);
251  }
252  /**
253   * Creates a set of partition tokens that can be used to execute a query
254   * operation in parallel. Each of the returned partition tokens can be used by
255   * ExecuteStreamingSql to specify a subset of the query result to read. The same
256   * session and read-only transaction must be used by the PartitionQueryRequest
257   * used to create the partition tokens and the ExecuteSqlRequests that use the
258   * partition tokens. Partition tokens become invalid when the session used to
259   * create them is deleted, is idle for too long, begins a new transaction, or
260   * becomes too old. When any of these happen, it is not possible to resume the
261   * query, and the whole operation must be restarted from the beginning.
262   * (sessions.partitionQuery)
263   *
264   * @param string $session Required. The session used to create the partitions.
265   * @param PartitionQueryRequest $postBody
266   * @param array $optParams Optional parameters.
267   * @return PartitionResponse
268   */
269  public function partitionQuery($session, PartitionQueryRequest $postBody, $optParams = [])
270  {
271    $params = ['session' => $session, 'postBody' => $postBody];
272    $params = array_merge($params, $optParams);
273    return $this->call('partitionQuery', [$params], PartitionResponse::class);
274  }
275  /**
276   * Creates a set of partition tokens that can be used to execute a read
277   * operation in parallel. Each of the returned partition tokens can be used by
278   * StreamingRead to specify a subset of the read result to read. The same
279   * session and read-only transaction must be used by the PartitionReadRequest
280   * used to create the partition tokens and the ReadRequests that use the
281   * partition tokens. There are no ordering guarantees on rows returned among the
282   * returned partition tokens, or even within each individual StreamingRead call
283   * issued with a partition_token. Partition tokens become invalid when the
284   * session used to create them is deleted, is idle for too long, begins a new
285   * transaction, or becomes too old. When any of these happen, it is not possible
286   * to resume the read, and the whole operation must be restarted from the
287   * beginning. (sessions.partitionRead)
288   *
289   * @param string $session Required. The session used to create the partitions.
290   * @param PartitionReadRequest $postBody
291   * @param array $optParams Optional parameters.
292   * @return PartitionResponse
293   */
294  public function partitionRead($session, PartitionReadRequest $postBody, $optParams = [])
295  {
296    $params = ['session' => $session, 'postBody' => $postBody];
297    $params = array_merge($params, $optParams);
298    return $this->call('partitionRead', [$params], PartitionResponse::class);
299  }
300  /**
301   * Reads rows from the database using key lookups and scans, as a simple
302   * key/value style alternative to ExecuteSql. This method cannot be used to
303   * return a result set larger than 10 MiB; if the read matches more data than
304   * that, the read fails with a `FAILED_PRECONDITION` error. Reads inside read-
305   * write transactions might return `ABORTED`. If this occurs, the application
306   * should restart the transaction from the beginning. See Transaction for more
307   * details. Larger result sets can be yielded in streaming fashion by calling
308   * StreamingRead instead. (sessions.read)
309   *
310   * @param string $session Required. The session in which the read should be
311   * performed.
312   * @param ReadRequest $postBody
313   * @param array $optParams Optional parameters.
314   * @return ResultSet
315   */
316  public function read($session, ReadRequest $postBody, $optParams = [])
317  {
318    $params = ['session' => $session, 'postBody' => $postBody];
319    $params = array_merge($params, $optParams);
320    return $this->call('read', [$params], ResultSet::class);
321  }
322  /**
323   * Rolls back a transaction, releasing any locks it holds. It is a good idea to
324   * call this for any transaction that includes one or more Read or ExecuteSql
325   * requests and ultimately decides not to commit. `Rollback` returns `OK` if it
326   * successfully aborts the transaction, the transaction was already aborted, or
327   * the transaction is not found. `Rollback` never returns `ABORTED`.
328   * (sessions.rollback)
329   *
330   * @param string $session Required. The session in which the transaction to roll
331   * back is running.
332   * @param RollbackRequest $postBody
333   * @param array $optParams Optional parameters.
334   * @return SpannerEmpty
335   */
336  public function rollback($session, RollbackRequest $postBody, $optParams = [])
337  {
338    $params = ['session' => $session, 'postBody' => $postBody];
339    $params = array_merge($params, $optParams);
340    return $this->call('rollback', [$params], SpannerEmpty::class);
341  }
342  /**
343   * Like Read, except returns the result set as a stream. Unlike Read, there is
344   * no limit on the size of the returned result set. However, no individual row
345   * in the result set can exceed 100 MiB, and no column value can exceed 10 MiB.
346   * (sessions.streamingRead)
347   *
348   * @param string $session Required. The session in which the read should be
349   * performed.
350   * @param ReadRequest $postBody
351   * @param array $optParams Optional parameters.
352   * @return PartialResultSet
353   */
354  public function streamingRead($session, ReadRequest $postBody, $optParams = [])
355  {
356    $params = ['session' => $session, 'postBody' => $postBody];
357    $params = array_merge($params, $optParams);
358    return $this->call('streamingRead', [$params], PartialResultSet::class);
359  }
360}
361
362// Adding a class alias for backwards compatibility with the previous class name.
363class_alias(ProjectsInstancesDatabasesSessions::class, 'Google_Service_Spanner_Resource_ProjectsInstancesDatabasesSessions');
364