0
# protoc-gen-grpc-java
1

2
protoc-gen-grpc-java is a Protocol Buffer compiler plugin that generates Java language bindings for gRPC services defined in .proto files. It integrates with the Protocol Buffer compiler (protoc) to automatically generate Java client stubs, server implementations, and service interfaces from protobuf service definitions.
3

4
## Package Information
5

6
- **Package Name**: protoc-gen-grpc-java
7
- **Package Type**: Maven Artifact (Native Executable)
8
- **Language**: C++ (generates Java code)
9
- **Installation**: `mvn dependency:get -Dartifact=io.grpc:protoc-gen-grpc-java:1.73.0:exe:${os.detected.classifier}`
10
- **Build Requirements**: C++ compiler, Protocol Buffers (libprotobuf, libprotoc)
11

12
## Core Usage
13

14
The plugin is invoked through protoc and generates Java gRPC service stubs from .proto service definitions:
15

16
```bash
17
# Basic gRPC Java code generation
18
protoc --plugin=protoc-gen-grpc-java=/path/to/protoc-gen-grpc-java \
19
  --grpc-java_out="./generated" \
20
  --proto_path="./protos" \
21
  service.proto
22
```
23

24
With Maven (using protobuf-maven-plugin):
25

26
```xml
27
<plugin>
28
  <groupId>org.xolstice.maven.plugins</groupId>
29
  <artifactId>protobuf-maven-plugin</artifactId>
30
  <configuration>
31
    <protocArtifact>com.google.protobuf:protoc:3.24.0:exe:${os.detected.classifier}</protocArtifact>
32
    <pluginId>grpc-java</pluginId>
33
    <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.73.0:exe:${os.detected.classifier}</pluginArtifact>
34
  </configuration>
35
</plugin>
36
```
37

38
## Basic Usage
39

40
```bash
41
# Generate Java gRPC service stubs from a proto file
42
mkdir -p generated/java
43
protoc --plugin=protoc-gen-grpc-java=./protoc-gen-grpc-java \
44
  --grpc-java_out="./generated/java" \
45
  --proto_path="./protos" \
46
  user_service.proto
47

48
# Generate with lite protobuf runtime
49
protoc --plugin=protoc-gen-grpc-java=./protoc-gen-grpc-java \
50
  --grpc-java_out=lite:"./generated/java" \
51
  --proto_path="./protos" \
52
  user_service.proto
53

54
# Generate without version annotations
55
protoc --plugin=protoc-gen-grpc-java=./protoc-gen-grpc-java \
56
  --grpc-java_out=noversion:"./generated/java" \
57
  --proto_path="./protos" \
58
  user_service.proto
59
```
60

61
Given this proto file:
62

63
```protobuf
64
syntax = "proto3";
65
package com.example;
66
option java_package = "com.example.user";
67

68
service UserService {
69
  rpc GetUser(GetUserRequest) returns (UserResponse);
70
  rpc ListUsers(ListUsersRequest) returns (stream UserResponse);
71
}
72
```
73

74
The plugin generates: `com/example/user/UserServiceGrpc.java` with client stubs, server base class, and method descriptors.
75

76
## Capabilities
77

78
### Command Line Interface
79

80
The plugin implements the protoc plugin protocol and accepts configuration through protoc command-line options.
81

82
```bash { .api }
83
# Plugin invocation through protoc
84
protoc --plugin=protoc-gen-grpc-java=<path-to-executable> \
85
  --grpc-java_out=[OPTIONS:]<output-directory> \
86
  [--proto_path=<proto-directories>] \
87
  <proto-files>
88

89
# Supported options (comma-separated):
90
# lite                     - Generate lite protobuf bindings
91
# noversion               - Omit version information in generated code  
92
# @generated=omit         - Omit @Generated annotations
93
# @generated=javax        - Use javax.annotation.Generated (default)
94
```
95

96
### Service Code Generation
97

98
Generates complete Java gRPC service implementations including stubs, method descriptors, and server base classes.
99

100
```cpp { .api }
101
// Core code generation function
102
void GenerateService(
103
  const google::protobuf::ServiceDescriptor* service,
104
  google::protobuf::io::ZeroCopyOutputStream* output,
105
  ProtoFlavor flavor,
106
  bool disable_version,
107
  GeneratedAnnotation generated_annotation
108
);
109
```
110

111
**Parameters:**
112
- `service`: Protobuf service descriptor containing RPC method definitions
113
- `output`: Output stream for generated Java code
114
- `flavor`: Generation mode (NORMAL or LITE protobuf runtime)
115
- `disable_version`: Whether to omit version information in generated code
116
- `generated_annotation`: Annotation generation strategy (OMIT or JAVAX)
117

118
### Package and Class Naming
119

120
Determines Java package names and class names for generated service stubs.
121

122
```cpp { .api }
123
// Get Java package name for generated service classes
124
std::string ServiceJavaPackage(
125
  const google::protobuf::FileDescriptor* file
126
);
127

128
// Get outer class name for generated service code
129
std::string ServiceClassName(
130
  const google::protobuf::ServiceDescriptor* service
131
);
132
```
133

134
**ServiceJavaPackage** returns the Java package name based on:
135
1. `java_package` option in the .proto file, or
136
2. The proto package name converted to Java naming conventions
137

138
**ServiceClassName** returns the service name with "Grpc" suffix (e.g., "UserService" → "UserServiceGrpc").
139

140
### Protobuf Compiler Integration
141

142
Implements the protobuf compiler plugin interface for seamless integration with protoc.
143

144
```cpp { .api }
145
class JavaGrpcGenerator : public google::protobuf::compiler::CodeGenerator {
146
public:
147
  // Get supported protobuf features
148
  uint64_t GetSupportedFeatures() const override;
149
  
150
  // Get minimum supported protobuf edition  
151
  google::protobuf::Edition GetMinimumEdition() const override;
152
  
153
  // Get maximum supported protobuf edition
154
  google::protobuf::Edition GetMaximumEdition() const override;
155
  
156
  // Main code generation entry point
157
  bool Generate(
158
    const google::protobuf::FileDescriptor* file,
159
    const std::string& parameter, 
160
    google::protobuf::compiler::GeneratorContext* context,
161
    std::string* error
162
  ) const override;
163
};
164
```
165

166
**Supported Features:**
167
- `FEATURE_PROTO3_OPTIONAL`: Proto3 optional field support
168
- `FEATURE_SUPPORTS_EDITIONS`: Protobuf editions support
169

170
**Supported Editions:** EDITION_PROTO2 through EDITION_2023
171

172
## Generated Code Structure
173

174
The plugin generates Java classes following gRPC Java conventions:
175

176
### Service Stub Classes
177

178
For each protobuf service, generates a final class named `{ServiceName}Grpc`:
179

180
```java { .api }
181
// Generated service class structure
182
@javax.annotation.Generated(
183
    value = "by gRPC proto compiler (version 1.73.0)",
184
    comments = "Source: user_service.proto")
185
@io.grpc.stub.annotations.GrpcGenerated
186
public final class UserServiceGrpc {
187
  // Service name constant
188
  public static final String SERVICE_NAME = "com.example.UserService";
189
  
190
  // Method descriptor getters
191
  public static MethodDescriptor<GetUserRequest, UserResponse> getGetUserMethod();
192
  public static MethodDescriptor<ListUsersRequest, UserResponse> getListUsersMethod();
193
  
194
  // Factory methods for creating client stubs
195
  public static UserServiceStub newStub(Channel channel);
196
  public static UserServiceBlockingStub newBlockingStub(Channel channel);
197
  public static UserServiceFutureStub newFutureStub(Channel channel);
198
  
199
  // Service binding for server implementations
200
  public static ServerServiceDefinition bindService(UserServiceImplBase serviceImpl);
201
  
202
  // Client stub classes
203
  public static final class UserServiceStub 
204
    extends AbstractAsyncStub<UserServiceStub> {
205
    // Async streaming client methods
206
  }
207
  
208
  public static final class UserServiceBlockingV2Stub 
209
    extends AbstractBlockingStub<UserServiceBlockingV2Stub> {
210
    // Blocking stub with V2 interface
211
  }
212
  
213
  public static final class UserServiceBlockingStub 
214
    extends AbstractBlockingStub<UserServiceBlockingStub> {
215
    // Synchronous blocking client methods  
216
  }
217
  
218
  public static final class UserServiceFutureStub 
219
    extends AbstractFutureStub<UserServiceFutureStub> {
220
    // Asynchronous future-based client methods
221
  }
222
  
223
  // Server implementation base class
224
  public static abstract class UserServiceImplBase 
225
    implements BindableService, AsyncService {
226
    // Abstract methods for server implementation
227
    @Override public final ServerServiceDefinition bindService() {
228
      return UserServiceGrpc.bindService(this);
229
    }
230
  }
231
}
232
```
233

234
### Method Descriptor Generation
235

236
Each RPC method gets a corresponding method descriptor with proper marshalling:
237

238
```java { .api }
239
// Generated method descriptor pattern
240
private static volatile MethodDescriptor<RequestType, ResponseType> getMethodName;
241

242
@io.grpc.stub.annotations.RpcMethod(
243
  fullMethodName = SERVICE_NAME + "/MethodName",
244
  requestType = RequestType.class,
245
  responseType = ResponseType.class, 
246
  methodType = MethodDescriptor.MethodType.UNARY // or SERVER_STREAMING, etc.
247
)
248
public static MethodDescriptor<RequestType, ResponseType> getMethodName() {
249
  MethodDescriptor<RequestType, ResponseType> getMethodName;
250
  if ((getMethodName = ServiceGrpc.getMethodName) == null) {
251
    synchronized (ServiceGrpc.class) {
252
      if ((getMethodName = ServiceGrpc.getMethodName) == null) {
253
        ServiceGrpc.getMethodName = getMethodName =
254
            MethodDescriptor.<RequestType, ResponseType>newBuilder()
255
            .setType(MethodDescriptor.MethodType.UNARY)
256
            .setFullMethodName(generateFullMethodName(SERVICE_NAME, "MethodName"))
257
            .setSampledToLocalTracing(true)
258
            .setRequestMarshaller(ProtoUtils.marshaller(
259
                RequestType.getDefaultInstance()))
260
            .setResponseMarshaller(ProtoUtils.marshaller(
261
                ResponseType.getDefaultInstance()))
262
            .setSchemaDescriptor(new ServiceMethodDescriptorSupplier("MethodName"))
263
            .build();
264
      }
265
    }
266
  }
267
  return getMethodName;
268
}
269
```
270

271
## RPC Method Types
272

273
The plugin supports all gRPC method types:
274

275
### Unary RPCs
276
```protobuf
277
rpc GetUser(GetUserRequest) returns (UserResponse);
278
```
279
Generates: Synchronous request-response methods
280

281
### Server Streaming RPCs  
282
```protobuf
283
rpc ListUsers(ListUsersRequest) returns (stream UserResponse);
284
```
285
Generates: Methods returning `Iterator<UserResponse>` (blocking) or `StreamObserver<UserResponse>` (async)
286

287
### Client Streaming RPCs
288
```protobuf
289
rpc CreateUsers(stream CreateUserRequest) returns (CreateUsersResponse);
290
```
291
Generates: Methods accepting `StreamObserver<CreateUserRequest>` and returning response observer
292

293
### Bidirectional Streaming RPCs
294
```protobuf
295
rpc ChatUsers(stream ChatMessage) returns (stream ChatMessage);
296
```
297
Generates: Methods with bidirectional `StreamObserver<ChatMessage>`
298

299
## Build Integration
300

301
### Gradle Integration
302

303
```gradle { .api }
304
// build.gradle configuration
305
plugins {
306
  id 'java'
307
  id 'com.google.protobuf' version '0.9.4'
308
}
309

310
def grpcVersion = '1.73.0'
311
def protobufVersion = '3.24.0'
312

313
dependencies {
314
  implementation "io.grpc:grpc-stub:${grpcVersion}"
315
  implementation "io.grpc:grpc-protobuf:${grpcVersion}"
316
  implementation "com.google.protobuf:protobuf-java:${protobufVersion}"
317
  
318
  // Required for annotation processing
319
  compileOnly "javax.annotation:javax.annotation-api:1.3.2"
320
}
321

322
protobuf {
323
  protoc {
324
    artifact = "com.google.protobuf:protoc:${protobufVersion}"
325
  }
326
  plugins {
327
    grpc {
328
      artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}"
329
    }
330
  }
331
  generateProtoTasks {
332
    all()*.plugins {
333
      grpc {}
334
    }
335
  }
336
}
337

338
sourceSets {
339
  main {
340
    java {
341
      srcDirs 'build/generated/source/proto/main/grpc'
342
      srcDirs 'build/generated/source/proto/main/java'
343
    }
344
  }
345
}
346
```
347

348
### Maven Integration
349

350
```xml { .api }
351
<!-- pom.xml configuration -->
352
<properties>
353
  <grpc.version>1.73.0</grpc.version>
354
  <protobuf.version>3.24.0</protobuf.version>
355
</properties>
356

357
<dependencies>
358
  <dependency>
359
    <groupId>io.grpc</groupId>
360
    <artifactId>grpc-stub</artifactId>
361
    <version>${grpc.version}</version>
362
  </dependency>
363
  <dependency>
364
    <groupId>io.grpc</groupId>
365
    <artifactId>grpc-protobuf</artifactId>
366
    <version>${grpc.version}</version>
367
  </dependency>
368
  <dependency>
369
    <groupId>com.google.protobuf</groupId>
370
    <artifactId>protobuf-java</artifactId>
371
    <version>${protobuf.version}</version>
372
  </dependency>
373
</dependencies>
374

375
<build>
376
  <extensions>
377
    <extension>
378
      <groupId>kr.motd.maven</groupId>
379
      <artifactId>os-maven-plugin</artifactId>
380
      <version>1.7.1</version>
381
    </extension>
382
  </extensions>
383
  <plugins>
384
    <plugin>
385
      <groupId>org.xolstice.maven.plugins</groupId>
386
      <artifactId>protobuf-maven-plugin</artifactId>
387
      <version>0.6.1</version>
388
      <configuration>
389
        <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
390
        <pluginId>grpc-java</pluginId>
391
        <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
392
        <protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot>
393
      </configuration>
394
      <executions>
395
        <execution>
396
          <goals>
397
            <goal>compile</goal>
398
            <goal>compile-custom</goal>
399
          </goals>
400
        </execution>
401
      </executions>
402
    </plugin>
403
  </plugins>
404
</build>
405
```
406

407
## Types
408

409
```cpp { .api }
410
// Code generation configuration enums
411
enum ProtoFlavor {
412
  NORMAL,  // Standard protobuf runtime
413
  LITE     // Lite protobuf runtime (smaller footprint)
414
};
415

416
enum GeneratedAnnotation {
417
  OMIT,    // Omit @Generated annotations  
418
  JAVAX    // Use javax.annotation.Generated annotations
419
};
420
```
421

422
```java { .api }
423
// gRPC method types supported in generated code
424
enum MethodType {
425
  UNARY,              // Single request, single response
426
  CLIENT_STREAMING,   // Stream of requests, single response  
427
  SERVER_STREAMING,   // Single request, stream of responses
428
  BIDI_STREAMING      // Stream of requests, stream of responses
429
}
430

431
// Key interfaces used in generated code
432
interface BindableService {
433
  ServerServiceDefinition bindService();
434
}
435

436
interface AsyncService {
437
  // Marker interface for async service implementations
438
}
439

440
// Abstract stub base classes
441
abstract class AbstractAsyncStub<T extends AbstractAsyncStub<T>> {
442
  protected AbstractAsyncStub(Channel channel, CallOptions callOptions);
443
  protected abstract T build(Channel channel, CallOptions callOptions);
444
}
445

446
abstract class AbstractBlockingStub<T extends AbstractBlockingStub<T>> {
447
  protected AbstractBlockingStub(Channel channel, CallOptions callOptions);
448
  protected abstract T build(Channel channel, CallOptions callOptions);
449
}
450

451
abstract class AbstractFutureStub<T extends AbstractFutureStub<T>> {
452
  protected AbstractFutureStub(Channel channel, CallOptions callOptions);
453
  protected abstract T build(Channel channel, CallOptions callOptions);
454
}
455

456
// Server service definition for registration
457
class ServerServiceDefinition {
458
  // Service definition for gRPC server registration
459
}
460

461
// Utility classes used in generated code
462
class ClientCalls {
463
  public static <ReqT, RespT> void asyncUnaryCall(
464
      ClientCall<ReqT, RespT> call, ReqT request, 
465
      StreamObserver<RespT> responseObserver);
466
  public static <ReqT, RespT> RespT blockingUnaryCall(
467
      Channel channel, MethodDescriptor<ReqT, RespT> method, 
468
      CallOptions callOptions, ReqT request);
469
  public static <ReqT, RespT> ListenableFuture<RespT> futureUnaryCall(
470
      ClientCall<ReqT, RespT> call, ReqT request);
471
}
472

473
class ProtoUtils {
474
  public static <T extends Message> Marshaller<T> marshaller(T defaultInstance);
475
}
476
```
477

478
## Error Handling
479

480
The plugin reports errors through the protoc plugin interface:
481

482
- **Compilation errors**: Invalid proto syntax or unsupported features
483
- **Generation errors**: Issues during Java code generation
484
- **I/O errors**: Problems writing generated files
485

486
Errors are reported via protoc's standard error handling mechanism and will cause the compilation to fail with descriptive error messages.
487

488
## Platform Support
489

490
The plugin is distributed as platform-specific native executables:
491

492
- **Linux**: x86_64, aarch64, ppcle_64, s390_64, loongarch_64
493
- **macOS**: x86_64, aarch64  
494
- **Windows**: x86_64, x86_32
495

496
Each platform executable is available as a separate Maven classifier (e.g., `linux-x86_64`, `osx-x86_64`, `windows-x86_64`).