Protobuf Service Descriptors
gRPC uses the Protobuf .proto
file format to define your messages, services and some aspects of the code generation.
For an in-depth description see the official documentation, but here are a few quick examples:
Messages
Messages are defined in the same way protobuf definitions are used for serialization:
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
Full source at GitHub
Services
Those messages can be used to define services:
// The greeting service definition.
service GreeterService {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
rpc ItKeepsTalking (stream HelloRequest) returns (HelloReply) {}
rpc ItKeepsReplying (HelloRequest) returns (stream HelloReply) {}
rpc StreamHellos (stream HelloRequest) returns (stream HelloReply) {}
}
Full source at GitHub
Both the request and the response consists of either a single message or a stream of messages.
Code generation options
There are a number of options that can be set in the .proto definition that influence how the code is generated:
option java_multiple_files = true;
option java_package = "example.myapp.helloworld.grpc";
option java_outer_classname = "HelloWorldProto";
package helloworld;
Full source at GitHub
The (optional) ‘package’ in the .proto
is used to resolve references from one .proto
file to another. It can also be used for the package name in the generated code, but it is common to use the separate java_package
option to override it. For akka-grpc examples our convention is to choose a java_package
ending in .grpc
to easily distinguish between generated and regular code.
For the Java code generation, by default all message classes are placed in a large class whose name is determined by the java_outer_classname
setting. By setting the java_multiple_files
option, the message classes will be moved outside this outer class, but the ‘outer’ class is still generated with some metadata and utilities.
For the Scala code generation, by default the mechanism described in the ScalaPB documentation is used, with the flat_package
option enabled.