The base com.twitter.finagle.Dtab used to interpret logical destinations for this client.
The base com.twitter.finagle.Dtab used to interpret logical destinations for this client. (This is given as a function to permit late initialization of com.twitter.finagle.Dtab.base.)
Construct a Service.
Construct a ServiceFactory.
Construct a ServiceFactory. This is useful for stateful protocols (e.g., those that support transactions or authentication).
Use the given channel factory instead of the default.
Use the given channel factory instead of the default. Note that
when using a non-default ChannelFactory, finagle can't
meaningfully reference count factory usage, and so the caller is
responsible for calling releaseExternalResources()
.
Specify a cluster directly.
Specify a cluster directly. A com.twitter.finagle.builder.Cluster defines a dynamic mechanism for specifying a set of endpoints to which this client remains connected.
A variation of codec for codecs that support only client-codecs.
A variation of codec
that supports codec factories.
A variation of codec
that supports codec factories. This is
used by codecs that need dynamic construction, but should be
transparent to the user.
Specify the codec.
Specify the codec. The codec implements the network protocol
used by the client, and consequently determines the Req
and Rep
type variables. One of the codec variations is required.
The connect timeout is the timeout applied to the acquisition of a Service.
The connect timeout is the timeout applied to the acquisition of
a Service. This includes both queueing time (eg. because we
cannot create more connections due to hostConnectionLimit
and
there are more than hostConnectionLimit
requests outstanding)
as well as physical connection time. Futures returned from
factory()
will always be satisfied within this timeout.
This timeout is also used for name resolution, separately from queueing and physical connection time, so in the worst case the time to acquire a service may be double the given duration before timing out.
When true, the client is daemonized.
When true, the client is daemonized. As with java threads, a process can exit only when all remaining clients are daemonized. False by default.
The logical destination of requests dispatched through this client.
The logical destination of requests dispatched through this client, as evaluated by a resolver.
The logical destination of requests dispatched through this client, as evaluated by a resolver. If the name evaluates a label, this replaces the builder's current name.
Provide an alternative to putting all request exceptions under a "failures" stat.
Provide an alternative to putting all request exceptions under a "failures" stat. Typical implementations may report any cancellations or validation errors separately so success rate considers only valid non cancelled requests.
function to record failure details.
Experimental option to buffer size
connections from the pool.
Experimental option to buffer size
connections from the pool.
The buffer is fast and lock-free, reducing contention for
services with very high requests rates. The buffer size should
be sized roughly to the expected concurrency. Buffers sized by
power-of-twos may be faster due to the use of modular
arithmetic.
This will be integrated into the mainline pool, at which time the experimental option will go away.
Marks a host dead on connection failure.
Marks a host dead on connection failure. The host remains dead until we successfully connect. Intermediate connection attempts *are* respected, but host availability is turned off during the reconnection period.
Completely replaces the FailureAccrualFactory from the underlying stack
with the ServiceFactoryWrapper returned from the given function factory
.
Completely replaces the FailureAccrualFactory from the underlying stack
with the ServiceFactoryWrapper returned from the given function factory
.
To completely disable FailureAccrualFactory use noFailureAccrual
.
Use the given parameters for failure accrual.
Use the given parameters for failure accrual. The first parameter is the number of *successive* failures that are required to mark a host failed. The second parameter specifies how long the host is dead for, once marked.
To completely disable FailureAccrualFactory use noFailureAccrual
.
The core size of the connection pool: the pool is not shrinked below this limit.
The amount of time a connection is allowed to linger (when it otherwise would have been closed by the pool) before being closed.
The maximum number of connections that are allowed per host.
The maximum number of connections that are allowed per host. Required. Finagle guarantees to never have more active connections than this limit.
The maximum time a connection is allowed to linger unused.
The maximum time a connection is allowed to exist, regardless of occupancy.
The maximum queue size for the connection pool.
A convenience method for specifying a one-host java.net.SocketAddress client.
A variant of {{hosts}} that takes a sequence of java.net.SocketAddress instead.
Specify the set of hosts to connect this client to.
Specify the set of hosts to connect this client to. Requests will be load balanced across these. This is a shorthand form for specifying a cluster.
One of the {{hosts}} variations or direct specification of the cluster (via {{cluster}}) is required.
comma-separated "host:port" string.
Make connections via the given HTTP proxy.
Make connections via the given HTTP proxy. If this is defined concurrently with socksProxy, the order in which they are applied is undefined.
For the http proxy use these Credentials for authentication.
Apply TCP keepAlive (SO_KEEPALIVE
socket option).
Specify a load balancer.
Specify a load balancer. The load balancer implements a strategy for choosing one from a set of hosts to service a request
Log very detailed debug information to the given logger.
Give a meaningful name to the client.
Give a meaningful name to the client. Required.
Disables FailureAccrualFactory.
Disables FailureAccrualFactory.
To replace the FailureAccrualFactory use failureAccrualFactory
.
The maximum time a connection may have received no data.
Sets the TCP recv buffer size.
Report per host stats to the given StatsReceiver
.
Report per host stats to the given StatsReceiver
.
The statsReceiver will be scoped per client, like this:
client/connect_latency_ms_max/0.0.0.0:64754
Report stats to the given StatsReceiver
.
Report stats to the given StatsReceiver
. This will report
verbose global statistics and counters, that in turn may be
exported to monitoring applications.
Per hosts statistics will NOT be exported to this receiver
The request timeout is the time given to a *single* request (if there are retries, they each get a fresh request timeout).
The request timeout is the time given to a *single* request (if there are retries, they each get a fresh request timeout). The timeout is applied only after a connection has been acquired. That is: it is applied to the interval between the dispatch of the request and the receipt of the response.
Retry (some) failed requests up to value - 1
times.
Retry (some) failed requests up to value - 1
times.
Retries are only done if the request failed with something known to be safe to retry. This includes WriteExceptions and Failures that are marked restartable.
the maximum number of attempts (including retries) that can be made.
1
means one attempt and no retries
on failure.2
means one attempt and then a
single retry if the failure is known to be safe to retry.
The failures seen in the client will not include
application level failures. This is particularly important for
codecs that include exceptions, such as Thrift
.
This is only applicable to service-builds (build()
).
Retry failed requests according to the given RetryPolicy.
Retry failed requests according to the given RetryPolicy.
The failures seen in the client will not include
application level failures. This is particularly important for
codecs that include exceptions, such as Thrift
.
This is only applicable to service-builds (build()
).
Sets the TCP send buffer size.
Make connections via the given SOCKS proxy.
Make connections via the given SOCKS proxy. If this is defined concurrently with httpProxy, the order in which they are applied is undefined.
For the socks proxy use this username for authentication.
For the socks proxy use this username for authentication. socksPassword and socksProxy must be set as well
Overrides the stack and com.twitter.finagle.Client that will be used by this builder.
Overrides the stack and com.twitter.finagle.Client that will be used by this builder.
A StackBasedClient
representation of a
com.twitter.finagle.Client. client
is materialized with the state of
configuration when build
is called. There is no guarantee that all
builder parameters will be used by the resultant Client
; it is up to the
discretion of client
itself and the protocol implementation. For example,
the Mux protocol has no use for most connection pool parameters (e.g.
hostConnectionLimit
). Thus when configuring
com.twitter.finagle.ThriftMux clients (via stack(ThriftMux.client)),
such connection pool parameters will not be applied.
Specify the TCP connection timeout.
Total request timeout.
Total request timeout. This timeout is applied from the issuance
of a request (through service(request)
) until the
satisfaction of that reply future. No request will take longer
than this.
Applicable only to service-builds (build()
)
Encrypt the connection with SSL.
Encrypt the connection with SSL. The Engine to use can be passed into the client. This allows the user to use client certificates SSL Hostname Validation is performed, on the passed in hostname
Encrypt the connection with SSL.
Encrypt the connection with SSL. The Engine to use can be passed into the client. This allows the user to use client certificates No SSL Hostname Validation is performed
Encrypt the connection with SSL.
Encrypt the connection with SSL. Hostname verification will be provided against the given hostname.
Do not perform TLS validation.
Do not perform TLS validation. Probably dangerous.
Specifies a tracer that receives trace events.
Specifies a tracer that receives trace events. See com.twitter.finagle.tracing for details.
Configures the traffic class.
Configures the traffic class.
Transporter.TrafficClass
Construct a Service, with runtime checks for builder completeness.
Construct a ServiceFactory, with runtime checks for builder completeness.
The maximum time a connection may not have sent any data.
(Since version 5.0.1) Used for ABI compat
(Since version 5.0.1) Used for ABI compat
(Since version 5.0.1) Use tcpConnectTimeout instead
(Since version 5.3.10)
(Since version 2014-12-02) Use socksProxy(socksProxy: Option[SocketAddress])
(Since version 7.0.0) Use tracer() instead
Specifies a tracer that receives trace events.
Specifies a tracer that receives trace events. See com.twitter.finagle.tracing for details.
(Since version 7.0.0) Use tracer() instead
A builder of Finagle Clients.
Please see the Finagle user guide for information on a newer set of client-construction APIs introduced in Finagle v6.
The
ClientBuilder
requires the definition ofcluster
,codec
, andhostConnectionLimit
. In Scala, these are statically type checked, and in Java the lack of any of the above causes a runtime error.The
build
method uses an implicit argument to statically typecheck the builder (to ensure completeness, see above). The Java compiler cannot provide such implicit, so we provide a separate function in Java to accomplish this. Thus, the Java code for the above isAlternatively, using the
unsafeBuild
method onClientBuilder
verifies the builder dynamically, resulting in a runtime error instead of a compiler error.Defaults
The following defaults are applied to clients constructed via ClientBuilder, unless overridden with the corresponding method. These defaults were chosen carefully so as to work well for most use cases.
Commonly-configured options:
connectTimeout
: Duration.ToptcpConnectTimeout
: 1 secondrequestTimeout
: Duration.Toptimeout
: Duration.TophostConnectionLimit
:Int.MaxValue
hostConnectionCoresize
: 0hostConnectionIdleTime
: Duration.TophostConnectionMaxWaiters
:Int.MaxValue
failFast
: truefailureAccrualParams
,failureAccrualFactory
:numFailures
= 5,markDeadFor
= 5 secondsAdvanced options:
Before changing any of these, make sure that you know exactly how they will affect your application -- these options are typically only changed by expert users.
keepAlive
: Unspecified, in which case the Java default offalse
is usedreaderIdleTimeout
: Duration.TopwriterIdleTimeout
: Duration.TophostConnectionMaxIdleTime
: Duration.TophostConnectionMaxLifeTime
: Duration.TopsendBufferSize
,recvBufferSize
: OS-defined default value