生成コードリファレンス
生成コードリファレンス
パッケージ
`.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 コードには、`ImplBase` で終わる内部抽象クラス（例：`ServiceNameImplBase`）が含まれています。このクラスは、サービス定義の各メソッドに対して 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 のシグネチャは同じであることに注意してください。クライアントから 1 つの `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` は、クライアントから追加のメッセージが受信されるたびに呼び出されます。
クライアント スタブ
生成されたクラスには、サービスによって定義されたメソッドを呼び出すためのクライアント用のスタブも含まれています。各スタブは、生成されたコードのユーザーによって提供される `Channel` をラップします。スタブはこのチャネルを使用して、RPC をサービスに送信します。
gRPC Java は、3 種類のスタブのコードを生成します。非同期、ブロッキング、Future です。各スタブタイプには、生成されたコードに対応するクラスがあります（例：`ServiceNameStub`、`ServiceNameBlockingStub`、`ServiceNameFutureStub`）。
非同期スタブ
非同期スタブを介した RPC は、`StreamObserver` のコールバックを通じて完全に実行されます。
非同期スタブには、サービス定義の各メソッドに対する Java メソッドが 1 つ含まれています。
新しい非同期スタブは、`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 は、その名前が示すとおり、サービスからの応答が利用可能になるまでブロックします。
ブロッキング スタブには、サービス定義の各単項およびサーバー ストリーミング メソッドに対する Java メソッドが 1 つ含まれています。ブロッキング スタブは、クライアント ストリーミングまたは双方向ストリーミング RPC をサポートしません。
新しいブロッキング スタブは、`ServiceNameGrpc.newBlockingStub(Channel channel)` 静的メソッドを介してインスタンス化されます。
単項
単項 RPC メソッド `unaryExample` のブロッキング スタブ シグネチャ
public ResponseType unaryExample(RequestType request)
サーバー ストリーミング
サーバー ストリーミング RPC メソッド `serverStreamingExample` のブロッキング スタブ シグネチャ
public Iterator<ResponseType> serverStreamingExample(RequestType request)
Future スタブ
Future スタブを介した RPC は、非同期スタブの戻り値を `GrpcFuture<ResponseType>` にラップします。これは `com.google.common.util.concurrent.ListenableFuture` インターフェースを実装します。
Future スタブには、サービス定義の各単項メソッドに対する Java メソッドが 1 つ含まれています。Future スタブはストリーミング呼び出しをサポートしません。
新しい Future スタブは、`ServiceNameGrpc.newFutureStub(Channel channel)` 静的メソッドを介してインスタンス化されます。
単項
単項 RPC メソッド `unaryExample` の Future スタブ シグネチャ
public ListenableFuture<ResponseType> unaryExample(RequestType request)
Codegen
通常、ビルドシステムが 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"