Skip to content

Commit

Permalink
Doc: Add gRPC datastore gapic upgrade user guide (#1489)
Browse files Browse the repository at this point in the history 
* chore: Add read me user guide

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* Updating formatting

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* fixing formatting

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* adjusting formatting

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
  • Loading branch information
@cindy-peng @gcf-owl-bot
cindy-peng and gcf-owl-bot[bot] authored Jun 25, 2024
1 parent e7636fd commit 9d61e9b
Show file tree
Hide file tree
Showing 2 changed files with 197 additions and 5 deletions.
98 changes: 97 additions & 1 deletion .readme-partials.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,103 @@ custom_content: |
running on Compute Engine or from your own desktop. To run the example on App Engine, simply move
the code from the main method to your application's servlet class and change the print statements to
display on your webpage.
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 =
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();
```
Testing
-------
Expand Down
104 changes: 100 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,20 +50,20 @@ If you are using Maven without the BOM, add this to your dependencies:
If you are using Gradle 5.x or later, add this to your dependencies:

```Groovy
implementation platform('com.google.cloud:libraries-bom:26.40.0')
implementation platform('com.google.cloud:libraries-bom:26.42.0')
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.20.0'
implementation 'com.google.cloud:google-cloud-datastore:2.20.1'
```

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

```Scala
libraryDependencies += "com.google.cloud" % "google-cloud-datastore" % "2.20.0"
libraryDependencies += "com.google.cloud" % "google-cloud-datastore" % "2.20.1"
```
<!-- {x-version-update-end} -->

Expand Down Expand Up @@ -210,6 +210,102 @@ running on Compute Engine or from your own desktop. To run the example on App En
the code from the main method to your application's servlet class and change the print statements to
display on your webpage.

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 =
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();
```
Testing
-------

Expand Down Expand Up @@ -384,7 +480,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.20.0
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.20.1
[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

0 comments on commit 9d61e9b

Please sign in to comment.