Skip to content

Commit

Permalink
chore: generate libraries at Thu Nov 14 18:29:54 UTC 2024
Browse files Browse the repository at this point in the history
  • Loading branch information
@cloud-java-bot
cloud-java-bot committed Nov 14, 2024
1 parent 402ad47 commit 0f9546f
Show file tree
Hide file tree
Showing 17 changed files with 654 additions and 48 deletions.
103 changes: 100 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,13 @@ implementation 'com.google.cloud:google-cloud-datastore'
If you are using Gradle without BOM, add this to your dependencies:

```Groovy
implementation 'com.google.cloud:google-cloud-datastore:2.24.2'
implementation 'com.google.cloud:google-cloud-datastore:2.22.0'
```

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

```Scala
libraryDependencies += "com.google.cloud" % "google-cloud-datastore" % "2.24.2"
libraryDependencies += "com.google.cloud" % "google-cloud-datastore" % "2.22.0"
```

## Authentication
Expand Down Expand Up @@ -283,6 +283,103 @@ There are new gRPC specific features available to use in this update.
To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions.
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.

Example:
```java
InstantiatingGrpcChannelProvider channelProvider =
DatastoreSettings.defaultGrpcTransportProviderBuilder()
.setChannelPoolSettings(
ChannelPoolSettings.builder()
.setInitialChannelCount(MIN_VAL)
.setMaxChannelCount(MAX_VAL)
.build())
.build();

DatastoreOptions options = DatastoreOptions.newBuilder()
.setProjectId("my-project")
.setChannelProvider(channelProvider)
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
.build();
```

gRPC Java Datastore Client User Guide
-------
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.

#### Download Instructions
Instructions:
1. Clone the grpc-experimental branch from GitHub:
```python
git clone -b grpc-experimental https://github.com/googleapis/java-datastore.git
```
2. Run the following commands to build the library:
```python
# Go to the directory the code was downloaded to
cd java-datastore/

# Build the library
mvn clean install -DskipTests=true
```
3. Add the following dependency to your project:
```xml
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-datastore</artifactId>
<version>2.20.0-grpc-experimental-1-SNAPSHOT</version>
</dependency>
```

#### How to Use
To opt-in to the gRPC transport behavior, simply add the below line of code (`setTransportOptions`) to your Datastore client instantiation.

Example:
```java
DatastoreOptions datastoreOptions =
DatastoreOptions.newBuilder()
.setProjectId("my-project")
.setDatabaseId("my-database")
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
.build();
```
Setting the transport options explicitly to `GrpcTransportOptions` will signal the client to use gRPC instead of HTTP when making calls to the server.

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.
Example:
```java
// will default to existing HTTP transport behavior
DatastoreOptions datastoreOptions = DatastoreOptions.newBuilder()
.setProjectId("my-project")
.setDatabaseId("my-database")
.build();

// will also default to existing HTTP transport behavior
DatastoreOptions datastoreOptions =
DatastoreOptions.newBuilder()
.setProjectId("my-project")
.setDatabaseId("my-database")
.setTransportOptions(HttpTransportOptions.newBuilder()
.setConnectTimeout(1000)
.build()).build();
```

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.

#### Verify Datastore Transport Options Type
To verify which type of TransportOptions you have successfully configured, you can use the below lines of code to compare transport options type:
```java
// checks if using gRPC transport options
boolean isGRPC = datastore.getOptions().getTransportOptions() instanceof GrpcTransportOptions;

// checks if using HTTP transport options
boolean isHTTP = datastore.getOptions().getTransportOptions() instanceof HTTPTransportOptions;
```

#### New Features
There are new gRPC specific features available to use in this update.

##### Channel Pooling
To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions.
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.

Example:
```java
InstantiatingGrpcChannelProvider channelProvider =
Expand Down Expand Up @@ -479,7 +576,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-datastore/java11.html
[stability-image]: https://img.shields.io/badge/stability-stable-green
[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-datastore.svg
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.24.2
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.22.0
[authentication]: https://github.com/googleapis/google-cloud-java#authentication
[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles
Expand Down
168 changes: 154 additions & 14 deletions google-cloud-datastore/src/main/java/com/google/cloud/datastore/v1/DatastoreClient.java
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright 2023 Google LLC
* Copyright 2024 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -73,19 +73,151 @@
* <p>Note: close() needs to be called on the DatastoreClient object to clean up resources such as
* threads. In the example above, try-with-resources is used, which automatically calls close().
*
* <p>The surface of this class includes several types of Java methods for each of the API's
* methods:
*
* <ol>
* <li>A "flattened" method. With this type of method, the fields of the request type have been
* converted into function parameters. It may be the case that not all fields are available as
* parameters, and not every API method will have a flattened method entry point.
* <li>A "request object" method. This type of method only takes one parameter, a request object,
* which must be constructed before the call. Not every API method will have a request object
* method.
* <li>A "callable" method. This type of method takes no parameters and returns an immutable API
* callable object, which can be used to initiate calls to the service.
* </ol>
* <table>
* <caption>Methods</caption>
* <tr>
* <th>Method</th>
* <th>Description</th>
* <th>Method Variants</th>
* </tr>
* <tr>
* <td><p> Lookup</td>
* <td><p> Looks up entities by key.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> lookup(LookupRequest request)
* </ul>
* <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>
* <ul>
* <li><p> lookup(String projectId, ReadOptions readOptions, List&lt;Key&gt; keys)
* </ul>
* <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>
* <ul>
* <li><p> lookupCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> RunQuery</td>
* <td><p> Queries for entities.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> runQuery(RunQueryRequest request)
* </ul>
* <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>
* <ul>
* <li><p> runQueryCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> RunAggregationQuery</td>
* <td><p> Runs an aggregation query.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> runAggregationQuery(RunAggregationQueryRequest request)
* </ul>
* <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>
* <ul>
* <li><p> runAggregationQueryCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> BeginTransaction</td>
* <td><p> Begins a new transaction.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> beginTransaction(BeginTransactionRequest request)
* </ul>
* <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>
* <ul>
* <li><p> beginTransaction(String projectId)
* </ul>
* <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>
* <ul>
* <li><p> beginTransactionCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> Commit</td>
* <td><p> Commits a transaction, optionally creating, deleting or modifying some entities.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> commit(CommitRequest request)
* </ul>
* <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>
* <ul>
* <li><p> commit(String projectId, CommitRequest.Mode mode, List&lt;Mutation&gt; mutations)
* <li><p> commit(String projectId, CommitRequest.Mode mode, ByteString transaction, List&lt;Mutation&gt; mutations)
* </ul>
* <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>
* <ul>
* <li><p> commitCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> Rollback</td>
* <td><p> Rolls back a transaction.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> rollback(RollbackRequest request)
* </ul>
* <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>
* <ul>
* <li><p> rollback(String projectId, ByteString transaction)
* </ul>
* <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>
* <ul>
* <li><p> rollbackCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> AllocateIds</td>
* <td><p> Allocates IDs for the given keys, which is useful for referencing an entity before it is inserted.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> allocateIds(AllocateIdsRequest request)
* </ul>
* <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>
* <ul>
* <li><p> allocateIds(String projectId, List&lt;Key&gt; keys)
* </ul>
* <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>
* <ul>
* <li><p> allocateIdsCallable()
* </ul>
* </td>
* </tr>
* <tr>
* <td><p> ReserveIds</td>
* <td><p> Prevents the supplied keys' IDs from being auto-allocated by Cloud Datastore.</td>
* <td>
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
* <ul>
* <li><p> reserveIds(ReserveIdsRequest request)
* </ul>
* <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>
* <ul>
* <li><p> reserveIds(String projectId, List&lt;Key&gt; keys)
* </ul>
* <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>
* <ul>
* <li><p> reserveIdsCallable()
* </ul>
* </td>
* </tr>
* </table>
*
* <p>See the individual methods for example code.
*
Expand Down Expand Up @@ -241,6 +373,7 @@ public final LookupResponse lookup(String projectId, ReadOptions readOptions, Li
* .setDatabaseId("databaseId1688905718")
* .setReadOptions(ReadOptions.newBuilder().build())
* .addAllKeys(new ArrayList<Key>())
* .setPropertyMask(PropertyMask.newBuilder().build())
* .build();
* LookupResponse response = datastoreClient.lookup(request);
* }
Expand Down Expand Up @@ -272,6 +405,7 @@ public final LookupResponse lookup(LookupRequest request) {
* .setDatabaseId("databaseId1688905718")
* .setReadOptions(ReadOptions.newBuilder().build())
* .addAllKeys(new ArrayList<Key>())
* .setPropertyMask(PropertyMask.newBuilder().build())
* .build();
* ApiFuture<LookupResponse> future = datastoreClient.lookupCallable().futureCall(request);
* // Do something.
Expand Down Expand Up @@ -302,6 +436,8 @@ public final UnaryCallable<LookupRequest, LookupResponse> lookupCallable() {
* .setDatabaseId("databaseId1688905718")
* .setPartitionId(PartitionId.newBuilder().build())
* .setReadOptions(ReadOptions.newBuilder().build())
* .setPropertyMask(PropertyMask.newBuilder().build())
* .setExplainOptions(ExplainOptions.newBuilder().build())
* .build();
* RunQueryResponse response = datastoreClient.runQuery(request);
* }
Expand Down Expand Up @@ -333,6 +469,8 @@ public final RunQueryResponse runQuery(RunQueryRequest request) {
* .setDatabaseId("databaseId1688905718")
* .setPartitionId(PartitionId.newBuilder().build())
* .setReadOptions(ReadOptions.newBuilder().build())
* .setPropertyMask(PropertyMask.newBuilder().build())
* .setExplainOptions(ExplainOptions.newBuilder().build())
* .build();
* ApiFuture<RunQueryResponse> future = datastoreClient.runQueryCallable().futureCall(request);
* // Do something.
Expand Down Expand Up @@ -363,6 +501,7 @@ public final UnaryCallable<RunQueryRequest, RunQueryResponse> runQueryCallable()
* .setDatabaseId("databaseId1688905718")
* .setPartitionId(PartitionId.newBuilder().build())
* .setReadOptions(ReadOptions.newBuilder().build())
* .setExplainOptions(ExplainOptions.newBuilder().build())
* .build();
* RunAggregationQueryResponse response = datastoreClient.runAggregationQuery(request);
* }
Expand Down Expand Up @@ -394,6 +533,7 @@ public final RunAggregationQueryResponse runAggregationQuery(RunAggregationQuery
* .setDatabaseId("databaseId1688905718")
* .setPartitionId(PartitionId.newBuilder().build())
* .setReadOptions(ReadOptions.newBuilder().build())
* .setExplainOptions(ExplainOptions.newBuilder().build())
* .build();
* ApiFuture<RunAggregationQueryResponse> future =
* datastoreClient.runAggregationQueryCallable().futureCall(request);
Expand Down
Loading

0 comments on commit 0f9546f

Please sign in to comment.