Java Generated Code Reference

Packages

For each service defined in a .proto file, the Java code generation produces aJava class. The class name is the service’s name suffixed by Grpc. The packagefor the generated code is specified in the .proto file using the java_packageoption.

For example, if ServiceName is defined in a .proto file containing thefollowing:

  1. package grpcexample;
  3. option java_package = "io.grpc.examples";

Then the generated class will be io.grpc.examples.ServiceNameGrpc.

If java_package is not specified, the generated class will use the packageas specified in the .proto file. This should be avoided, as proto packagesusually do not begin with a reversed domain name.

Service Stub

The generated Java code contains an inner abstract class suffixed withImplBase, such as ServiceNameImplBase. This class defines one Java methodfor each method in the service definition. It is up to the service implementerto extend this class and implement the functionality of these methods. Withoutbeing overridden, the methods return an error to the client saying the method isunimplemented.

The signatures of the stub methods in ServiceNameImplBase vary depending onthe type of RPCs it handles. There are four types of gRPC service methods:unary, server-streaming, client-streaming, and bidirectional-streaming.

Unary

The service stub signature for a unary RPC method unaryExample:

  1. public void unaryExample(
  2.     RequestType request,
  3.     StreamObserver<ResponseType> responseObserver)

Server-streaming

The service stub signature for a server-streaming RPC methodserverStreamingExample:

  1. public void serverStreamingExample(
  2.     RequestType request,
  3.     StreamObserver<ResponseType> responseObserver)

Notice that the signatures for unary and server-streaming RPCs are the same. Asingle RequestType is received from the client, and the service implementationsends its response(s) by invoking responseObserver.onNext(ResponseType response).

Client-streaming

The service stub signature for a client-streaming RPC methodclientStreamingExample:

  1. public StreamObserver<RequestType> clientStreamingExample(
  2.     StreamObserver<ResponseType> responseObserver)

Bidirectional-streaming

The service stub signature for a bidirectional-streaming RPC methodbidirectionalStreamingExample:

  1. public StreamObserver<RequestType> bidirectionalStreamingExample(
  2.     StreamObserver<ResponseType> responseObserver)

The signatures for client and bidirectional-streaming RPCs are the same. Sincethe client can send multiple messages to the service, the service implementationis reponsible for returning a StreamObserver<RequestType> instance. ThisStreamObserver is invoked whenever additional messages are received from theclient.

Client Stubs

The generated class also contains stubs for use by gRPC clients to call methodsdefined by the service. Each stub wraps a Channel, supplied by the user of thegenerated code. The stub uses this channel to send RPCs to the service.

gRPC Java generates code for three types of stubs: asynchronous, blocking, andfuture. Each type of stub has a corresponding class in the generated code, suchas ServiceNameStub, ServiceNameBlockingStub, and ServiceNameFutureStub.

Asynchronous Stub

RPCs made via an asynchronous stub operate entirely through callbacks onStreamObserver.

The asynchronous stub contains one Java method for each method from the servicedefinition.

A new asynchronous stub is instantiated via the ServiceNameGrpc.newStub(Channel channel) static method.

Unary

The asynchronous stub signature for a unary RPC method unaryExample:

  1. public void unaryExample(
  2.     RequestType request,
  3.     StreamObserver<ResponseType> responseObserver)

Server-streaming

The asynchronous stub signature for a server-streaming RPC methodserverStreamingExample:

  1. public void serverStreamingExample(
  2.     RequestType request,
  3.     StreamObserver<ResponseType> responseObserver)

Client-streaming

The asynchronous stub signature for a client-streaming RPC methodclientStreamingExample:

  1. public StreamObserver<RequestType> clientStreamingExample(
  2.     StreamObserver<ResponseType> responseObserver)

Bidirectional-streaming

The asynchronous stub signature for a bidirectional-streaming RPC methodbidirectionalStreamingExample:

  1. public StreamObserver<RequestType> bidirectionalStreamingExample(
  2.     StreamObserver<ResponseType> responseObserver)

Blocking Stub

RPCs made through a blocking stub, as the name implies, block until the responsefrom the service is available.

The blocking stub contains one Java method for each unary and server-streamingmethod in the service definition. Blocking stubs do not support client-streamingor bidirectional-streaming RPCs.

A new blocking stub is instantiated via theServiceNameGrpc.newBlockingStub(Channel channel) static method.

Unary

The blocking stub signature for a unary RPC method unaryExample:

  1. public ResponseType unaryExample(RequestType request)

Server-streaming

The blocking stub signature for a server-streaming RPC methodserverStreamingExample:

  1. public Iterator<ResponseType> serverStreamingExample(RequestType request)

Future Stub

RPCs made via a future stub wrap the return value of the asynchronous stub in aGrpcFuture<ResponseType>, which implements thecom.google.common.util.concurrent.ListenableFuture interface.

The future stub contains one Java method for each unary method in the servicedefinition. Future stubs do not support streaming calls.

A new future stub is instantiated via the ServiceNameGrpc.newFutureStub(Channel channel) static method.

Unary

The future stub signature for a unary RPC method unaryExample:

  1. public ListenableFuture<ResponseType> unaryExample(RequestType request)

Codegen

Typically the build system handles creation of the gRPC generated code.

For protobuf-based codegen, you can put your .proto files in the src/main/protoand src/test/proto directories along with an appropriate plugin.

A typicalprotobuf-maven-plugin configuration for generating gRPC and ProtocolBuffers code would look like the following:

  1. <build>
  2.   <extensions>
  3.     <extension>
  4.       <groupId>kr.motd.maven</groupId>
  5.       <artifactId>os-maven-plugin</artifactId>
  6.       <version>1.4.1.Final</version>
  7.     </extension>
  8.   </extensions>
  9.   <plugins>
  10.     <plugin>
  11.       <groupId>org.xolstice.maven.plugins</groupId>
  12.       <artifactId>protobuf-maven-plugin</artifactId>
  13.       <version>0.5.0</version>
  14.       <configuration>
  15.         <protocArtifact>com.google.protobuf:protoc:3.3.0:exe:${os.detected.classifier}</protocArtifact>
  16.         <pluginId>grpc-java</pluginId>
  17.         <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.4.0:exe:${os.detected.classifier}</pluginArtifact>
  18.       </configuration>
  19.       <executions>
  20.         <execution>
  21.           <goals>
  22.             <goal>compile</goal>
  23.             <goal>compile-custom</goal>
  24.           </goals>
  25.         </execution>
  26.       </executions>
  27.     </plugin>
  28.   </plugins>
  29. </build>

Eclipse and NetBeans users should also look at os-maven-plugin'sIDE documentation.

A typicalprotobuf-gradle-plugin configuration would look like the following:

  1. apply plugin: 'java'
  2. apply plugin: 'com.google.protobuf'
  4. buildscript {
  5.   repositories {
  6.     mavenCentral()
  7.   }
  8.   dependencies {
  9.     // ASSUMES GRADLE 2.12 OR HIGHER. Use plugin version 0.7.5 with earlier
  10.     // gradle versions
  11.     classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.0'
  12.   }
  13. }
  15. protobuf {
  16.   protoc {
  17.     artifact = "com.google.protobuf:protoc:3.2.0"
  18.   }
  19.   plugins {
  20.     grpc {
  21.       artifact = 'io.grpc:protoc-gen-grpc-java:1.4.0'
  22.     }
  23.   }
  24.   generateProtoTasks {
  25.     all()*.plugins {
  26.       grpc {}
  27.     }
  28.   }
  29. }

Bazel developers can use thejava_grpc_libraryrule, typically as follows:

  1. load("@grpc_java//:java_grpc_library.bzl", "java_grpc_library")
  3. proto_library(
  4.     name = "helloworld_proto",
  5.     srcs = ["src/main/proto/helloworld.proto"],
  6. )
  8. java_proto_library(
  9.     name = "helloworld_java_proto",
  10.     deps = [":helloworld_proto"],
  11. )
  13. java_grpc_library(
  14.     name = "helloworld_java_grpc",
  15.     srcs = [":helloworld_proto"],
  16.     deps = [":helloworld_java_proto"],
  17. )

Android developers please seethis for reference.

If you wish to invoke the protobuf plugin for gRPC Java directly,the command-line syntax is as follows:

  1. $ protoc --plugin=protoc-gen-grpc-java \
  2.   --grpc-java_out="$OUTPUT_FILE" --proto_path="$DIR_OF_PROTO_FILE" "$PROTO_FILE"