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 com.linecorp.armeria.client.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 Details

    • serializationFormat

      public GrpcClientBuilder serializationFormat(com.linecorp.armeria.common.SerializationFormat serializationFormat)
      Sets the gRPC SerializationFormat. If not set, the Scheme.serializationFormat() specified when creating this builder will be used by default.
      See Also:

    • 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:

    • 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 com.linecorp.armeria.client.RpcClient,? extends com.linecorp.armeria.client.RpcClient> decorator)
      Deprecated.
      Use either decorator(DecoratingHttpClientFunction) or intercept(ClientInterceptor...) instead.
      Unsupported operation. rpcDecorator only supports Thrift.
      Overrides:
      rpcDecorator in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • rpcDecorator

      @Deprecated public GrpcClientBuilder rpcDecorator(com.linecorp.armeria.client.DecoratingRpcClientFunction decorator)
      Deprecated.
      Use either decorator(DecoratingHttpClientFunction) or intercept(ClientInterceptor...) instead.
      Unsupported operation. rpcDecorator only supports Thrift.
      Overrides:
      rpcDecorator in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • 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(com.linecorp.armeria.client.ClientOptions options)
      Overrides:
      options in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • options

      public GrpcClientBuilder options(com.linecorp.armeria.client.ClientOptionValue<?>... options)
      Overrides:
      options in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • options

      public GrpcClientBuilder options(Iterable<com.linecorp.armeria.client.ClientOptionValue<?>> options)
      Overrides:
      options in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • option

      public <T> GrpcClientBuilder option(com.linecorp.armeria.client.ClientOption<T> option, T value)
      Overrides:
      option in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • option

      public <T> GrpcClientBuilder option(com.linecorp.armeria.client.ClientOptionValue<T> optionValue)
      Overrides:
      option in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • factory

      public GrpcClientBuilder factory(com.linecorp.armeria.client.ClientFactory factory)
      Overrides:
      factory in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • writeTimeout

      public GrpcClientBuilder writeTimeout(Duration writeTimeout)
      Overrides:
      writeTimeout in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • writeTimeoutMillis

      public GrpcClientBuilder writeTimeoutMillis(long writeTimeoutMillis)
      Overrides:
      writeTimeoutMillis in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • responseTimeout

      public GrpcClientBuilder responseTimeout(Duration responseTimeout)
      Overrides:
      responseTimeout in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • responseTimeoutMillis

      public GrpcClientBuilder responseTimeoutMillis(long responseTimeoutMillis)
      Overrides:
      responseTimeoutMillis in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • maxResponseLength

      public GrpcClientBuilder maxResponseLength(long maxResponseLength)
      Overrides:
      maxResponseLength in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • requestIdGenerator

      public GrpcClientBuilder requestIdGenerator(Supplier<com.linecorp.armeria.common.RequestId> requestIdGenerator)
      Overrides:
      requestIdGenerator in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • successFunction

      public GrpcClientBuilder successFunction(com.linecorp.armeria.common.SuccessFunction successFunction)
      Overrides:
      successFunction in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • endpointRemapper

      public GrpcClientBuilder endpointRemapper(Function<? super com.linecorp.armeria.client.Endpoint,? extends com.linecorp.armeria.client.endpoint.EndpointGroup> endpointRemapper)
      Overrides:
      endpointRemapper in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • decorator

      public GrpcClientBuilder decorator(Function<? super com.linecorp.armeria.client.HttpClient,? extends com.linecorp.armeria.client.HttpClient> decorator)
      Overrides:
      decorator in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • decorator

      public GrpcClientBuilder decorator(com.linecorp.armeria.client.DecoratingHttpClientFunction decorator)
      Overrides:
      decorator in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • clearDecorators

      public GrpcClientBuilder clearDecorators()
      Overrides:
      clearDecorators in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • addHeader

      public GrpcClientBuilder addHeader(CharSequence name, Object value)
      Overrides:
      addHeader in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • addHeaders

      public GrpcClientBuilder addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)
      Overrides:
      addHeaders in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • setHeader

      public GrpcClientBuilder setHeader(CharSequence name, Object value)
      Overrides:
      setHeader in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • setHeaders

      public GrpcClientBuilder setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)
      Overrides:
      setHeaders in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • auth

      public GrpcClientBuilder auth(com.linecorp.armeria.common.auth.BasicToken token)
      Overrides:
      auth in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • auth

      public GrpcClientBuilder auth(com.linecorp.armeria.common.auth.OAuth1aToken token)
      Overrides:
      auth in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • auth

      public GrpcClientBuilder auth(com.linecorp.armeria.common.auth.OAuth2Token token)
      Overrides:
      auth in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • auth

      public GrpcClientBuilder auth(com.linecorp.armeria.common.auth.AuthToken token)
      Overrides:
      auth in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • followRedirects

      public GrpcClientBuilder followRedirects()
      Overrides:
      followRedirects in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • followRedirects

      public GrpcClientBuilder followRedirects(com.linecorp.armeria.client.redirect.RedirectConfig redirectConfig)
      Overrides:
      followRedirects in class com.linecorp.armeria.client.AbstractClientOptionsBuilder

    • contextCustomizer

      public GrpcClientBuilder contextCustomizer(Consumer<? super com.linecorp.armeria.client.ClientRequestContext> contextCustomizer)
      Overrides:
      contextCustomizer in class com.linecorp.armeria.client.AbstractClientOptionsBuilder