Package com.linecorp.armeria.client.grpc

Class GrpcClientBuilder

java.lang.Object

com.linecorp.armeria.client.AbstractClientOptionsBuilder

com.linecorp.armeria.client.grpc.GrpcClientBuilder

@UnstableApi
public final class GrpcClientBuilder
extends AbstractClientOptionsBuilder

Creates a new gRPC client that connects to the specified URI using the builder pattern. Use the factory methods in GrpcClients if you do not have many options to override.

Method Summary

Modifier and Type	Method	Description
GrpcClientBuilder	addHeader(CharSequence name, Object value)	Adds the specified HTTP header.
GrpcClientBuilder	addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Adds the specified HTTP headers.
GrpcClientBuilder	auth(AuthToken token)	Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.
GrpcClientBuilder	auth(BasicToken token)	Sets the HTTP basic access authentication header using HttpHeaderNames.AUTHORIZATION.
GrpcClientBuilder	auth(OAuth1aToken token)	Sets the OAuth Core 1.0 Revision A header using HttpHeaderNames.AUTHORIZATION.
GrpcClientBuilder	auth(OAuth2Token token)	Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.
<T> T	build(Class<T> clientType)	Returns a newly-created gRPC client which implements the specified clientType, based on the properties of this builder.
GrpcClientBuilder	callCredentials(CallCredentials callCredentials)	Sets the CallCredentials that carries credential data that will be propagated to the server via request metadata.
GrpcClientBuilder	clearDecorators()	Clears all HTTP-level and RPC-level decorators set so far.
GrpcClientBuilder	clientStubFactory(GrpcClientStubFactory clientStubFactory)	Sets the GrpcClientStubFactory that creates a gRPC client stub.
GrpcClientBuilder	compressor(Compressor compressor)	Sets the Compressor to use when compressing messages.
GrpcClientBuilder	contextCustomizer(Consumer<? super ClientRequestContext> contextCustomizer)	Adds the specified ClientRequestContext customizer function so that it customizes the context in the thread that initiated the client call.
GrpcClientBuilder	decompressorRegistry(DecompressorRegistry registry)	Sets the DecompressorRegistry to use when decompressing messages.
GrpcClientBuilder	decorator(DecoratingHttpClientFunction decorator)	Adds the specified HTTP-level decorator.
GrpcClientBuilder	decorator(Function<? super HttpClient,? extends HttpClient> decorator)	Adds the specified HTTP-level decorator.
GrpcClientBuilder	enableUnsafeWrapResponseBuffers(boolean enableUnsafeWrapResponseBuffers)	(Advanced users only) Enables unsafe retention of response buffers.
GrpcClientBuilder	endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)	Sets a Function that remaps an Endpoint into an EndpointGroup.
GrpcClientBuilder	factory(ClientFactory factory)	Sets the ClientFactory used for creating a client.
GrpcClientBuilder	followRedirects()	Enables automatic redirection.
GrpcClientBuilder	followRedirects(RedirectConfig redirectConfig)	Sets the RedirectConfig to enable automatic redirection.
GrpcClientBuilder	intercept(ClientInterceptor... interceptors)	Adds the ClientInterceptors to the gRPC client stub.
GrpcClientBuilder	intercept(Iterable<? extends ClientInterceptor> interceptors)	Adds the ClientInterceptors to the gRPC client stub.
GrpcClientBuilder	jsonMarshallerFactory(Function<? super ServiceDescriptor,? extends GrpcJsonMarshaller> jsonMarshallerFactory)	Sets the factory that creates a GrpcJsonMarshaller that serializes and deserializes request or response messages to and from JSON depending on the SerializationFormat.
GrpcClientBuilder	maxRequestMessageLength(int maxRequestMessageLength)	Sets the maximum size, in bytes, of messages sent in a request.
GrpcClientBuilder	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
GrpcClientBuilder	maxResponseMessageLength(int maxResponseMessageLength)	Sets the maximum size, in bytes, of messages coming in a response.
<T> GrpcClientBuilder	option(ClientOption<T> option, T value)	Adds the specified ClientOption and its value.
<T> GrpcClientBuilder	option(ClientOptionValue<T> optionValue)	Adds the specified ClientOptionValue.
GrpcClientBuilder	options(ClientOptions options)	Adds the specified ClientOptions.
GrpcClientBuilder	options(ClientOptionValue<?>... options)	Adds the specified ClientOptionValues.
GrpcClientBuilder	options(Iterable<ClientOptionValue<?>> options)	Adds the specified ClientOptionValues.
GrpcClientBuilder	path(String prefix)	Deprecated. Use pathPrefix(String) instead.
GrpcClientBuilder	pathPrefix(String prefix)	Sets the context path for the gRPC endpoint.
GrpcClientBuilder	requestIdGenerator(Supplier<RequestId> requestIdGenerator)	Sets the Supplier that generates a RequestId.
GrpcClientBuilder	responseTimeout(Duration responseTimeout)	Sets the timeout of a response.
GrpcClientBuilder	responseTimeoutMillis(long responseTimeoutMillis)	Sets the timeout of a response in milliseconds.
GrpcClientBuilder	rpcDecorator(DecoratingRpcClientFunction decorator)	Deprecated. Use either decorator(DecoratingHttpClientFunction) or intercept(ClientInterceptor...) instead.
GrpcClientBuilder	rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)	Deprecated. Use either decorator(DecoratingHttpClientFunction) or intercept(ClientInterceptor...) instead.
GrpcClientBuilder	serializationFormat(SerializationFormat serializationFormat)	Sets the gRPC SerializationFormat.
GrpcClientBuilder	setHeader(CharSequence name, Object value)	Sets the specified HTTP header.
GrpcClientBuilder	setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Sets the specified HTTP headers.
GrpcClientBuilder	successFunction(SuccessFunction successFunction)	Sets a SuccessFunction that determines whether a request was handled successfully or not.
GrpcClientBuilder	writeTimeout(Duration writeTimeout)	Sets the timeout of a socket write attempt.
GrpcClientBuilder	writeTimeoutMillis(long writeTimeoutMillis)	Sets the timeout of a socket write attempt in milliseconds.

Methods inherited from class com.linecorp.armeria.client.AbstractClientOptionsBuilder

buildOptions, buildOptions

Methods inherited from class java.lang.Object

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

Method Details

serializationFormat

public GrpcClientBuilder serializationFormat(SerializationFormat serializationFormat)

Sets the gRPC SerializationFormat. If not set, the Scheme.serializationFormat() specified when creating this builder will be used by default.

See Also:

• GrpcSerializationFormats

path

@Deprecated
public GrpcClientBuilder path(String prefix)

Deprecated.

Use pathPrefix(String) instead.

Sets the context path for the gRPC endpoint. This method will be useful if your gRPC service is bound to a context path. For example:

 // A gRPC service is bound to "/grpc/com.example.MyGrpcService/"
 Server.builder()
       .serviceUnder("/grpc", GrpcService.builder()
                                         .addService(new MyGrpcService())
                                         .build())
       .build();

 // Prefix "/grpc" to the gRPC service path.
 GrpcClient.builder("https://api.example.com")
           .path("/grpc")
           .build(MyGrpcServiceGrpc.XXXStub.class)
 

pathPrefix

public GrpcClientBuilder pathPrefix(String prefix)

Sets the context path for the gRPC endpoint. This method will be useful if your gRPC service is bound to a context path. For example:

 // A gRPC service is bound to "/grpc/com.example.MyGrpcService/"
 Server.builder()
       .serviceUnder("/grpc", GrpcService.builder()
                                         .addService(new MyGrpcService())
                                         .build())
       .build();

 // Prefix "/grpc" to the gRPC service path.
 GrpcClient.builder("https://api.example.com")
           .pathPrefix("/grpc")
           .build(MyGrpcServiceGrpc.XXXStub.class)
 

maxRequestMessageLength

public GrpcClientBuilder maxRequestMessageLength(int maxRequestMessageLength)

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

maxResponseMessageLength

public GrpcClientBuilder maxResponseMessageLength(int maxResponseMessageLength)

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

compressor

public GrpcClientBuilder compressor(Compressor compressor)

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

Note that it is only safe to call this if the server supports the compression format chosen. There is no negotiation performed; if the server does not support the compression chosen, the call will fail.

decompressorRegistry

public GrpcClientBuilder decompressorRegistry(DecompressorRegistry registry)

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

callCredentials

public GrpcClientBuilder callCredentials(CallCredentials callCredentials)

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

enableUnsafeWrapResponseBuffers

@UnstableApi
public GrpcClientBuilder enableUnsafeWrapResponseBuffers(boolean enableUnsafeWrapResponseBuffers)

(Advanced users only) 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.

jsonMarshallerFactory

public GrpcClientBuilder jsonMarshallerFactory(Function<? super ServiceDescriptor,? extends GrpcJsonMarshaller> jsonMarshallerFactory)

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 with com.linecorp.armeria.common.scalapb.ScalaPbJsonMarshaller for Scala.

  
         GrpcClients.builder(grpcServerUri)
                    .jsonMarshallerFactory(_ => ScalaPbJsonMarshaller())
                    .build()
         

clientStubFactory

public GrpcClientBuilder clientStubFactory(GrpcClientStubFactory clientStubFactory)

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

intercept

public GrpcClientBuilder intercept(ClientInterceptor... interceptors)

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

intercept

public GrpcClientBuilder intercept(Iterable<? extends ClientInterceptor> interceptors)

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

rpcDecorator

@Deprecated
public GrpcClientBuilder rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)

Deprecated.

Use either decorator(DecoratingHttpClientFunction) or intercept(ClientInterceptor...) instead.

Unsupported operation. rpcDecorator only supports Thrift.

Overrides:

rpcDecorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the Function that transforms an RpcClient to another

rpcDecorator

@Deprecated
public GrpcClientBuilder rpcDecorator(DecoratingRpcClientFunction decorator)

Deprecated.

Use either decorator(DecoratingHttpClientFunction) or intercept(ClientInterceptor...) instead.

Unsupported operation. rpcDecorator only supports Thrift.

Overrides:

rpcDecorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the DecoratingRpcClientFunction that intercepts an invocation

build

public <T> T build(Class<T> clientType)

Returns a newly-created gRPC client which implements the specified clientType, based on the properties of this builder.

options

public GrpcClientBuilder options(ClientOptions options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptions.

Overrides:

options in class AbstractClientOptionsBuilder

options

public GrpcClientBuilder options(ClientOptionValue<?>... options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

options

public GrpcClientBuilder options(Iterable<ClientOptionValue<?>> options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

option

public <T> GrpcClientBuilder option(ClientOption<T> option,
 T value)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOption and its value.

Overrides:

option in class AbstractClientOptionsBuilder

option

public <T> GrpcClientBuilder option(ClientOptionValue<T> optionValue)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValue.

Overrides:

option in class AbstractClientOptionsBuilder

factory

public GrpcClientBuilder factory(ClientFactory factory)

Description copied from class: AbstractClientOptionsBuilder

Sets the ClientFactory used for creating a client. The default is ClientFactory.ofDefault().

Overrides:

factory in class AbstractClientOptionsBuilder

writeTimeout

public GrpcClientBuilder writeTimeout(Duration writeTimeout)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a socket write attempt.

Overrides:

writeTimeout in class AbstractClientOptionsBuilder

Parameters:

writeTimeout - the timeout. 0 disables the timeout.

writeTimeoutMillis

public GrpcClientBuilder writeTimeoutMillis(long writeTimeoutMillis)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a socket write attempt in milliseconds.

Overrides:

writeTimeoutMillis in class AbstractClientOptionsBuilder

Parameters:

writeTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

responseTimeout

public GrpcClientBuilder responseTimeout(Duration responseTimeout)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a response.

Overrides:

responseTimeout in class AbstractClientOptionsBuilder

Parameters:

responseTimeout - the timeout. 0 disables the timeout.

responseTimeoutMillis

public GrpcClientBuilder responseTimeoutMillis(long responseTimeoutMillis)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a response in milliseconds.

Overrides:

responseTimeoutMillis in class AbstractClientOptionsBuilder

Parameters:

responseTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

maxResponseLength

public GrpcClientBuilder maxResponseLength(long maxResponseLength)

Description copied from class: AbstractClientOptionsBuilder

Sets the maximum allowed length of a server response in bytes.

Overrides:

maxResponseLength in class AbstractClientOptionsBuilder

Parameters:

maxResponseLength - the maximum length in bytes. 0 disables the limit.

requestIdGenerator

public GrpcClientBuilder requestIdGenerator(Supplier<RequestId> requestIdGenerator)

Description copied from class: AbstractClientOptionsBuilder

Sets the Supplier that generates a RequestId.

Overrides:

requestIdGenerator in class AbstractClientOptionsBuilder

successFunction

public GrpcClientBuilder successFunction(SuccessFunction successFunction)

Description copied from class: AbstractClientOptionsBuilder

Sets a SuccessFunction that determines whether a request was handled successfully or not. If unspecified, SuccessFunction.ofDefault() is used.

Overrides:

successFunction in class AbstractClientOptionsBuilder

endpointRemapper

public GrpcClientBuilder endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)

Description copied from class: AbstractClientOptionsBuilder

Sets a Function that remaps an Endpoint into an EndpointGroup. This ClientOption is useful when you need to override a single target host into a group of hosts to enable client-side load-balancing, e.g.

 MyService.Iface client =
     Clients.newClient("tbinary+http://example.com/api",
                       MyService.Iface.class);

 EndpointGroup myGroup = EndpointGroup.of(Endpoint.of("node-1.example.com")),
                                          Endpoint.of("node-2.example.com")));

 MyService.Iface derivedClient =
     Clients.newDerivedClient(client, options -> {
         return options.toBuilder()
                       .endpointRemapper(endpoint -> {
                           if (endpoint.host().equals("example.com")) {
                               return myGroup;
                           } else {
                               return endpoint;
                           }
                       })
                       .build();
     });

 // This request goes to 'node-1.example.com' or 'node-2.example.com'.
 derivedClient.call();
 

Note that the remapping does not occur recursively but only once.

Overrides:

endpointRemapper in class AbstractClientOptionsBuilder

See Also:

• ClientOptions.ENDPOINT_REMAPPER
• ClientOptions.endpointRemapper()

decorator

public GrpcClientBuilder decorator(Function<? super HttpClient,? extends HttpClient> decorator)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP-level decorator.

Overrides:

decorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the Function that transforms an HttpClient to another

decorator

public GrpcClientBuilder decorator(DecoratingHttpClientFunction decorator)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP-level decorator.

Overrides:

decorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the DecoratingHttpClientFunction that intercepts an invocation

clearDecorators

public GrpcClientBuilder clearDecorators()

Description copied from class: AbstractClientOptionsBuilder

Clears all HTTP-level and RPC-level decorators set so far.

Overrides:

clearDecorators in class AbstractClientOptionsBuilder

addHeader

public GrpcClientBuilder addHeader(CharSequence name,
 Object value)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP header.

Overrides:

addHeader in class AbstractClientOptionsBuilder

addHeaders

public GrpcClientBuilder addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP headers.

Overrides:

addHeaders in class AbstractClientOptionsBuilder

setHeader

public GrpcClientBuilder setHeader(CharSequence name,
 Object value)

Description copied from class: AbstractClientOptionsBuilder

Sets the specified HTTP header.

Overrides:

setHeader in class AbstractClientOptionsBuilder

setHeaders

public GrpcClientBuilder setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)

Description copied from class: AbstractClientOptionsBuilder

Sets the specified HTTP headers.

Overrides:

setHeaders in class AbstractClientOptionsBuilder

auth

public GrpcClientBuilder auth(BasicToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the HTTP basic access authentication header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public GrpcClientBuilder auth(OAuth1aToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the OAuth Core 1.0 Revision A header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public GrpcClientBuilder auth(OAuth2Token token)

Description copied from class: AbstractClientOptionsBuilder

Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public GrpcClientBuilder auth(AuthToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

followRedirects

public GrpcClientBuilder followRedirects()

Description copied from class: AbstractClientOptionsBuilder

Enables automatic redirection.

Overrides:

followRedirects in class AbstractClientOptionsBuilder

followRedirects

public GrpcClientBuilder followRedirects(RedirectConfig redirectConfig)

Description copied from class: AbstractClientOptionsBuilder

Sets the RedirectConfig to enable automatic redirection.

Overrides:

followRedirects in class AbstractClientOptionsBuilder

contextCustomizer

public GrpcClientBuilder contextCustomizer(Consumer<? super ClientRequestContext> contextCustomizer)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientRequestContext customizer function so that it customizes the context in the thread that initiated the client call. The given customizer function is evaluated before the customizer function specified by Clients.withContextCustomizer(Consumer).

 static final ThreadLocal<String> USER_ID = new ThreadLocal<>();
 static final AttributeKey<String> USER_ID_ATTR = AttributeKey.valueOf("USER_ID");
 ...
 MyClientStub client =
     Clients.builder(...)
            .contextCustomizer(ctx -> {
                // This customizer will be invoked from the thread that initiates a client call.
                ctx.setAttr(USER_ID_ATTR, USER_ID.get());
            })
            .build(MyClientStub.class);

 // Good:
 // The context data is set by the thread that initiates the client call.
 USER_ID.set("user1");
 try {
     client.executeSomething1(..);
     ...
     client.executeSomethingN(..);
 } finally {
     // Should clean up the thread local storage.
     USER_ID.remove();
 }

 // Bad:
 USER_ID.set("user1");
 executor.execute(() -> {
     // The variable in USER_ID won't be propagated to the context.
     // The variable is not valid at the moment client.executeSomething1() is called.
      client.executeSomething1(..);
 });
 

Note that certain properties of ClientRequestContext, such as:

• ClientRequestContext.endpoint()
• RequestContext.localAddress()
• RequestContext.remoteAddress()

may be null while the customizer function runs, because the target host of the Request is not determined yet.

Overrides:

contextCustomizer in class AbstractClientOptionsBuilder

See Also:

• Clients.withContextCustomizer(Consumer)