Package com.linecorp.armeria.client

Class ClientFactoryBuilder

java.lang.Object
com.linecorp.armeria.client.ClientFactoryBuilder
All Implemented Interfaces:
TlsSetters
public final class ClientFactoryBuilder extends Object implements TlsSetters
Builds a new ClientFactory.

Example


 final ClientFactory factory =
         ClientFactory.builder()
                      // Set the connection timeout to 5 seconds.
                      .connectTimeoutMillis(5000)
                      // Set the socket send buffer to 1 MiB.
                      .socketOption(ChannelOption.SO_SNDBUF, 1048576)
                      // Disable certificate verification; never do this in production!
                      .tlsNoVerify()
                      .build();

  • Method Details

    • workerGroup

      public ClientFactoryBuilder workerGroup(io.netty.channel.EventLoopGroup workerGroup, boolean shutdownOnClose)
      Sets the worker EventLoopGroup which is responsible for performing socket I/O and running Client.execute(ClientRequestContext, Request). If not set, the common worker group is used.
      Parameters:
      shutdownOnClose - whether to shut down the worker EventLoopGroup when the ClientFactory is closed

    • workerGroup

      public ClientFactoryBuilder workerGroup(int numThreads)
      Uses a newly created EventLoopGroup with the specified number of threads for performing socket I/O and running Client.execute(ClientRequestContext, Request). The worker EventLoopGroup will be shut down when the ClientFactory is closed.
      Parameters:
      numThreads - the number of event loop threads

    • eventLoopSchedulerFactory

      public ClientFactoryBuilder eventLoopSchedulerFactory(Function<? super io.netty.channel.EventLoopGroup,? extends EventLoopScheduler> eventLoopSchedulerFactory)
      Sets the factory that creates an EventLoopScheduler which is responsible for assigning an EventLoop to handle a connection to the specified Endpoint.

    • maxNumEventLoopsPerHttp1Endpoint

      public ClientFactoryBuilder maxNumEventLoopsPerHttp1Endpoint(int maxNumEventLoopsPerEndpoint)
      Sets the maximum number of EventLoops which will be used to handle HTTP/1.1 connections except the ones specified by maxNumEventLoopsFunction(ToIntFunction). 1 is used by default.

    • maxNumEventLoopsPerEndpoint

      public ClientFactoryBuilder maxNumEventLoopsPerEndpoint(int maxNumEventLoopsPerEndpoint)
      Sets the maximum number of EventLoops which will be used to handle HTTP/2 connections except the ones specified by maxNumEventLoopsFunction(ToIntFunction). 1 is used by default.

    • maxNumEventLoopsFunction

      public ClientFactoryBuilder maxNumEventLoopsFunction(ToIntFunction<Endpoint> maxNumEventLoopsFunction)
      Sets the ToIntFunction which takes an Endpoint and produces the maximum number of EventLoops which will be used to handle connections to the specified Endpoint. The function should return 0 or a negative value for the Endpoints which it doesn't want to handle. For example: 
      
 ToIntFunction<Endpoint> function = endpoint -> {
     if (endpoint.equals(Endpoint.of("foo.com"))) {
         return 5;
     }
     if (endpoint.host().contains("bar.com")) {
         return Integer.MAX_VALUE; // The value will be clamped at the number of event loops.
     }
     return -1; // Should return 0 or a negative value to use the default value.
 }

    • connectTimeout

      public ClientFactoryBuilder connectTimeout(Duration connectTimeout)
      Sets the timeout of a socket connection attempt.

    • connectTimeoutMillis

      public ClientFactoryBuilder connectTimeoutMillis(long connectTimeoutMillis)
      Sets the timeout of a socket connection attempt in milliseconds.

    • channelOption

      public <T> ClientFactoryBuilder channelOption(io.netty.channel.ChannelOption<T> option, T value)
      Sets the options of sockets created by the ClientFactory.

    • tlsNoVerify

      public ClientFactoryBuilder tlsNoVerify()
      Disables the verification of server's TLS certificate chain. If you want to disable verification for only specific hosts, use tlsNoVerifyHosts(String...). Note: You should never use this in production but only for a testing purpose.
      See Also:

    • tlsNoVerifyHosts

      public ClientFactoryBuilder tlsNoVerifyHosts(String... insecureHosts)
      Disables the verification of server's TLS certificate chain for specific hosts. If you want to disable all verification, use tlsNoVerify() . Note: You should never use this in production but only for a testing purpose.
      See Also:

    • tls

      public ClientFactoryBuilder tls(File keyCertChainFile, File keyFile)
      Configures SSL or TLS for client certificate authentication with the specified keyCertChainFile and cleartext keyFile.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(File keyCertChainFile, File keyFile, @Nullable @Nullable String keyPassword)
      Configures SSL or TLS for client certificate authentication with the specified keyCertChainFile, keyFile and keyPassword.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(InputStream keyCertChainInputStream, InputStream keyInputStream)
      Configures SSL or TLS for client certificate authentication with the specified keyCertChainInputStream and cleartext keyInputStream.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(InputStream keyCertChainInputStream, InputStream keyInputStream, @Nullable @Nullable String keyPassword)
      Configures SSL or TLS for client certificate authentication with the specified keyCertChainInputStream and keyInputStream and keyPassword.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(PrivateKey key, X509Certificate... keyCertChain)
      Configures SSL or TLS for client certificate authentication with the specified cleartext PrivateKey and X509Certificate chain.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(PrivateKey key, Iterable<? extends X509Certificate> keyCertChain)
      Configures SSL or TLS for client certificate authentication with the specified cleartext PrivateKey and X509Certificate chain.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(PrivateKey key, @Nullable @Nullable String keyPassword, X509Certificate... keyCertChain)
      Configures SSL or TLS for client certificate authentication with the specified PrivateKey, keyPassword and X509Certificate chain.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(PrivateKey key, @Nullable @Nullable String keyPassword, Iterable<? extends X509Certificate> keyCertChain)
      Configures SSL or TLS for client certificate authentication with the specified PrivateKey, keyPassword and X509Certificate chain.
      Specified by:
      tls in interface TlsSetters

    • tls

      public ClientFactoryBuilder tls(KeyManagerFactory keyManagerFactory)
      Configures SSL or TLS for client certificate authentication with the specified KeyManagerFactory.
      Specified by:
      tls in interface TlsSetters

    • tlsCustomizer

      public ClientFactoryBuilder tlsCustomizer(Consumer<? super io.netty.handler.ssl.SslContextBuilder> tlsCustomizer)
      Adds the Consumer which can arbitrarily configure the SslContextBuilder that will be applied to the SSL session. For example, use SslContextBuilder.trustManager(TrustManagerFactory) to configure a custom server CA or SslContextBuilder.keyManager(KeyManagerFactory) to configure a client certificate for SSL authorization.
      Specified by:
      tlsCustomizer in interface TlsSetters

    • tlsAllowUnsafeCiphers

      @Deprecated public ClientFactoryBuilder tlsAllowUnsafeCiphers()
      Deprecated.
      It's not recommended to enable this option. Use it only when you have no other way to communicate with an insecure peer than this.
      Allows the bad cipher suites listed in RFC7540 for TLS handshake.

      Note that enabling this option increases the security risk of your connection. Use it only when you must communicate with a legacy system that does not support secure cipher suites. See Section 9.2.2, RFC7540 for more information. This option is disabled by default.

    • tlsAllowUnsafeCiphers

      @Deprecated public ClientFactoryBuilder tlsAllowUnsafeCiphers(boolean tlsAllowUnsafeCiphers)
      Deprecated.
      It's not recommended to enable this option. Use it only when you have no other way to communicate with an insecure peer than this.
      Allows the bad cipher suites listed in RFC7540 for TLS handshake.

      Note that enabling this option increases the security risk of your connection. Use it only when you must communicate with a legacy system that does not support secure cipher suites. See Section 9.2.2, RFC7540 for more information. This option is disabled by default.

      Parameters:
      tlsAllowUnsafeCiphers - Whether to allow the unsafe ciphers

    • addressResolverGroupFactory

      public ClientFactoryBuilder addressResolverGroupFactory(Function<? super io.netty.channel.EventLoopGroup,? extends io.netty.resolver.AddressResolverGroup<? extends InetSocketAddress>> addressResolverGroupFactory)
      Sets the factory that creates a AddressResolverGroup which resolves remote addresses into InetSocketAddresses.
      Throws:
      IllegalStateException - if domainNameResolverCustomizer(Consumer) was called already.

    • domainNameResolverCustomizer

      public ClientFactoryBuilder domainNameResolverCustomizer(Consumer<? super DnsResolverGroupBuilder> dnsResolverGroupCustomizer)
      Adds the specified Consumer which customizes the given DnsNameResolverBuilder. This method is useful when you want to change the behavior of the default domain name resolver, such as changing the DNS server list.
      Throws:
      IllegalStateException - if addressResolverGroupFactory(Function) was called already.

    • http2InitialConnectionWindowSize

      public ClientFactoryBuilder http2InitialConnectionWindowSize(int http2InitialConnectionWindowSize)
      Sets the initial connection flow-control window size. The HTTP/2 connection is first established with 65535 bytes of connection flow-control window size, and it is changed if and only if http2InitialConnectionWindowSize is set. Note that this setting affects the connection-level window size, not the window size of streams.
      See Also:

    • http2InitialStreamWindowSize

      public ClientFactoryBuilder http2InitialStreamWindowSize(int http2InitialStreamWindowSize)
      Sets the SETTINGS_INITIAL_WINDOW_SIZE for HTTP/2 stream-level flow control. Note that this setting affects the window size of all streams, not the connection-level window size.
      See Also:

    • http2MaxFrameSize

      public ClientFactoryBuilder http2MaxFrameSize(int http2MaxFrameSize)
      Sets the SETTINGS_MAX_FRAME_SIZE that indicates the size of the largest frame payload that this client is willing to receive.

    • http2MaxHeaderListSize

      public ClientFactoryBuilder http2MaxHeaderListSize(long http2MaxHeaderListSize)
      Sets the SETTINGS_MAX_HEADER_LIST_SIZE that indicates the maximum size of header list that the client is prepared to accept, in octets.

    • http1MaxInitialLineLength

      public ClientFactoryBuilder http1MaxInitialLineLength(int http1MaxInitialLineLength)
      Sets the maximum length of an HTTP/1 response initial line.

    • http1MaxHeaderSize

      public ClientFactoryBuilder http1MaxHeaderSize(int http1MaxHeaderSize)
      Sets the maximum length of all headers in an HTTP/1 response.

    • http1MaxChunkSize

      public ClientFactoryBuilder http1MaxChunkSize(int http1MaxChunkSize)
      Sets the maximum length of each chunk in an HTTP/1 response content. The content or a chunk longer than this value will be split into smaller chunks so that their lengths never exceed it.

    • idleTimeout

      public ClientFactoryBuilder idleTimeout(Duration idleTimeout)
      Sets the idle timeout of a socket connection. The connection is closed if there is no request in progress for the given amount of time. By default, HTTP/2 PING frames do not prevent connection from closing. Use the method idleTimeout(Duration, boolean) to set whether to prevent connection from closing when an HTTP/2 PING frame or the response of "OPTIONS * HTTP/1.1" is received.

    • idleTimeout

      @UnstableApi public ClientFactoryBuilder idleTimeout(Duration idleTimeout, boolean keepAliveOnPing)
      Sets the idle timeout of a socket connection. The connection is closed if there is no request in progress for the given amount of time. If keepAliveOnPing is true, the idle timeout is reset when an HTTP/2 PING frame or the response of "OPTIONS * HTTP/1.1" is received.

    • idleTimeoutMillis

      public ClientFactoryBuilder idleTimeoutMillis(long idleTimeoutMillis)
      Sets the idle timeout of a socket connection in milliseconds. The connection is closed if there is no request in progress for the given amount of time.

    • idleTimeoutMillis

      @UnstableApi public ClientFactoryBuilder idleTimeoutMillis(long idleTimeoutMillis, boolean keepAliveOnPing)
      Sets the idle timeout of a socket connection. The connection is closed if there is no request in progress for the given amount of time. If keepAliveOnPing is true, the idle timeout is reset when an HTTP/2 PING frame or the response of "OPTIONS * HTTP/1.1" is received.

    • pingIntervalMillis

      public ClientFactoryBuilder pingIntervalMillis(long pingIntervalMillis)
      Sets the PING interval in milliseconds. When neither read nor write was performed for the given pingIntervalMillis, a PING frame is sent for HTTP/2 or an OPTIONS request with an asterisk ("*") is sent for HTTP/1.

      Note that this settings is only in effect when idleTimeoutMillis(long)} or idleTimeout(Duration) is greater than the specified PING interval.

      The minimum allowed PING interval is 1000L milliseconds. 0 means the client will not send a PING.

      Throws:
      IllegalArgumentException - if the specified pingIntervalMillis is smaller than 1000L milliseconds.

    • pingInterval

      public ClientFactoryBuilder pingInterval(Duration pingInterval)
      Sets the PING interval. When neither read nor write was performed for the given pingInterval, a PING frame is sent for HTTP/2 or an OPTIONS request with an asterisk ("*") is sent for HTTP/1.

      Note that this settings is only in effect when idleTimeoutMillis(long)} or idleTimeout(Duration) is greater than the specified PING interval.

      The minimum allowed PING interval is 1000L milliseconds. 0 means the client will not send a PING.

      Throws:
      IllegalArgumentException - if the specified pingInterval is smaller than 1000L milliseconds.

    • maxConnectionAgeMillis

      public ClientFactoryBuilder maxConnectionAgeMillis(long maxConnectionAgeMillis)
      Sets the maximum allowed age of a connection in millis for keep-alive. A connection is disconnected after the specified maxConnectionAgeMillis since the connection was established. This option is disabled by default, which means unlimited.
      Parameters:
      maxConnectionAgeMillis - the maximum connection age in millis. 0 disables the limit.
      Throws:
      IllegalArgumentException - if the specified maxConnectionAgeMillis is smaller than 1000L milliseconds.

    • maxConnectionAge

      public ClientFactoryBuilder maxConnectionAge(Duration maxConnectionAge)
      Sets the maximum allowed age of a connection for keep-alive. A connection is disconnected after the specified maxConnectionAge since the connection was established. This option is disabled by default, which means unlimited.
      Parameters:
      maxConnectionAge - the maximum connection age. 0 disables the limit.
      Throws:
      IllegalArgumentException - if the specified maxConnectionAge is smaller than 1000L milliseconds.

    • maxNumRequestsPerConnection

      public ClientFactoryBuilder maxNumRequestsPerConnection(int maxNumRequestsPerConnection)
      Sets the maximum allowed number of requests that can be sent through one connection. This option is disabled by default, which means unlimited.
      Parameters:
      maxNumRequestsPerConnection - the maximum number of requests per connection. 0 disables the limit.

    • useHttp2Preface

      public ClientFactoryBuilder useHttp2Preface(boolean useHttp2Preface)
      Sets whether to send an HTTP/2 preface string instead of an HTTP/1 upgrade request to negotiate the protocol version of a cleartext HTTP connection.

    • preferHttp1

      @UnstableApi public ClientFactoryBuilder preferHttp1(boolean preferHttp1)
      Sets whether to use HTTP/1.1 instead of HTTP/2. If enabled, the client will not attempt to upgrade to HTTP/2 for SessionProtocol.HTTP and SessionProtocol.HTTPS. However, the client will use HTTP/2 if SessionProtocol.H2 or SessionProtocol.H2C is used. This option is disabled by default.

    • useHttp2WithoutAlpn

      @UnstableApi public ClientFactoryBuilder useHttp2WithoutAlpn(boolean useHttp2WithoutAlpn)
      Sets whether to use HTTP/2 without ALPN. This is useful if you want to communicate with an HTTP/2 server over TLS but the server does not support ALPN.

    • useHttp1Pipelining

      public ClientFactoryBuilder useHttp1Pipelining(boolean useHttp1Pipelining)
      Sets whether to use HTTP pipelining for HTTP/1 connections. This does not affect HTTP/2 connections. This option is disabled by default.

    • connectionPoolListener

      public ClientFactoryBuilder connectionPoolListener(ConnectionPoolListener connectionPoolListener)
      Sets the listener which is notified on a connection pool event.

    • meterRegistry

      public ClientFactoryBuilder meterRegistry(io.micrometer.core.instrument.MeterRegistry meterRegistry)
      Sets the MeterRegistry which collects various stats.

    • proxyConfig

      public ClientFactoryBuilder proxyConfig(ProxyConfig proxyConfig)
      Sets the ProxyConfig which contains proxy related configuration.

    • proxyConfig

      public ClientFactoryBuilder proxyConfig(ProxySelector proxySelector)
      Sets the ProxySelector which determines the ProxyConfig to be used.

      This method makes a best effort to provide compatibility with ProxySelector, but it has some limitations. See ProxyConfigSelector.of(ProxySelector) for more information.

    • proxyConfig

      public ClientFactoryBuilder proxyConfig(ProxyConfigSelector proxyConfigSelector)
      Sets the ProxyConfigSelector which determines the ProxyConfig to be used.

    • http1HeaderNaming

      public ClientFactoryBuilder http1HeaderNaming(Http1HeaderNaming http1HeaderNaming)
      Sets the Http1HeaderNaming which converts a lower-cased HTTP/2 header name into another HTTP/1 header name. This is useful when communicating with a legacy system that only supports case-sensitive HTTP/1 headers.

    • option

      public <T> ClientFactoryBuilder option(ClientFactoryOption<T> option, T value)
      Adds the specified ClientFactoryOption and its value.

    • option

      public <T> ClientFactoryBuilder option(ClientFactoryOptionValue<T> optionValue)
      Adds the specified ClientFactoryOptionValue.

    • options

      public ClientFactoryBuilder options(ClientFactoryOptions options)
      Adds the specified ClientFactoryOptions.

    • build

      public ClientFactory build()
      Returns a newly-created ClientFactory based on the properties of this builder.

    • toString

      public String toString()
      Overrides:
      toString in class Object