Code generation

This page explains the structure of the code generated by the Piezo plugin. To configure your build, please see the Installation page.

The protocol buffer IDL allows the declaration of RPC services in the same .proto files you define proto messages:

service TimeService {
  rpc GetTime (TimeRequest) returns (TimeResponse);
}

By default, the protocol buffer compiler will parse but ignore such declarations. The Piezo plugin taps into the declarations and translate service definitions into .java files that can then be used to expose and access the service.

For each service defined in a .proto file, the Piezo plugin will generate a class named after the service:

public class TimeService {
  public static interface Interface {
    public ListenableFuture<TimeResponse> getTime(TimeRequest request);
  }
  public static Interface newStub(Client client);
  public static Service newService(Interface implementation);
}

An inner interface (always named Interface) will be declared in the service class. This interface is the representation of the service on both the server and client side. Each method is built as such:

• the name is translated to a standard lowerCamel Java method name;
• it take a single argument, of the type declared in the .proto file;
• the return type is a ListenableFuture that wraps the response RPC response type.

The service class contains two more methods of interest:

• newStub() takes a single argument of type Client and returns an implementation of the above-declared TimeService.Interface. It is intended to be used on the client-side to instantiate a stub that will use a client connected to a remote server.
• newService takes a concrete implementation of the generated TimeService.Interface and returns a concrete Service implementations. The returned object can then be surfaced through a Server

As per the Maven convention, the files will be generated under target/generated-sources/protobuf/java. The generated code's package will derived from the declarations in the .proto file:

• The java_package_name option if it is present;
• The declared proto package otherwise.

By default, the protocol buffer compiler will declare all the generated Java classes as static inner types of a single outer class which is then written as a single .java file. In this scenario, each service class generated by Piezo will also be declared as a static inner class in that file. However, In case the java_multiple_files option is enabled in the .proto file, the Piezo plugin will write each service class into a separate file.