生成コードリファレンス
生成コードリファレンス
パッケージ
.protoファイルで定義された各サービスに対して、Javaコード生成はJavaクラスを生成します。クラス名は、サービスの名の後にGrpcが付加されたものです。生成されたコードのパッケージは、.protoファイルでjava_packageオプションを使用して指定します。
たとえば、ServiceNameが以下を含む.protoファイルで定義されている場合
package grpcexample;
option java_package = "io.grpc.examples";
生成されるクラスはio.grpc.examples.ServiceNameGrpcになります。
java_packageが指定されていない場合、生成されたクラスは.protoファイルで指定されたpackageを使用します。protoパッケージは通常、リバースドメイン名で始まらないため、これは避けるべきです。
サービススタブ
生成されたJavaコードには、ServiceNameImplBaseのように、ImplBaseというサフィックスが付いた内部抽象クラスが含まれます。このクラスは、サービス定義の各メソッドに対して1つのJavaメソッドを定義します。このクラスを拡張し、これらのメソッドの機能を実装するのはサービスの実装者の責任です。オーバーライドされない場合、メソッドはメソッドが実装されていないというエラーをクライアントに返します。
ServiceNameImplBaseのスタブメソッドのシグネチャは、それが処理するRPCのタイプによって異なります。gRPCサービスメソッドには、単項、サーバストリーミング、クライアントストリーミング、双方向ストリーミングの4つのタイプがあります。
単項
単項RPCメソッドunaryExampleのサービススタブシグネチャ
public void unaryExample(
RequestType request,
StreamObserver<ResponseType> responseObserver)
サーバストリーミング
サーバストリーミングRPCメソッドserverStreamingExampleのサービススタブシグネチャ
public void serverStreamingExample(
RequestType request,
StreamObserver<ResponseType> responseObserver)
単項RPCとサーバストリーミングRPCのシグネチャが同じであることに注意してください。クライアントから単一のRequestTypeが受信され、サービス実装はresponseObserver.onNext(ResponseType response)を呼び出すことで応答を送信します。
クライアントストリーミング
クライアントストリーミングRPCメソッドclientStreamingExampleのサービススタブシグネチャ
public StreamObserver<RequestType> clientStreamingExample(
StreamObserver<ResponseType> responseObserver)
双方向ストリーミング
双方向ストリーミングRPCメソッドbidirectionalStreamingExampleのサービススタブシグネチャ
public StreamObserver<RequestType> bidirectionalStreamingExample(
StreamObserver<ResponseType> responseObserver)
クライアントストリーミングと双方向ストリーミングRPCのシグネチャは同じです。クライアントは複数のメッセージをサービスに送信できるため、サービス実装はStreamObserver<RequestType>インスタンスを返す責任があります。このStreamObserverは、クライアントから追加のメッセージが受信されるたびに呼び出されます。
クライアントスタブ
生成されたクラスには、gRPCクライアントがサービスで定義されたメソッドを呼び出すために使用するスタブも含まれています。各スタブは、生成されたコードのユーザーによって提供されるChannelをラップします。スタブは、このチャネルを使用してRPCをサービスに送信します。
gRPC Javaは、非同期、ブロッキング、フューチャーの3種類のスタブのコードを生成します。各タイプのスタブには、生成されたコードにServiceNameStub、ServiceNameBlockingStub、およびServiceNameFutureStubのような対応するクラスがあります。
非同期スタブ
非同期スタブを介して行われたRPCは、StreamObserver上のコールバックを介して完全に動作します。
非同期スタブには、サービス定義の各メソッドに対して1つのJavaメソッドが含まれています。
新しい非同期スタブは、ServiceNameGrpc.newStub(Channel channel)静的メソッドを介してインスタンス化されます。
単項
単項RPCメソッドunaryExampleの非同期スタブシグネチャ
public void unaryExample(
RequestType request,
StreamObserver<ResponseType> responseObserver)
サーバストリーミング
サーバストリーミングRPCメソッドserverStreamingExampleの非同期スタブシグネチャ
public void serverStreamingExample(
RequestType request,
StreamObserver<ResponseType> responseObserver)
クライアントストリーミング
クライアントストリーミングRPCメソッドclientStreamingExampleの非同期スタブシグネチャ
public StreamObserver<RequestType> clientStreamingExample(
StreamObserver<ResponseType> responseObserver)
双方向ストリーミング
双方向ストリーミングRPCメソッドbidirectionalStreamingExampleの非同期スタブシグネチャ
public StreamObserver<RequestType> bidirectionalStreamingExample(
StreamObserver<ResponseType> responseObserver)
ブロッキングスタブ
ブロッキングスタブを介して行われたRPCは、名前が示すように、サービスからの応答が利用可能になるまでブロックします。
ブロッキングスタブには、サービス定義の各単項メソッドとサーバストリーミングメソッドに対して1つのJavaメソッドが含まれています。ブロッキングスタブは、クライアントストリーミングRPCまたは双方向ストリーミングRPCをサポートしていません。
新しいブロッキングスタブは、ServiceNameGrpc.newBlockingStub(Channel channel)静的メソッドを介してインスタンス化されます。
単項
単項RPCメソッドunaryExampleのブロッキングスタブシグネチャ
public ResponseType unaryExample(RequestType request)
サーバストリーミング
サーバストリーミングRPCメソッドserverStreamingExampleのブロッキングスタブシグネチャ
public Iterator<ResponseType> serverStreamingExample(RequestType request)
フューチャースタブ
フューチャースタブを介して行われたRPCは、非同期スタブの戻り値をGrpcFuture<ResponseType>でラップします。これは、com.google.common.util.concurrent.ListenableFutureインターフェースを実装します。
フューチャースタブには、サービス定義の各単項メソッドに対して1つのJavaメソッドが含まれています。フューチャースタブは、ストリーミングコールをサポートしていません。
新しいフューチャースタブは、ServiceNameGrpc.newFutureStub(Channel channel)静的メソッドを介してインスタンス化されます。
単項
単項RPCメソッドunaryExampleのフューチャースタブシグネチャ
public ListenableFuture<ResponseType> unaryExample(RequestType request)
コード生成
通常、ビルドシステムはgRPC生成コードの作成を処理します。
protobufベースのコード生成の場合、適切なプラグインとともに.protoファイルをsrc/main/protoおよびsrc/test/protoディレクトリに配置できます。
gRPCおよびProtocol Buffersコードを生成するための典型的なprotobuf-maven-plugin構成は次のようになります
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>1.4.1.Final</version>
</extension>
</extensions>
<plugins>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.5.0</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:3.3.0:exe:${os.detected.classifier}</protocArtifact>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:1.4.0:exe:${os.detected.classifier}</pluginArtifact>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
EclipseおよびNetBeansユーザーは、os-maven-pluginのIDEドキュメントも参照する必要があります。
典型的なprotobuf-gradle-plugin構成は次のようになります
apply plugin: 'java'
apply plugin: 'com.google.protobuf'
buildscript {
repositories {
mavenCentral()
}
dependencies {
// ASSUMES GRADLE 2.12 OR HIGHER. Use plugin version 0.7.5 with earlier
// gradle versions
classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.0'
}
}
protobuf {
protoc {
artifact = "com.google.protobuf:protoc:3.2.0"
}
plugins {
grpc {
artifact = 'io.grpc:protoc-gen-grpc-java:1.4.0'
}
}
generateProtoTasks {
all()*.plugins {
grpc {}
}
}
}
Bazel開発者は、通常、次のようにjava_grpc_libraryルールを使用できます。
load("@grpc_java//:java_grpc_library.bzl", "java_grpc_library")
proto_library(
name = "helloworld_proto",
srcs = ["src/main/proto/helloworld.proto"],
)
java_proto_library(
name = "helloworld_java_proto",
deps = [":helloworld_proto"],
)
java_grpc_library(
name = "helloworld_java_grpc",
srcs = [":helloworld_proto"],
deps = [":helloworld_java_proto"],
)
Android開発者は、リファレンスについてはクライアントコードの生成を参照してください。
gRPC Java用のprotobufプラグインを直接呼び出す場合は、コマンドライン構文は次のようになります
$ protoc --plugin=protoc-gen-grpc-java \
--grpc-java_out="$OUTPUT_FILE" --proto_path="$DIR_OF_PROTO_FILE" "$PROTO_FILE"