Package com.linecorp.armeria.client.grpc

Class GrpcClientOptions

java.lang.Object

com.linecorp.armeria.client.grpc.GrpcClientOptions

public final class GrpcClientOptions
extends Object

ClientOptions to control gRPC-specific behavior.

Field Summary

Fields

Modifier and Type	Field	Description
static final ClientOption<io.grpc.CallCredentials>	CALL_CREDENTIALS	Sets the CallCredentials that carries credential data that will be propagated to the server via request metadata.
static final ClientOption<io.grpc.Compressor>	COMPRESSOR	Sets the Compressor to use when compressing messages.
static final ClientOption<io.grpc.DecompressorRegistry>	DECOMPRESSOR_REGISTRY	Sets the DecompressorRegistry to use when decompressing messages.
static final ClientOption<GrpcExceptionHandlerFunction>	EXCEPTION_HANDLER	Sets the specified GrpcExceptionHandlerFunction that maps a Throwable to a gRPC Status.
static final ClientOption<GrpcClientStubFactory>	GRPC_CLIENT_STUB_FACTORY	Sets the GrpcClientStubFactory that creates a gRPC client stub.
static final ClientOption<Function<? super io.grpc.ServiceDescriptor,? extends GrpcJsonMarshaller>>	GRPC_JSON_MARSHALLER_FACTORY	Sets the factory that creates a GrpcJsonMarshaller that serializes and deserializes request or response messages to and from JSON depending on the SerializationFormat.
static final ClientOption<Iterable<? extends io.grpc.ClientInterceptor>>	INTERCEPTORS	Sets the ClientInterceptors to the gRPC client stub.
static final ClientOption<Integer>	MAX_INBOUND_MESSAGE_SIZE_BYTES	The maximum size, in bytes, of messages coming in a response.
static final ClientOption<Integer>	MAX_OUTBOUND_MESSAGE_SIZE_BYTES	The maximum size, in bytes, of messages sent in a request.
static final ClientOption<Boolean>	UNSAFE_WRAP_RESPONSE_BUFFERS	Enables unsafe retention of response buffers.
static final ClientOption<Boolean>	USE_METHOD_MARSHALLER	Sets whether to respect the marshaller specified in gRPC MethodDescriptor.

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_INBOUND_MESSAGE_SIZE_BYTES

public static final ClientOption<Integer> MAX_INBOUND_MESSAGE_SIZE_BYTES

The maximum size, in bytes, of messages coming in a response. The default value is -1, which means 'use ClientOptions.MAX_RESPONSE_LENGTH'.

MAX_OUTBOUND_MESSAGE_SIZE_BYTES

public static final ClientOption<Integer> MAX_OUTBOUND_MESSAGE_SIZE_BYTES

The maximum size, in bytes, of messages sent in a request. The default value is -1, which means unlimited.

UNSAFE_WRAP_RESPONSE_BUFFERS

public static final ClientOption<Boolean> UNSAFE_WRAP_RESPONSE_BUFFERS

Enables unsafe retention of response buffers. Can improve performance when working with very large (i.e., several megabytes) payloads.

DISCLAIMER: Do not use this if you don't know what you are doing. It is very easy to introduce memory leaks when using this method. You will probably spend much time debugging memory leaks during development if this is enabled. You will probably spend much time debugging memory leaks in production if this is enabled. You probably don't want to do this and should turn back now.

When enabled, the reference-counted buffer received from the server will be stored into RequestContext instead of being released. All ByteString in a protobuf message will reference sections of this buffer instead of having their own copies. When done with a response message, call GrpcUnsafeBufferUtil.releaseBuffer(Object, RequestContext) with the message and the request's context to release the buffer. The message must be the same reference as what was passed to the client stub - a message with the same contents will not work. If GrpcUnsafeBufferUtil.releaseBuffer(Object, RequestContext) is not called, the memory will be leaked.

Note that this has no effect if the payloads are compressed or the SerializationFormat is GrpcSerializationFormats.PROTO_WEB_TEXT.

GRPC_JSON_MARSHALLER_FACTORY

public static final ClientOption<Function<? super io.grpc.ServiceDescriptor,? extends GrpcJsonMarshaller>> GRPC_JSON_MARSHALLER_FACTORY

Sets the factory that creates a GrpcJsonMarshaller that serializes and deserializes request or response messages to and from JSON depending on the SerializationFormat. The returned GrpcJsonMarshaller from the factory replaces the built-in GrpcJsonMarshaller.

This is commonly used to:

• Switch from the default of using lowerCamelCase for field names to using the field name from the proto definition, by setting MessageMarshaller.Builder.preservingProtoFieldNames(boolean) via GrpcJsonMarshallerBuilder.jsonMarshallerCustomizer(Consumer).

  
         GrpcClients.builder(grpcServerUri)
                    .jsonMarshallerFactory(serviceDescriptor -> {
                        return GrpcJsonMarshaller.builder()
                                                 .jsonMarshallerCustomizer(builder -> {
                                                     builder.preservingProtoFieldNames(true);
                                                 })
                                                 .build(serviceDescriptor);
                    })
                    .build();
         

• Set a customer marshaller for non-Message types such as scalapb.GeneratedMessage for Scala and pbandk.Message for Kotlin.

GRPC_CLIENT_STUB_FACTORY

public static final ClientOption<GrpcClientStubFactory> GRPC_CLIENT_STUB_FACTORY

Sets the GrpcClientStubFactory that creates a gRPC client stub. If not specified, Armeria provides built-in factories for the following gRPC client stubs:

• gRPC-Java
• Reactive-gRPC
• gRPC-Kotlin
• ScalaPB

INTERCEPTORS

public static final ClientOption<Iterable<? extends io.grpc.ClientInterceptor>> INTERCEPTORS

Sets the ClientInterceptors to the gRPC client stub. The specified interceptor(s) is/are executed in reverse order.

COMPRESSOR

public static final ClientOption<io.grpc.Compressor> COMPRESSOR

Sets the Compressor to use when compressing messages. If not set, Codec.Identity.NONE will be used by default.

DECOMPRESSOR_REGISTRY

public static final ClientOption<io.grpc.DecompressorRegistry> DECOMPRESSOR_REGISTRY

Sets the DecompressorRegistry to use when decompressing messages. If not set, will use the default, which supports gzip only.

CALL_CREDENTIALS

public static final ClientOption<io.grpc.CallCredentials> CALL_CREDENTIALS

Sets the CallCredentials that carries credential data that will be propagated to the server via request metadata.

EXCEPTION_HANDLER

public static final ClientOption<GrpcExceptionHandlerFunction> EXCEPTION_HANDLER

Sets the specified GrpcExceptionHandlerFunction that maps a Throwable to a gRPC Status.

USE_METHOD_MARSHALLER

public static final ClientOption<Boolean> USE_METHOD_MARSHALLER

Sets whether to respect the marshaller specified in gRPC MethodDescriptor. If disabled, the default marshaller will be used, which is more efficient. This option is disabled by default.