0
# gRPC Protobuf
1

2
gRPC Protobuf provides seamless integration between gRPC and Protocol Buffers, enabling automatic serialization and deserialization of protobuf messages in gRPC applications. It offers utilities for creating marshallers, handling extension registries, converting between protobuf messages and gRPC metadata, and working with status protos.
3

4
## Package Information
5

6
- **Package Name**: io.grpc:grpc-protobuf
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven dependencies:
10
  ```xml
11
  <dependency>
12
    <groupId>io.grpc</groupId>
13
    <artifactId>grpc-protobuf</artifactId>
14
    <version>1.73.0</version>
15
  </dependency>
16
  ```
17
  Or for Gradle:
18
  ```groovy
19
  implementation 'io.grpc:grpc-protobuf:1.73.0'
20
  ```
21

22
## Core Imports
23

24
```java
25
import io.grpc.protobuf.ProtoUtils;
26
import io.grpc.protobuf.StatusProto;
27
import io.grpc.protobuf.ProtoServiceDescriptorSupplier;
28
import io.grpc.protobuf.ProtoMethodDescriptorSupplier;
29
import io.grpc.protobuf.ProtoFileDescriptorSupplier;
30
import io.grpc.MethodDescriptor.Marshaller;
31
import io.grpc.Metadata;
32
import com.google.protobuf.ExtensionRegistry;
33
import com.google.protobuf.Message;
34
import com.google.errorprone.annotations.CheckReturnValue;
35
```
36

37
## Basic Usage
38

39
```java
40
import io.grpc.protobuf.ProtoUtils;
41
import com.google.protobuf.Message;
42
import io.grpc.MethodDescriptor;
43

44
// Create a marshaller for a protobuf message type
45
MyProtoMessage defaultInstance = MyProtoMessage.getDefaultInstance();
46
MethodDescriptor.Marshaller<MyProtoMessage> marshaller = ProtoUtils.marshaller(defaultInstance);
47

48
// Create metadata key for protobuf messages
49
Metadata.Key<MyProtoMessage> metadataKey = ProtoUtils.keyForProto(defaultInstance);
50

51
// Set extension registry globally (if needed)
52
ExtensionRegistry registry = ExtensionRegistry.newInstance();
53
// register your extensions...
54
ProtoUtils.setExtensionRegistry(registry);
55
```
56

57
## Capabilities
58

59
### Protobuf Message Marshalling
60

61
Create marshallers for protobuf messages to enable automatic serialization/deserialization in gRPC method descriptors.
62

63
```java { .api }
64
public static <T extends Message> Marshaller<T> marshaller(final T defaultInstance);
65
public static <T extends Message> Marshaller<T> marshallerWithRecursionLimit(T defaultInstance, int recursionLimit);
66
```
67

68
### Extension Registry Management
69

70
Configure global extension registry for protobuf marshalling across all gRPC servers and clients.
71

72
```java { .api }
73
public static void setExtensionRegistry(ExtensionRegistry registry);
74
```
75

76
### Metadata Integration
77

78
Convert protobuf messages to gRPC metadata keys and marshallers for header transmission.
79

80
```java { .api }
81
public static <T extends Message> Metadata.Key<T> keyForProto(T instance);
82
public static <T extends Message> Metadata.BinaryMarshaller<T> metadataMarshaller(T instance);
83
```
84

85
### Status Proto Conversion (Experimental)
86

87
Convert between com.google.rpc.Status protos and gRPC Status/Exception types for rich error handling.
88

89
```java { .api }
90
public static StatusRuntimeException toStatusRuntimeException(com.google.rpc.Status statusProto);
91
public static StatusRuntimeException toStatusRuntimeException(com.google.rpc.Status statusProto, Metadata metadata);
92
public static StatusException toStatusException(com.google.rpc.Status statusProto);
93
public static StatusException toStatusException(com.google.rpc.Status statusProto, Metadata metadata);
94
public static StatusException toStatusException(com.google.rpc.Status statusProto, Metadata metadata, Throwable cause);
95
public static com.google.rpc.Status fromThrowable(Throwable t); // @Nullable return
96
public static com.google.rpc.Status fromStatusAndTrailers(Status status, @Nullable Metadata trailers);
97
```
98

99
### Descriptor Supplier Interfaces
100

101
Interfaces for providing access to protobuf descriptors in generated code.
102

103
```java { .api }
104
public interface ProtoFileDescriptorSupplier {
105
    FileDescriptor getFileDescriptor();
106
}
107

108
public interface ProtoServiceDescriptorSupplier extends ProtoFileDescriptorSupplier {
109
    ServiceDescriptor getServiceDescriptor();
110
}
111

112
public interface ProtoMethodDescriptorSupplier extends ProtoServiceDescriptorSupplier {
113
    @CheckReturnValue
114
    MethodDescriptor getMethodDescriptor();
115
}
116
```
117

118
## Usage Examples
119

120
### Creating Method Descriptors with Protobuf Marshallers
121

122
```java
123
import io.grpc.MethodDescriptor;
124
import io.grpc.protobuf.ProtoUtils;
125

126
// Assuming you have MyRequest and MyResponse protobuf message types
127
private static final MethodDescriptor<MyRequest, MyResponse> METHOD_DESCRIPTOR =
128
    MethodDescriptor.<MyRequest, MyResponse>newBuilder()
129
        .setType(MethodDescriptor.MethodType.UNARY)
130
        .setFullMethodName("MyService/MyMethod")
131
        .setRequestMarshaller(ProtoUtils.marshaller(MyRequest.getDefaultInstance()))
132
        .setResponseMarshaller(ProtoUtils.marshaller(MyResponse.getDefaultInstance()))
133
        .build();
134
```
135

136
### Working with Metadata and Protobuf Messages
137

138
```java
139
import io.grpc.Metadata;
140
import io.grpc.protobuf.ProtoUtils;
141

142
// Create metadata key for a protobuf message
143
Metadata.Key<MyProtoMessage> key = ProtoUtils.keyForProto(MyProtoMessage.getDefaultInstance());
144

145
// Create metadata and add protobuf message
146
Metadata metadata = new Metadata();
147
MyProtoMessage message = MyProtoMessage.newBuilder()
148
    .setField("value")
149
    .build();
150
metadata.put(key, message);
151
```
152

153
### Status Proto Error Handling
154

155
```java
156
import io.grpc.protobuf.StatusProto;
157
import com.google.rpc.Status;
158
import io.grpc.StatusRuntimeException;
159

160
// Convert RPC status proto to gRPC exception
161
Status statusProto = Status.newBuilder()
162
    .setCode(5) // NOT_FOUND
163
    .setMessage("Resource not found")
164
    .build();
165

166
StatusRuntimeException exception = StatusProto.toStatusRuntimeException(statusProto);
167

168
// Extract status proto from exception
169
com.google.rpc.Status extractedStatus = StatusProto.fromThrowable(exception);
170
```
171

172
### Using with Extension Registry
173

174
```java
175
import com.google.protobuf.ExtensionRegistry;
176
import io.grpc.protobuf.ProtoUtils;
177

178
// Set up extension registry for custom protobuf extensions
179
ExtensionRegistry registry = ExtensionRegistry.newInstance();
180
registry.add(MyExtensions.myCustomExtension);
181
ProtoUtils.setExtensionRegistry(registry);
182

183
// Now all marshallers will use this registry for parsing extensions
184
MethodDescriptor.Marshaller<MyMessage> marshaller = 
185
    ProtoUtils.marshaller(MyMessage.getDefaultInstance());
186
```
187

188
## Types
189

190
### Core Types
191

192
```java { .api }
193
// From io.grpc
194
class Metadata {
195
    static class Key<T> {
196
        String originalName();
197
    }
198
    static interface BinaryMarshaller<T> {}
199
}
200

201
// From io.grpc (different from com.google.protobuf.Descriptors.MethodDescriptor)
202
interface MethodDescriptor {
203
    interface Marshaller<T> {
204
        InputStream stream(T value);
205
        T parse(InputStream stream);
206
    }
207
}
208

209
class Status {
210
    Code getCode();
211
    String getDescription();
212
    Status withDescription(String description);
213
    Status withCause(Throwable cause);
214
    StatusException asException(Metadata trailers);
215
    StatusRuntimeException asRuntimeException(Metadata trailers);
216
}
217

218
class StatusException extends Exception {
219
    Status getStatus();
220
    Metadata getTrailers();
221
}
222

223
class StatusRuntimeException extends RuntimeException {
224
    Status getStatus();
225
    Metadata getTrailers();
226
}
227
```
228

229
```java { .api }
230
// From com.google.protobuf
231
interface Message {
232
    Descriptors.Descriptor getDescriptorForType();
233
}
234

235
class ExtensionRegistry {
236
    static ExtensionRegistry newInstance();
237
    void add(GeneratedMessage.GeneratedExtension<?, ?> extension);
238
}
239

240
class Descriptors {
241
    static class FileDescriptor {
242
        String getFullName();
243
    }
244
    static class ServiceDescriptor {
245
        String getFullName();
246
    }
247
    static class MethodDescriptor {
248
        String getFullName();
249
    }
250
}
251
```
252

253
## Error Handling
254

255
The StatusProto class provides experimental APIs for working with rich error information using com.google.rpc.Status protos. Common exceptions:
256

257
- **IllegalArgumentException**: Thrown when status codes don't match between com.google.rpc.Status and gRPC Status
258
- **NullPointerException**: Thrown when required parameters are null
259

260
When using extension registries:
261
- Do not modify the ExtensionRegistry after setting it via setExtensionRegistry()
262
- The registry is shared globally across all servers and clients
263

264
## Version Information
265

266
- Package version: 1.73.0
267
- Supports gRPC method descriptor marshalling since 1.0.0
268
- Extension registry support since 1.16.0  
269
- Recursion limit marshaller since 1.56.0
270
- StatusProto APIs are experimental and may change