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
available. Otherwise you must follow COMPILING.
You may want to read through the Quick Start before trying out the examples.
-
Install gRPC Java library SNAPSHOT locally, including code generation plugin (Only need this step for non-released versions, e.g. master HEAD).
-
From grpc-java/examples directory:
$ ./gradlew installDist
This creates the scripts hello-world-server
, hello-world-client
,
route-guide-server
, route-guide-client
, etc. in the
build/install/examples/bin/
directory that run the examples. Each
example requires the server to be running before starting the client.
For example, to try the hello world example first run:
$ ./build/install/examples/bin/hello-world-server
And in a different terminal window run:
$ ./build/install/examples/bin/hello-world-client
That's it!
For more information, refer to gRPC Java's README and tutorial.
If you prefer to use Maven:
-
Install gRPC Java library SNAPSHOT locally, including code generation plugin (Only need this step for non-released versions, e.g. master HEAD).
-
Run in this directory:
$ 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
If you prefer to use Bazel:
$ bazel build :hello-world-server :hello-world-client
$ # Run the server
$ bazel-bin/hello-world-server
$ # In another terminal run the client
$ bazel-bin/hello-world-client
-
Secure channel examples
Examples for unit testing gRPC clients and servers are located in examples/src/test.
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 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
and client in the same process without any socket/TCP connection.
Mocking the client stub provides a false sense of security when writing tests. Mocking stubs and responses
allows for tests that don't map to reality, causing the tests to pass, but the system-under-test to fail.
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
For testing a gRPC client, create the client with a real stub using an InProcessChannel, and test it against an InProcessServer 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.
The gRPC-java library also provides a JUnit rule, GrpcCleanupRule, to do the graceful shutdown boilerplate for you.
A wide variety of third-party examples can be found here.