Skip to content

Commit 0f9546f

Browse files
cloud-java-botcloud-java-bot
committed
chore: generate libraries at Thu Nov 14 18:29:54 UTC 2024
1 parent 402ad47 commit 0f9546f

File tree

17 files changed

+654
-48
lines changed

17 files changed

+654
-48
lines changed

‎README.md‎

Lines changed: 100 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,13 @@ implementation 'com.google.cloud:google-cloud-datastore'
5656
If you are using Gradle without BOM, add this to your dependencies:
5757

5858
```Groovy
59-
implementation 'com.google.cloud:google-cloud-datastore:2.24.2'
59+
implementation 'com.google.cloud:google-cloud-datastore:2.22.0'
6060
```
6161

6262
If you are using SBT, add this to your dependencies:
6363

6464
```Scala
65-
libraryDependencies += "com.google.cloud" % "google-cloud-datastore" % "2.24.2"
65+
libraryDependencies += "com.google.cloud" % "google-cloud-datastore" % "2.22.0"
6666
```
6767

6868
## Authentication
@@ -283,6 +283,103 @@ There are new gRPC specific features available to use in this update.
283283
To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions.
284284
See [ChannelPoolSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.grpc.ChannelPoolSettings) and [Performance Best Practices](https://grpc.io/docs/guides/performance/) for more information on channel pools and best practices for performance.
285285

286+
Example:
287+
```java
288+
InstantiatingGrpcChannelProvider channelProvider =
289+
DatastoreSettings.defaultGrpcTransportProviderBuilder()
290+
.setChannelPoolSettings(
291+
ChannelPoolSettings.builder()
292+
.setInitialChannelCount(MIN_VAL)
293+
.setMaxChannelCount(MAX_VAL)
294+
.build())
295+
.build();
296+
297+
DatastoreOptions options = DatastoreOptions.newBuilder()
298+
.setProjectId("my-project")
299+
.setChannelProvider(channelProvider)
300+
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
301+
.build();
302+
```
303+
304+
gRPC Java Datastore Client User Guide
305+
-------
306+
In this feature launch, the [Java Datastore client](https://github.com/googleapis/java-datastore) now offers gRPC as a transport layer option with experimental support. Using [gRPC connection pooling](https://grpc.io/docs/guides/performance/) enables distributing RPCs over multiple connections which may improve performance.
307+
308+
#### Download Instructions
309+
Instructions:
310+
1. Clone the grpc-experimental branch from GitHub:
311+
```python
312+
git clone -b grpc-experimental https://github.com/googleapis/java-datastore.git
313+
```
314+
2. Run the following commands to build the library:
315+
```python
316+
# Go to the directory the code was downloaded to
317+
cd java-datastore/
318+
319+
# Build the library
320+
mvn clean install -DskipTests=true
321+
```
322+
3. Add the following dependency to your project:
323+
```xml
324+
<dependency>
325+
<groupId>com.google.cloud</groupId>
326+
<artifactId>google-cloud-datastore</artifactId>
327+
<version>2.20.0-grpc-experimental-1-SNAPSHOT</version>
328+
</dependency>
329+
```
330+
331+
#### How to Use
332+
To opt-in to the gRPC transport behavior, simply add the below line of code (`setTransportOptions`) to your Datastore client instantiation.
333+
334+
Example:
335+
```java
336+
DatastoreOptions datastoreOptions =
337+
DatastoreOptions.newBuilder()
338+
.setProjectId("my-project")
339+
.setDatabaseId("my-database")
340+
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
341+
.build();
342+
```
343+
Setting the transport options explicitly to `GrpcTransportOptions` will signal the client to use gRPC instead of HTTP when making calls to the server.
344+
345+
To revert back to the existing stable behavior and transport, simply remove the transport options line or replace it with `HttpTransportOptions`. Please note this will require an application rebuild and restart.
346+
Example:
347+
```java
348+
// will default to existing HTTP transport behavior
349+
DatastoreOptions datastoreOptions = DatastoreOptions.newBuilder()
350+
.setProjectId("my-project")
351+
.setDatabaseId("my-database")
352+
.build();
353+
354+
// will also default to existing HTTP transport behavior
355+
DatastoreOptions datastoreOptions =
356+
DatastoreOptions.newBuilder()
357+
.setProjectId("my-project")
358+
.setDatabaseId("my-database")
359+
.setTransportOptions(HttpTransportOptions.newBuilder()
360+
.setConnectTimeout(1000)
361+
.build()).build();
362+
```
363+
364+
Note: client instantiations that already use `setTransportOptions` with `HttpTransportOptions` will continue to have the same behavior. Only transports that are explicitly set to gRPC will change.
365+
366+
#### Verify Datastore Transport Options Type
367+
To verify which type of TransportOptions you have successfully configured, you can use the below lines of code to compare transport options type:
368+
```java
369+
// checks if using gRPC transport options
370+
boolean isGRPC = datastore.getOptions().getTransportOptions() instanceof GrpcTransportOptions;
371+
372+
// checks if using HTTP transport options
373+
boolean isHTTP = datastore.getOptions().getTransportOptions() instanceof HTTPTransportOptions;
374+
```
375+
376+
#### New Features
377+
There are new gRPC specific features available to use in this update.
378+
379+
##### Channel Pooling
380+
To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions.
381+
See [ChannelPoolSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.grpc.ChannelPoolSettings) and [Performance Best Practices](https://grpc.io/docs/guides/performance/) for more information on channel pools and best practices for performance.
382+
286383
Example:
287384
```java
288385
InstantiatingGrpcChannelProvider channelProvider =
@@ -479,7 +576,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
479576
[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-datastore/java11.html
480577
[stability-image]: https://img.shields.io/badge/stability-stable-green
481578
[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-datastore.svg
482-
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.24.2
579+
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.22.0
483580
[authentication]: https://github.com/googleapis/google-cloud-java#authentication
484581
[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
485582
[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles

‎google-cloud-datastore/src/main/java/com/google/cloud/datastore/v1/DatastoreClient.java‎

Lines changed: 154 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2023 Google LLC
2+
* Copyright 2024 Google LLC
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -73,19 +73,151 @@
7373
* <p>Note: close() needs to be called on the DatastoreClient object to clean up resources such as
7474
* threads. In the example above, try-with-resources is used, which automatically calls close().
7575
*
76-
* <p>The surface of this class includes several types of Java methods for each of the API's
77-
* methods:
78-
*
79-
* <ol>
80-
* <li>A "flattened" method. With this type of method, the fields of the request type have been
81-
* converted into function parameters. It may be the case that not all fields are available as
82-
* parameters, and not every API method will have a flattened method entry point.
83-
* <li>A "request object" method. This type of method only takes one parameter, a request object,
84-
* which must be constructed before the call. Not every API method will have a request object
85-
* method.
86-
* <li>A "callable" method. This type of method takes no parameters and returns an immutable API
87-
* callable object, which can be used to initiate calls to the service.
88-
* </ol>
76+
* <table>
77+
* <caption>Methods</caption>
78+
* <tr>
79+
* <th>Method</th>
80+
* <th>Description</th>
81+
* <th>Method Variants</th>
82+
* </tr>
83+
* <tr>
84+
* <td><p> Lookup</td>
85+
* <td><p> Looks up entities by key.</td>
86+
* <td>
87+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
88+
* <ul>
89+
* <li><p> lookup(LookupRequest request)
90+
* </ul>
91+
* <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
92+
* <ul>
93+
* <li><p> lookup(String projectId, ReadOptions readOptions, List&lt;Key&gt; keys)
94+
* </ul>
95+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
96+
* <ul>
97+
* <li><p> lookupCallable()
98+
* </ul>
99+
* </td>
100+
* </tr>
101+
* <tr>
102+
* <td><p> RunQuery</td>
103+
* <td><p> Queries for entities.</td>
104+
* <td>
105+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
106+
* <ul>
107+
* <li><p> runQuery(RunQueryRequest request)
108+
* </ul>
109+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
110+
* <ul>
111+
* <li><p> runQueryCallable()
112+
* </ul>
113+
* </td>
114+
* </tr>
115+
* <tr>
116+
* <td><p> RunAggregationQuery</td>
117+
* <td><p> Runs an aggregation query.</td>
118+
* <td>
119+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
120+
* <ul>
121+
* <li><p> runAggregationQuery(RunAggregationQueryRequest request)
122+
* </ul>
123+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
124+
* <ul>
125+
* <li><p> runAggregationQueryCallable()
126+
* </ul>
127+
* </td>
128+
* </tr>
129+
* <tr>
130+
* <td><p> BeginTransaction</td>
131+
* <td><p> Begins a new transaction.</td>
132+
* <td>
133+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
134+
* <ul>
135+
* <li><p> beginTransaction(BeginTransactionRequest request)
136+
* </ul>
137+
* <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
138+
* <ul>
139+
* <li><p> beginTransaction(String projectId)
140+
* </ul>
141+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
142+
* <ul>
143+
* <li><p> beginTransactionCallable()
144+
* </ul>
145+
* </td>
146+
* </tr>
147+
* <tr>
148+
* <td><p> Commit</td>
149+
* <td><p> Commits a transaction, optionally creating, deleting or modifying some entities.</td>
150+
* <td>
151+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
152+
* <ul>
153+
* <li><p> commit(CommitRequest request)
154+
* </ul>
155+
* <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
156+
* <ul>
157+
* <li><p> commit(String projectId, CommitRequest.Mode mode, List&lt;Mutation&gt; mutations)
158+
* <li><p> commit(String projectId, CommitRequest.Mode mode, ByteString transaction, List&lt;Mutation&gt; mutations)
159+
* </ul>
160+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
161+
* <ul>
162+
* <li><p> commitCallable()
163+
* </ul>
164+
* </td>
165+
* </tr>
166+
* <tr>
167+
* <td><p> Rollback</td>
168+
* <td><p> Rolls back a transaction.</td>
169+
* <td>
170+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
171+
* <ul>
172+
* <li><p> rollback(RollbackRequest request)
173+
* </ul>
174+
* <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
175+
* <ul>
176+
* <li><p> rollback(String projectId, ByteString transaction)
177+
* </ul>
178+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
179+
* <ul>
180+
* <li><p> rollbackCallable()
181+
* </ul>
182+
* </td>
183+
* </tr>
184+
* <tr>
185+
* <td><p> AllocateIds</td>
186+
* <td><p> Allocates IDs for the given keys, which is useful for referencing an entity before it is inserted.</td>
187+
* <td>
188+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
189+
* <ul>
190+
* <li><p> allocateIds(AllocateIdsRequest request)
191+
* </ul>
192+
* <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
193+
* <ul>
194+
* <li><p> allocateIds(String projectId, List&lt;Key&gt; keys)
195+
* </ul>
196+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
197+
* <ul>
198+
* <li><p> allocateIdsCallable()
199+
* </ul>
200+
* </td>
201+
* </tr>
202+
* <tr>
203+
* <td><p> ReserveIds</td>
204+
* <td><p> Prevents the supplied keys' IDs from being auto-allocated by Cloud Datastore.</td>
205+
* <td>
206+
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
207+
* <ul>
208+
* <li><p> reserveIds(ReserveIdsRequest request)
209+
* </ul>
210+
* <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
211+
* <ul>
212+
* <li><p> reserveIds(String projectId, List&lt;Key&gt; keys)
213+
* </ul>
214+
* <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
215+
* <ul>
216+
* <li><p> reserveIdsCallable()
217+
* </ul>
218+
* </td>
219+
* </tr>
220+
* </table>
89221
*
90222
* <p>See the individual methods for example code.
91223
*
@@ -241,6 +373,7 @@ public final LookupResponse lookup(String projectId, ReadOptions readOptions, Li
241373
* .setDatabaseId("databaseId1688905718")
242374
* .setReadOptions(ReadOptions.newBuilder().build())
243375
* .addAllKeys(new ArrayList<Key>())
376+
* .setPropertyMask(PropertyMask.newBuilder().build())
244377
* .build();
245378
* LookupResponse response = datastoreClient.lookup(request);
246379
* }
@@ -272,6 +405,7 @@ public final LookupResponse lookup(LookupRequest request) {
272405
* .setDatabaseId("databaseId1688905718")
273406
* .setReadOptions(ReadOptions.newBuilder().build())
274407
* .addAllKeys(new ArrayList<Key>())
408+
* .setPropertyMask(PropertyMask.newBuilder().build())
275409
* .build();
276410
* ApiFuture<LookupResponse> future = datastoreClient.lookupCallable().futureCall(request);
277411
* // Do something.
@@ -302,6 +436,8 @@ public final UnaryCallable<LookupRequest, LookupResponse> lookupCallable() {
302436
* .setDatabaseId("databaseId1688905718")
303437
* .setPartitionId(PartitionId.newBuilder().build())
304438
* .setReadOptions(ReadOptions.newBuilder().build())
439+
* .setPropertyMask(PropertyMask.newBuilder().build())
440+
* .setExplainOptions(ExplainOptions.newBuilder().build())
305441
* .build();
306442
* RunQueryResponse response = datastoreClient.runQuery(request);
307443
* }
@@ -333,6 +469,8 @@ public final RunQueryResponse runQuery(RunQueryRequest request) {
333469
* .setDatabaseId("databaseId1688905718")
334470
* .setPartitionId(PartitionId.newBuilder().build())
335471
* .setReadOptions(ReadOptions.newBuilder().build())
472+
* .setPropertyMask(PropertyMask.newBuilder().build())
473+
* .setExplainOptions(ExplainOptions.newBuilder().build())
336474
* .build();
337475
* ApiFuture<RunQueryResponse> future = datastoreClient.runQueryCallable().futureCall(request);
338476
* // Do something.
@@ -363,6 +501,7 @@ public final UnaryCallable<RunQueryRequest, RunQueryResponse> runQueryCallable()
363501
* .setDatabaseId("databaseId1688905718")
364502
* .setPartitionId(PartitionId.newBuilder().build())
365503
* .setReadOptions(ReadOptions.newBuilder().build())
504+
* .setExplainOptions(ExplainOptions.newBuilder().build())
366505
* .build();
367506
* RunAggregationQueryResponse response = datastoreClient.runAggregationQuery(request);
368507
* }
@@ -394,6 +533,7 @@ public final RunAggregationQueryResponse runAggregationQuery(RunAggregationQuery
394533
* .setDatabaseId("databaseId1688905718")
395534
* .setPartitionId(PartitionId.newBuilder().build())
396535
* .setReadOptions(ReadOptions.newBuilder().build())
536+
* .setExplainOptions(ExplainOptions.newBuilder().build())
397537
* .build();
398538
* ApiFuture<RunAggregationQueryResponse> future =
399539
* datastoreClient.runAggregationQueryCallable().futureCall(request);

0 commit comments

Comments
 (0)