2020-08-05 23:55:47 +08:00
gRPC Examples
2015-02-19 05:26:48 +08:00
==============================================
2020-08-05 23:55:47 +08:00
The examples require `grpc-java` to already be built. You are strongly encouraged
to check out a git release tag, since there will already be a build of gRPC
2016-06-25 09:18:06 +08:00
available. Otherwise you must follow [COMPILING ](../COMPILING.md ).
2017-01-19 01:06:45 +08:00
You may want to read through the
2020-08-05 23:55:47 +08:00
[Quick Start ](https://grpc.io/docs/languages/java/quickstart )
2017-01-19 01:06:45 +08:00
before trying out the examples.
2018-12-08 02:48:35 +08:00
## Basic examples
- [Hello world ](src/main/java/io/grpc/examples/helloworld )
- [Route guide ](src/main/java/io/grpc/examples/routeguide )
- [Metadata ](src/main/java/io/grpc/examples/header )
- [Error handling ](src/main/java/io/grpc/examples/errorhandling )
- [Compression ](src/main/java/io/grpc/examples/experimental )
- [Flow control ](src/main/java/io/grpc/examples/manualflowcontrol )
2023-03-23 03:14:00 +08:00
- [Wait For Ready ](src/main/java/io/grpc/examples/waitforready )
2018-12-08 02:48:35 +08:00
- [Json serialization ](src/main/java/io/grpc/examples/advanced )
2019-06-20 02:53:54 +08:00
- < details >
< summary > Hedging< / summary >
The [hedging example ](src/main/java/io/grpc/examples/hedging ) demonstrates that enabling hedging
can reduce tail latency. (Users should note that enabling hedging may introduce other overhead;
and in some scenarios, such as when some server resource gets exhausted for a period of time and
almost every RPC during that time has high latency or fails, hedging may make things worse.
Setting a throttle in the service config is recommended to protect the server from too many
inappropriate retry or hedging requests.)
The server and the client in the example are basically the same as those in the
[hello world ](src/main/java/io/grpc/examples/helloworld ) example, except that the server mimics a
long tail of latency, and the client sends 2000 requests and can turn on and off hedging.
To mimic the latency, the server randomly delays the RPC handling by 2 seconds at 10% chance, 5
seconds at 5% chance, and 10 seconds at 1% chance.
When running the client enabling the following hedging policy
```json
"hedgingPolicy": {
"maxAttempts": 3,
2019-06-26 06:29:52 +08:00
"hedgingDelay": "1s"
2019-06-20 02:53:54 +08:00
}
```
Then the latency summary in the client log is like the following
```text
Total RPCs sent: 2,000. Total RPCs failed: 0
[Hedging enabled]
========================
50% latency: 0ms
90% latency: 6ms
95% latency: 1,003ms
99% latency: 2,002ms
99.9% latency: 2,011ms
Max latency: 5,272ms
========================
```
See [the section below ](#to-build-the-examples ) for how to build and run the example. The
executables for the server and the client are `hedging-hello-world-server` and
`hedging-hello-world-client` .
To disable hedging, set environment variable `DISABLE_HEDGING_IN_HEDGING_EXAMPLE=true` before
running the client. That produces a latency summary in the client log like the following
```text
Total RPCs sent: 2,000. Total RPCs failed: 0
[Hedging disabled]
========================
50% latency: 0ms
90% latency: 2,002ms
95% latency: 5,002ms
99% latency: 10,004ms
99.9% latency: 10,007ms
Max latency: 10,007ms
========================
```
< / details >
2020-06-17 03:18:42 +08:00
- < details >
< summary > Retrying< / summary >
2020-08-05 23:55:47 +08:00
The [retrying example ](src/main/java/io/grpc/examples/retrying ) provides a HelloWorld gRPC client &
2020-06-17 03:18:42 +08:00
server which demos the effect of client retry policy configured on the [ManagedChannel](
2020-08-05 23:55:47 +08:00
../api/src/main/java/io/grpc/ManagedChannel.java) via [gRPC ServiceConfig](
https://github.com/grpc/grpc/blob/master/doc/service_config.md). Retry policy implementation &
2020-06-17 03:18:42 +08:00
configuration details are outlined in the [proposal ](https://github.com/grpc/proposal/blob/master/A6-client-retries.md ).
2020-08-05 23:55:47 +08:00
This retrying example is very similar to the [hedging example ](src/main/java/io/grpc/examples/hedging ) in its setup.
2020-06-17 03:18:42 +08:00
The [RetryingHelloWorldServer ](src/main/java/io/grpc/examples/retrying/RetryingHelloWorldServer.java ) responds with
2020-08-05 23:55:47 +08:00
a status UNAVAILABLE error response to a specified percentage of requests to simulate server resource exhaustion and
general flakiness. The [RetryingHelloWorldClient ](src/main/java/io/grpc/examples/retrying/RetryingHelloWorldClient.java ) makes
a number of sequential requests to the server, several of which will be retried depending on the configured policy in
[retrying_service_config.json ](src/main/resources/io/grpc/examples/retrying/retrying_service_config.json ). Although
the requests are blocking unary calls for simplicity, these could easily be changed to future unary calls in order to
2020-06-17 03:18:42 +08:00
test the result of request concurrency with retry policy enabled.
2020-08-05 23:55:47 +08:00
2020-06-17 03:18:42 +08:00
One can experiment with the [RetryingHelloWorldServer ](src/main/java/io/grpc/examples/retrying/RetryingHelloWorldServer.java )
failure conditions to simulate server throttling, as well as alter policy values in the [retrying_service_config.json](
2020-08-05 23:55:47 +08:00
src/main/resources/io/grpc/examples/retrying/retrying_service_config.json) to see their effects. To disable retrying
entirely, set environment variable `DISABLE_RETRYING_IN_RETRYING_EXAMPLE=true` before running the client.
Disabling the retry policy should produce many more failed gRPC calls as seen in the output log.
2020-06-17 03:18:42 +08:00
See [the section below ](#to-build-the-examples ) for how to build and run the example. The
executables for the server and the client are `retrying-hello-world-server` and
`retrying-hello-world-client` .
2020-08-05 23:55:47 +08:00
2020-06-17 03:18:42 +08:00
< / details >
2023-03-31 04:32:04 +08:00
- < details >
< summary > Health Service< / summary >
The [health service example ](src/main/java/io/grpc/examples/healthservice )
provides a HelloWorld gRPC server that doesn't like short names along with a
health service. It also provides a client application which makes HelloWorld
calls and checks the health status.
The client application also shows how the round robin load balancer can
utilize the health status to avoid making calls to a service that is
not actively serving.
< / details >
2023-03-18 07:27:33 +08:00
- [Keep Alive ](src/main/java/io/grpc/examples/keepalive )
2019-06-20 02:53:54 +08:00
### <a name="to-build-the-examples"></a> To build the examples
2015-02-19 05:26:48 +08:00
2018-12-07 05:17:59 +08:00
1. ** [Install gRPC Java library SNAPSHOT locally, including code generation plugin ](../COMPILING.md ) (Only need this step for non-released versions, e.g. master HEAD).**
2019-10-08 01:52:39 +08:00
2. From grpc-java/examples directory:
2015-05-07 22:37:51 +08:00
```
2016-06-25 09:18:06 +08:00
$ ./gradlew installDist
2015-05-07 22:37:51 +08:00
```
2018-12-07 04:03:25 +08:00
This creates the scripts `hello-world-server` , `hello-world-client` ,
2018-12-08 02:48:35 +08:00
`route-guide-server` , `route-guide-client` , etc. in the
2016-07-28 07:46:15 +08:00
`build/install/examples/bin/` directory that run the examples. Each
2015-05-07 22:37:51 +08:00
example requires the server to be running before starting the client.
2015-02-26 00:42:10 +08:00
2015-05-07 22:37:51 +08:00
For example, to try the hello world example first run:
2015-02-19 05:26:48 +08:00
```
2016-07-28 07:46:15 +08:00
$ ./build/install/examples/bin/hello-world-server
2015-02-19 05:26:48 +08:00
```
2015-05-07 22:37:51 +08:00
And in a different terminal window run:
2015-02-19 05:26:48 +08:00
```
2016-07-28 07:46:15 +08:00
$ ./build/install/examples/bin/hello-world-client
2015-02-19 05:26:48 +08:00
```
That's it!
2015-02-26 21:21:03 +08:00
2020-08-05 23:55:47 +08:00
For more information, refer to gRPC Java's [README ](../README.md ) and
[tutorial ](https://grpc.io/docs/languages/java/basics ).
2016-06-25 09:18:06 +08:00
2018-12-08 02:48:35 +08:00
### Maven
2016-06-25 09:18:06 +08:00
If you prefer to use Maven:
2018-12-07 05:17:59 +08:00
1. ** [Install gRPC Java library SNAPSHOT locally, including code generation plugin ](../COMPILING.md ) (Only need this step for non-released versions, e.g. master HEAD).**
2. Run in this directory:
2016-06-25 09:18:06 +08:00
```
$ mvn verify
$ # Run the server
$ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldServer
$ # In another terminal run the client
$ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldClient
```
2016-11-16 06:15:55 +08:00
2018-12-08 02:48:35 +08:00
### Bazel
2017-06-30 03:25:54 +08:00
If you prefer to use Bazel:
```
$ bazel build :hello-world-server :hello-world-client
2018-12-07 04:03:25 +08:00
$ # Run the server
2017-06-30 03:25:54 +08:00
$ bazel-bin/hello-world-server
$ # In another terminal run the client
$ bazel-bin/hello-world-client
```
2018-12-07 04:03:25 +08:00
## Other examples
2018-12-08 02:48:35 +08:00
- [Android examples ](android )
2018-12-07 04:03:25 +08:00
2018-12-08 02:48:35 +08:00
- Secure channel examples
2018-12-07 04:03:25 +08:00
2018-12-08 02:48:35 +08:00
+ [TLS examples ](example-tls )
2018-12-07 04:03:25 +08:00
2018-12-08 02:48:35 +08:00
+ [ALTS examples ](example-alts )
2018-12-07 04:03:25 +08:00
2019-06-21 05:45:53 +08:00
- [Google Authentication ](example-gauth )
2019-06-20 02:53:54 +08:00
2020-03-18 08:43:31 +08:00
- [JWT-based Authentication ](example-jwt-auth )
2023-09-19 00:56:16 +08:00
- [OAuth2-based Authentication ](example-oauth )
2023-08-15 08:00:29 +08:00
- [Pre-serialized messages ](src/main/java/io/grpc/examples/preserialized )
2018-12-08 02:48:35 +08:00
## Unit test examples
2016-11-16 06:15:55 +08:00
Examples for unit testing gRPC clients and servers are located in [examples/src/test ](src/test ).
2019-09-19 04:24:56 +08:00
In general, we DO NOT allow overriding the client stub and we DO NOT support mocking final methods
in gRPC-Java library. Users should be cautious that using tools like PowerMock or
[mockito-inline ](https://search.maven.org/search?q=g:org.mockito%20a:mockito-inline ) can easily
break this rule of thumb. We encourage users to leverage `InProcessTransport` as demonstrated in the
examples to write unit tests. `InProcessTransport` is light-weight and runs the server
2016-11-16 06:15:55 +08:00
and client in the same process without any socket/TCP connection.
2019-05-30 23:52:13 +08:00
Mocking the client stub provides a false sense of security when writing tests. Mocking stubs and responses
2020-04-17 04:55:05 +08:00
allows for tests that don't map to reality, causing the tests to pass, but the system-under-test to fail.
2019-05-30 23:52:13 +08:00
The gRPC client library is complicated, and accurately reproducing that complexity with mocks is very hard.
You will be better off and write less code by using `InProcessTransport` instead.
Example bugs not caught by mocked stub tests include:
* Calling the stub with a `null` message
* Not calling `close()`
* Sending invalid headers
* Ignoring deadlines
* Ignoring cancellation
2016-11-16 06:15:55 +08:00
For testing a gRPC client, create the client with a real stub
using an
[InProcessChannel ](../core/src/main/java/io/grpc/inprocess/InProcessChannelBuilder.java ),
and test it against an
[InProcessServer ](../core/src/main/java/io/grpc/inprocess/InProcessServerBuilder.java )
with a mock/fake service implementation.
For testing a gRPC server, create the server as an InProcessServer,
and test it against a real client stub with an InProcessChannel.
2017-06-06 07:32:18 +08:00
The gRPC-java library also provides a JUnit rule,
2018-12-06 04:43:02 +08:00
[GrpcCleanupRule ](../testing/src/main/java/io/grpc/testing/GrpcCleanupRule.java ), to do the graceful
2018-05-15 02:30:38 +08:00
shutdown boilerplate for you.
2018-12-08 02:48:35 +08:00
## Even more examples
A wide variety of third-party examples can be found [here ](https://github.com/saturnism/grpc-java-by-example ).