examples: add reflection example (#9955)

Author: YifeiZhuang

examples/example-reflection/README.md

@@ -0,0 +1,106 @@
+gRPC Reflection Example
+================
+
+The reflection example has a Hello World server with `ProtoReflectionService` registered. 
+
+### Build the example
+
+To build the example server, from the `grpc-java/examples/examples-reflection`
+directory:
+```
+$ ../gradlew installDist
+```
+
+This creates the scripts `build/install/example-reflection/bin/reflection-server`.
+
+### Run the example
+
+gRPC Server Reflection provides information about publicly-accessible gRPC services on a server,
+and assists clients at runtime to construct RPC requests and responses without precompiled
+service information. It is used by gRPCurl, which can be used to introspect server protos and
+send/receive test RPCs.
+
+1. To start the reflection example server on its default port of 50051, run:
+```
+$ ./build/install/example-reflection/bin/reflection-server
+```
+
+2. After enabling Server Reflection in a server application, you can use gRPCurl to check its
+services. Instructions on how to install and use gRPCurl can be found at [gRPCurl Installation](https://github.com/fullstorydev/grpcurl#installation)
+
+After installing gRPCurl, open a new terminal and run the commands from the new terminal.
+
+### List all the services exposed at a given port
+
+  ```
+  $ grpcurl -plaintext localhost:50051 list
+  ```
+
+Output
+
+  ```
+  grpc.reflection.v1alpha.ServerReflection
+  helloworld.Greeter
+  ```
+
+### List all the methods of a service
+  ```
+  $ grpcurl -plaintext localhost:50051 helloworld.Greeter
+  ```
+Output
+  ```
+  helloworld.Greeter.SayHello
+  ```
+
+### Describe services and methods
+
+The describe command inspects a method given its full name(in the format of 
+`<package>.<service>.<method>`).
+
+  ```
+$ grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello
+  ```
+
+Output
+
+  ```
+  helloworld.Greeter.SayHello is a method:
+  rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
+  ```
+
+### Inspect message types
+
+We can use the describe 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:
+
+  ```
+$ grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest
+  ```
+
+Output
+
+  ```
+  helloworld.HelloRequest is a message:
+  message HelloRequest {
+    string name = 1;
+  }
+  ```
+
+### Call a remote method
+
+We can send RPCs to a server and get responses using the full method name
+(in the format of `<package>.<service>.<method>`). The `-d <string>` flag represents the request data
+and the -format text flag indicates that the request data is in text format.
+
+  ```
+  $ grpcurl -plaintext -format text -d 'name: "gRPCurl"' \
+    localhost:50051 helloworld.Greeter.SayHello
+  ```
+
+Output
+
+  ```
+  message: "Hello gRPCurl"
+  ```

examples/example-reflection/build.gradle

@@ -0,0 +1,54 @@
+plugins {
+    id 'application' // Provide convenience executables for trying out the examples.
+    // ASSUMES GRADLE 5.6 OR HIGHER. Use plugin version 0.8.10 with earlier gradle versions
+    id 'com.google.protobuf' version '0.8.17'
+    // Generate IntelliJ IDEA's .idea & .iml project files
+    id 'idea'
+    id 'java'
+}
+
+repositories {
+    maven { // The google mirror is less flaky than mavenCentral()
+        url "https://maven-central.storage-download.googleapis.com/maven2/" }
+    mavenCentral()
+    mavenLocal()
+}
+
+sourceCompatibility = 1.8
+targetCompatibility = 1.8
+
+def grpcVersion = '1.55.0-SNAPSHOT' // CURRENT_GRPC_VERSION
+def protocVersion = '3.21.7'
+
+dependencies {
+    implementation "io.grpc:grpc-protobuf:${grpcVersion}"
+    implementation "io.grpc:grpc-services:${grpcVersion}"
+    implementation "io.grpc:grpc-stub:${grpcVersion}"
+    implementation "io.grpc:grpc-netty-shaded:${grpcVersion}"
+    compileOnly "org.apache.tomcat:annotations-api:6.0.53"
+
+}
+
+protobuf {
+    protoc { artifact = "com.google.protobuf:protoc:${protocVersion}" }
+    plugins {
+        grpc { artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}" }
+    }
+    generateProtoTasks {
+        all()*.plugins { grpc {} }
+    }
+}
+
+startScripts.enabled = false
+
+task ReflectionServer(type: CreateStartScripts) {
+    mainClass = 'io.grpc.examples.reflection.ReflectionServer'
+    applicationName = 'reflection-server'
+    outputDir = new File(project.buildDir, 'tmp/scripts/' + name)
+    classpath = startScripts.classpath
+}
+
+applicationDistribution.into('bin') {
+    from(ReflectionServer)
+    fileMode = 0755
+}

examples/example-reflection/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'example-reflection'

examples/example-reflection/src/main/java/io/grpc/examples/reflection/ReflectionServer.java

@@ -0,0 +1,81 @@
+
+package io.grpc.examples.reflection;
+
+import io.grpc.Grpc;
+import io.grpc.InsecureServerCredentials;
+import io.grpc.Server;
+import io.grpc.examples.helloworld.GreeterGrpc;
+import io.grpc.examples.helloworld.HelloReply;
+import io.grpc.examples.helloworld.HelloRequest;
+import io.grpc.protobuf.services.ProtoReflectionService;
+import io.grpc.stub.StreamObserver;
+import java.io.IOException;
+import java.util.concurrent.TimeUnit;
+import java.util.logging.Logger;
+
+/**
+ * Server that manages startup/shutdown of a {@code Greeter} server.
+ */
+public class ReflectionServer {
+  private static final Logger logger = Logger.getLogger(ReflectionServer.class.getName());
+
+  private Server server;
+
+  private void start() throws IOException {
+    /* The port on which the server should run */
+    int port = 50051;
+    server = Grpc.newServerBuilderForPort(port, InsecureServerCredentials.create())
+        .addService(new GreeterImpl())
+        .addService(ProtoReflectionService.newInstance()) // add reflection service
+        .build()
+        .start();
+    logger.info("Server started, listening on " + port);
+    Runtime.getRuntime().addShutdownHook(new Thread() {
+      @Override
+      public void run() {
+        // Use stderr here since the logger may have been reset by its JVM shutdown hook.
+        System.err.println("*** shutting down gRPC server since JVM is shutting down");
+        try {
+          ReflectionServer.this.stop();
+        } catch (InterruptedException e) {
+          e.printStackTrace(System.err);
+        }
+        System.err.println("*** server shut down");
+      }
+    });
+  }
+
+  private void stop() throws InterruptedException {
+    if (server != null) {
+      server.shutdown().awaitTermination(30, TimeUnit.SECONDS);
+    }
+  }
+
+  /**
+   * Await termination on the main thread since the grpc library uses daemon threads.
+   */
+  private void blockUntilShutdown() throws InterruptedException {
+    if (server != null) {
+      server.awaitTermination();
+    }
+  }
+
+  /**
+   * Main launches the server from the command line.
+   */
+  public static void main(String[] args) throws IOException, InterruptedException {
+    final ReflectionServer server = new ReflectionServer();
+    server.start();
+    server.blockUntilShutdown();
+  }
+
+  static class GreeterImpl extends GreeterGrpc.GreeterImplBase {
+
+    @Override
+    public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
+      HelloReply reply = HelloReply.newBuilder().setMessage("Hello " + req.getName()).build();
+      responseObserver.onNext(reply);
+      responseObserver.onCompleted();
+    }
+  }
+}

examples/example-reflection/src/main/proto/helloworld/helloworld.proto

@@ -0,0 +1,37 @@
+// Copyright 2022 The gRPC Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "io.grpc.examples.helloworld";
+option java_outer_classname = "HelloWorldProto";
+option objc_class_prefix = "HLW";
+
+package helloworld;
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}