or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/maven-io-grpc--grpc-protobuf

gRPC integration for Protocol Buffers with utilities for serialization, marshalling, and metadata handling

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/io.grpc/grpc-protobuf@1.73.x

To install, run

npx @tessl/cli install tessl/maven-io-grpc--grpc-protobuf@1.73.0

gRPC Protobuf

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.

Package Information

Package Name: io.grpc:grpc-protobuf
Package Type: Maven
Language: Java

Installation: Add to your Maven dependencies:

<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-protobuf</artifactId>
  <version>1.73.0</version>
</dependency>

Or for Gradle:

implementation 'io.grpc:grpc-protobuf:1.73.0'

Core Imports

import io.grpc.protobuf.ProtoUtils;
import io.grpc.protobuf.StatusProto;
import io.grpc.protobuf.ProtoServiceDescriptorSupplier;
import io.grpc.protobuf.ProtoMethodDescriptorSupplier;
import io.grpc.protobuf.ProtoFileDescriptorSupplier;
import io.grpc.MethodDescriptor.Marshaller;
import io.grpc.Metadata;
import com.google.protobuf.ExtensionRegistry;
import com.google.protobuf.Message;
import com.google.errorprone.annotations.CheckReturnValue;

Basic Usage

import io.grpc.protobuf.ProtoUtils;
import com.google.protobuf.Message;
import io.grpc.MethodDescriptor;

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

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

// Set extension registry globally (if needed)
ExtensionRegistry registry = ExtensionRegistry.newInstance();
// register your extensions...
ProtoUtils.setExtensionRegistry(registry);

Capabilities

Protobuf Message Marshalling

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

public static <T extends Message> Marshaller<T> marshaller(final T defaultInstance);
public static <T extends Message> Marshaller<T> marshallerWithRecursionLimit(T defaultInstance, int recursionLimit);

Extension Registry Management

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

public static void setExtensionRegistry(ExtensionRegistry registry);

Metadata Integration

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

public static <T extends Message> Metadata.Key<T> keyForProto(T instance);
public static <T extends Message> Metadata.BinaryMarshaller<T> metadataMarshaller(T instance);

Status Proto Conversion (Experimental)

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

public static StatusRuntimeException toStatusRuntimeException(com.google.rpc.Status statusProto);
public static StatusRuntimeException toStatusRuntimeException(com.google.rpc.Status statusProto, Metadata metadata);
public static StatusException toStatusException(com.google.rpc.Status statusProto);
public static StatusException toStatusException(com.google.rpc.Status statusProto, Metadata metadata);
public static StatusException toStatusException(com.google.rpc.Status statusProto, Metadata metadata, Throwable cause);
public static com.google.rpc.Status fromThrowable(Throwable t); // @Nullable return
public static com.google.rpc.Status fromStatusAndTrailers(Status status, @Nullable Metadata trailers);

Descriptor Supplier Interfaces

Interfaces for providing access to protobuf descriptors in generated code.

public interface ProtoFileDescriptorSupplier {
    FileDescriptor getFileDescriptor();
}

public interface ProtoServiceDescriptorSupplier extends ProtoFileDescriptorSupplier {
    ServiceDescriptor getServiceDescriptor();
}

public interface ProtoMethodDescriptorSupplier extends ProtoServiceDescriptorSupplier {
    @CheckReturnValue
    MethodDescriptor getMethodDescriptor();
}

Usage Examples

Creating Method Descriptors with Protobuf Marshallers

import io.grpc.MethodDescriptor;
import io.grpc.protobuf.ProtoUtils;

// Assuming you have MyRequest and MyResponse protobuf message types
private static final MethodDescriptor<MyRequest, MyResponse> METHOD_DESCRIPTOR =
    MethodDescriptor.<MyRequest, MyResponse>newBuilder()
        .setType(MethodDescriptor.MethodType.UNARY)
        .setFullMethodName("MyService/MyMethod")
        .setRequestMarshaller(ProtoUtils.marshaller(MyRequest.getDefaultInstance()))
        .setResponseMarshaller(ProtoUtils.marshaller(MyResponse.getDefaultInstance()))
        .build();

Working with Metadata and Protobuf Messages

import io.grpc.Metadata;
import io.grpc.protobuf.ProtoUtils;

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

// Create metadata and add protobuf message
Metadata metadata = new Metadata();
MyProtoMessage message = MyProtoMessage.newBuilder()
    .setField("value")
    .build();
metadata.put(key, message);

Status Proto Error Handling

import io.grpc.protobuf.StatusProto;
import com.google.rpc.Status;
import io.grpc.StatusRuntimeException;

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

StatusRuntimeException exception = StatusProto.toStatusRuntimeException(statusProto);

// Extract status proto from exception
com.google.rpc.Status extractedStatus = StatusProto.fromThrowable(exception);

Using with Extension Registry

import com.google.protobuf.ExtensionRegistry;
import io.grpc.protobuf.ProtoUtils;

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

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

Types

Core Types

// From io.grpc
class Metadata {
    static class Key<T> {
        String originalName();
    }
    static interface BinaryMarshaller<T> {}
}

// From io.grpc (different from com.google.protobuf.Descriptors.MethodDescriptor)
interface MethodDescriptor {
    interface Marshaller<T> {
        InputStream stream(T value);
        T parse(InputStream stream);
    }
}

class Status {
    Code getCode();
    String getDescription();
    Status withDescription(String description);
    Status withCause(Throwable cause);
    StatusException asException(Metadata trailers);
    StatusRuntimeException asRuntimeException(Metadata trailers);
}

class StatusException extends Exception {
    Status getStatus();
    Metadata getTrailers();
}

class StatusRuntimeException extends RuntimeException {
    Status getStatus();
    Metadata getTrailers();
}

// From com.google.protobuf
interface Message {
    Descriptors.Descriptor getDescriptorForType();
}

class ExtensionRegistry {
    static ExtensionRegistry newInstance();
    void add(GeneratedMessage.GeneratedExtension<?, ?> extension);
}

class Descriptors {
    static class FileDescriptor {
        String getFullName();
    }
    static class ServiceDescriptor {
        String getFullName();
    }
    static class MethodDescriptor {
        String getFullName();
    }
}

Error Handling

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

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

When using extension registries:

Do not modify the ExtensionRegistry after setting it via setExtensionRegistry()
The registry is shared globally across all servers and clients

Version Information

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