Skip to content

Commit 9d61e9b

Browse files
cindy-penggcf-owl-bot[bot]
cindy-peng
and
gcf-owl-bot[bot]
authored
Doc: Add gRPC datastore gapic upgrade user guide (#1489)
* 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>
1 parent e7636fd commit 9d61e9b

File tree

2 files changed

+197
-5
lines changed

2 files changed

+197
-5
lines changed

‎.readme-partials.yaml

Lines changed: 97 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,103 @@ custom_content: |
105105
running on Compute Engine or from your own desktop. To run the example on App Engine, simply move
106106
the code from the main method to your application's servlet class and change the print statements to
107107
display on your webpage.
108-
108+
109+
gRPC Java Datastore Client User Guide
110+
-------
111+
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.
112+
113+
#### Download Instructions
114+
Instructions:
115+
1. Clone the grpc-experimental branch from GitHub:
116+
```python
117+
git clone -b grpc-experimental https://github.com/googleapis/java-datastore.git
118+
```
119+
2. Run the following commands to build the library:
120+
```python
121+
# Go to the directory the code was downloaded to
122+
cd java-datastore/
123+
124+
# Build the library
125+
mvn clean install -DskipTests=true
126+
```
127+
3. Add the following dependency to your project:
128+
```xml
129+
<dependency>
130+
<groupId>com.google.cloud</groupId>
131+
<artifactId>google-cloud-datastore</artifactId>
132+
<version>2.20.0-grpc-experimental-1-SNAPSHOT</version>
133+
</dependency>
134+
```
135+
136+
#### How to Use
137+
To opt-in to the gRPC transport behavior, simply add the below line of code (`setTransportOptions`) to your Datastore client instantiation.
138+
139+
Example:
140+
```java
141+
DatastoreOptions datastoreOptions =
142+
DatastoreOptions.newBuilder()
143+
.setProjectId("my-project")
144+
.setDatabaseId("my-database")
145+
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
146+
.build();
147+
```
148+
Setting the transport options explicitly to `GrpcTransportOptions` will signal the client to use gRPC instead of HTTP when making calls to the server.
149+
150+
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.
151+
Example:
152+
```java
153+
// will default to existing HTTP transport behavior
154+
DatastoreOptions datastoreOptions = DatastoreOptions.newBuilder()
155+
.setProjectId("my-project")
156+
.setDatabaseId("my-database")
157+
.build();
158+
159+
// will also default to existing HTTP transport behavior
160+
DatastoreOptions datastoreOptions =
161+
DatastoreOptions.newBuilder()
162+
.setProjectId("my-project")
163+
.setDatabaseId("my-database")
164+
.setTransportOptions(HttpTransportOptions.newBuilder()
165+
.setConnectTimeout(1000)
166+
.build()).build();
167+
```
168+
169+
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.
170+
171+
#### Verify Datastore Transport Options Type
172+
To verify which type of TransportOptions you have successfully configured, you can use the below lines of code to compare transport options type:
173+
```java
174+
// checks if using gRPC transport options
175+
boolean isGRPC = datastore.getOptions().getTransportOptions() instanceof GrpcTransportOptions;
176+
177+
// checks if using HTTP transport options
178+
boolean isHTTP = datastore.getOptions().getTransportOptions() instanceof HTTPTransportOptions;
179+
```
180+
181+
#### New Features
182+
There are new gRPC specific features available to use in this update.
183+
184+
##### Channel Pooling
185+
To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions.
186+
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.
187+
188+
Example:
189+
```java
190+
InstantiatingGrpcChannelProvider channelProvider =
191+
DatastoreSettings.defaultGrpcTransportProviderBuilder()
192+
.setChannelPoolSettings(
193+
ChannelPoolSettings.builder()
194+
.setInitialChannelCount(MIN_VAL)
195+
.setMaxChannelCount(MAX_VAL)
196+
.build())
197+
.build();
198+
199+
DatastoreOptions options = DatastoreOptions.newBuilder()
200+
.setProjectId("my-project")
201+
.setChannelProvider(channelProvider)
202+
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
203+
.build();
204+
```
109205
Testing
110206
-------
111207

‎README.md

Lines changed: 100 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,20 +50,20 @@ If you are using Maven without the BOM, add this to your dependencies:
5050
If you are using Gradle 5.x or later, add this to your dependencies:
5151

5252
```Groovy
53-
implementation platform('com.google.cloud:libraries-bom:26.40.0')
53+
implementation platform('com.google.cloud:libraries-bom:26.42.0')
5454
5555
implementation 'com.google.cloud:google-cloud-datastore'
5656
```
5757
If you are using Gradle without BOM, add this to your dependencies:
5858

5959
```Groovy
60-
implementation 'com.google.cloud:google-cloud-datastore:2.20.0'
60+
implementation 'com.google.cloud:google-cloud-datastore:2.20.1'
6161
```
6262

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

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

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

213+
gRPC Java Datastore Client User Guide
214+
-------
215+
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.
216+
217+
#### Download Instructions
218+
Instructions:
219+
1. Clone the grpc-experimental branch from GitHub:
220+
```python
221+
git clone -b grpc-experimental https://github.com/googleapis/java-datastore.git
222+
```
223+
2. Run the following commands to build the library:
224+
```python
225+
# Go to the directory the code was downloaded to
226+
cd java-datastore/
227+
228+
# Build the library
229+
mvn clean install -DskipTests=true
230+
```
231+
3. Add the following dependency to your project:
232+
```xml
233+
<dependency>
234+
<groupId>com.google.cloud</groupId>
235+
<artifactId>google-cloud-datastore</artifactId>
236+
<version>2.20.0-grpc-experimental-1-SNAPSHOT</version>
237+
</dependency>
238+
```
239+
240+
#### How to Use
241+
To opt-in to the gRPC transport behavior, simply add the below line of code (`setTransportOptions`) to your Datastore client instantiation.
242+
243+
Example:
244+
```java
245+
DatastoreOptions datastoreOptions =
246+
DatastoreOptions.newBuilder()
247+
.setProjectId("my-project")
248+
.setDatabaseId("my-database")
249+
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
250+
.build();
251+
```
252+
Setting the transport options explicitly to `GrpcTransportOptions` will signal the client to use gRPC instead of HTTP when making calls to the server.
253+
254+
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.
255+
Example:
256+
```java
257+
// will default to existing HTTP transport behavior
258+
DatastoreOptions datastoreOptions = DatastoreOptions.newBuilder()
259+
.setProjectId("my-project")
260+
.setDatabaseId("my-database")
261+
.build();
262+
263+
// will also default to existing HTTP transport behavior
264+
DatastoreOptions datastoreOptions =
265+
DatastoreOptions.newBuilder()
266+
.setProjectId("my-project")
267+
.setDatabaseId("my-database")
268+
.setTransportOptions(HttpTransportOptions.newBuilder()
269+
.setConnectTimeout(1000)
270+
.build()).build();
271+
```
272+
273+
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.
274+
275+
#### Verify Datastore Transport Options Type
276+
To verify which type of TransportOptions you have successfully configured, you can use the below lines of code to compare transport options type:
277+
```java
278+
// checks if using gRPC transport options
279+
boolean isGRPC = datastore.getOptions().getTransportOptions() instanceof GrpcTransportOptions;
280+
281+
// checks if using HTTP transport options
282+
boolean isHTTP = datastore.getOptions().getTransportOptions() instanceof HTTPTransportOptions;
283+
```
284+
285+
#### New Features
286+
There are new gRPC specific features available to use in this update.
287+
288+
##### Channel Pooling
289+
To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions.
290+
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.
291+
292+
Example:
293+
```java
294+
InstantiatingGrpcChannelProvider channelProvider =
295+
DatastoreSettings.defaultGrpcTransportProviderBuilder()
296+
.setChannelPoolSettings(
297+
ChannelPoolSettings.builder()
298+
.setInitialChannelCount(MIN_VAL)
299+
.setMaxChannelCount(MAX_VAL)
300+
.build())
301+
.build();
302+
303+
DatastoreOptions options = DatastoreOptions.newBuilder()
304+
.setProjectId("my-project")
305+
.setChannelProvider(channelProvider)
306+
.setTransportOptions(GrpcTransportOptions.newBuilder().build())
307+
.build();
308+
```
213309
Testing
214310
-------
215311

@@ -384,7 +480,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
384480
[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-datastore/java11.html
385481
[stability-image]: https://img.shields.io/badge/stability-stable-green
386482
[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-datastore.svg
387-
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.20.0
483+
[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-datastore/2.20.1
388484
[authentication]: https://github.com/googleapis/google-cloud-java#authentication
389485
[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
390486
[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles

0 commit comments

Comments
 (0)