diff options
author | Eric Gribkoff <ericgribkoff@google.com> | 2017-01-30 12:57:48 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-01-30 12:57:48 -0800 |
commit | e08034cde033bb5cd4a2df1adbf06af67ce7da15 (patch) | |
tree | ba564b8cb1a855cecbb943b6afe3fce7cf0d3079 /documentation | |
parent | 0c0ce37bbd436c421149e8da5b9006ef1a32fcbd (diff) | |
download | grpc-grpc-java-e08034cde033bb5cd4a2df1adbf06af67ce7da15.tar.gz |
documentation: new server reflection tutorial
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/server-reflection-tutorial.md | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/documentation/server-reflection-tutorial.md b/documentation/server-reflection-tutorial.md new file mode 100644 index 000000000..7fd4e40f4 --- /dev/null +++ b/documentation/server-reflection-tutorial.md @@ -0,0 +1,165 @@ +# gRPC Server Reflection Tutorial + +gRPC Server Reflection provides information about publicly-accessible gRPC +services on a server, and assists clients at runtime with constructing RPC +requests and responses without precompiled service information. It is used by +the gRPC command line tool (gRPC CLI), which can be used to introspect server +protos and send/receive test RPCs. Reflection is only supported for +proto-based services. + +## Enable Server Reflection + +gRPC-Java Server Reflection is implemented by +`io.grpc.protobuf.service.ProtoReflectionService` in the `grpc-services` +package. To enable server reflection, you need to add the +`ProtoReflectionService` to your gRPC server. + +For example, to enable server reflection in +`examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java`, we +need to make the following changes: + +```diff +--- a/examples/build.gradle ++++ b/examples/build.gradle +@@ -27,6 +27,7 @@ def grpcVersion = '1.1.0-SNAPSHOT' // CURRENT_GRPC_VERSION + dependencies { + compile "io.grpc:grpc-netty:${grpcVersion}" + compile "io.grpc:grpc-protobuf:${grpcVersion}" ++ compile "io.grpc:grpc-services:${grpcVersion}" + compile "io.grpc:grpc-stub:${grpcVersion}" + + testCompile "junit:junit:4.11" +diff --git a/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java b/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java +index ce1158a4..788bcc62 100644 +--- a/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java ++++ b/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java +@@ -33,6 +33,7 @@ package io.grpc.examples.helloworld; + + import io.grpc.Server; + import io.grpc.ServerBuilder; ++import io.grpc.protobuf.service.ProtoReflectionService; + import io.grpc.stub.StreamObserver; + + import java.io.IOException; +@@ -51,6 +52,7 @@ public class HelloWorldServer { + int port = 50051; + server = ServerBuilder.forPort(port) + .addService(new GreeterImpl()) ++ .addService(ProtoReflectionService.getInstance()) + .build() + .start(); + logger.info("Server started, listening on " + port); +``` + +In the following examples, we assume you have made these changes to +enable reflection in `HelloWorldServer.java`. + +## gRPC CLI + +After enabling server reflection in a server application, you can use gRPC +CLI to get information about its available services. gRPC CLI is written +in C++. Instructions on how to build gRPC CLI can be found at +[command_line_tool.md](https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md). + +## Use gRPC CLI to check services + +First, build and start the `hello-world-server`: + +```sh +$ cd examples/ +$ ./gradlew installDist +$ build/install/examples/bin/hello-world-server +``` + +Open a new terminal and make sure you are in the directory where the `grpc_cli` +binary is located: + +```sh +$ cd <grpc-cpp-directory>/bins/opt +``` + +### List services + +`grpc_cli ls` command lists services and methods exposed at a given port: + +- List all the services exposed at a given port + + ```sh + $ ./grpc_cli ls localhost:50051 + ``` + + output: + ```sh + helloworld.Greeter + grpc.reflection.v1alpha.ServerReflection + ``` + +- List one service with details + + `grpc_cli ls` command inspects a service given its full name (in the format of + \<package\>.\<service\>). It can print information with a long listing format + when `-l` flag is set. This flag can be used to get more details about a + service. + + ```sh + $ ./grpc_cli ls localhost:50051 helloworld.Greeter -l + ``` + + output: + ```sh + filename: helloworld.proto + package: helloworld; + service Greeter { + rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {} + } + + ``` + +### List methods + +- List one method with details + + `grpc_cli ls` command also inspects a method given its full name (in the + format of \<package\>.\<service\>.\<method\>). + + ```sh + $ ./grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l + ``` + + output: + ```sh + rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {} + ``` + +### Inspect message types + +We can use`grpc_cli type` command to inspect request/response types given the +full name of the type (in the format of \<package\>.\<type\>). + +- Get information about the request type + + ```sh + $ ./grpc_cli type localhost:50051 helloworld.HelloRequest + ``` + + output: + ```sh + message HelloRequest { + optional string name = 1[json_name = "name"]; + } + ``` + +### Call a remote method + +We can send RPCs to a server and get responses using `grpc_cli call` command. + +- Call a unary method + + ```sh + $ ./grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'" + ``` + + output: + ```sh + message: "Hello gRPC CLI" + ``` |