Class/Object

com.twitter.finagle.builder

ClientBuilder

Related Docs: object ClientBuilder | package builder

Permalink

class ClientBuilder[Req, Rep, HasCluster, HasCodec, HasHostConnectionLimit] extends AnyRef

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.

val client = ClientBuilder()
  .codec(Http)
  .hosts("localhost:10000,localhost:10001,localhost:10003")
  .hostConnectionLimit(1)
  .tcpConnectTimeout(1.second)        // max time to spend establishing a TCP connection.
  .retries(2)                         // (1) per-request retries
  .reportTo(new OstrichStatsReceiver) // export host-level load data to ostrich
  .logger(Logger.getLogger("http"))
  .build()

The ClientBuilder requires the definition of cluster, codec, and hostConnectionLimit. 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 is

Service<HttpRequest, HttpResponse> service =
 ClientBuilder.safeBuild(
   ClientBuilder.get()
     .codec(new Http())
     .hosts("localhost:10000,localhost:10001,localhost:10003")
     .hostConnectionLimit(1)
     .tcpConnectTimeout(1.second)
     .retries(2)
     .reportTo(new OstrichStatsReceiver())
     .logger(Logger.getLogger("http")))

Alternatively, using the unsafeBuild method on ClientBuilder 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:

Advanced 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.

Linear Supertypes
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. ClientBuilder
  2. AnyRef
  3. Any
  1. Hide All
  2. Show all
Visibility
  1. Public
  2. All

Type Members

  1. type FullySpecifiedConfig = ClientConfig[Req, Rep, Yes, Yes, Yes]

    Permalink
  2. type This = ClientBuilder[Req, Rep, HasCluster, HasCodec, HasHostConnectionLimit]

    Permalink
  3. type ThisConfig = ClientConfig[Req, Rep, HasCluster, HasCodec, HasHostConnectionLimit]

    Permalink

Value Members

  1. final def !=(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int

    Permalink
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0

    Permalink
    Definition Classes
    Any
  5. def baseDtab(baseDtab: () ⇒ Dtab): This

    Permalink

    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.)

  6. def build()(implicit THE_BUILDER_IS_NOT_FULLY_SPECIFIED_SEE_ClientBuilder_DOCUMENTATION: ClientConfigEvidence[HasCluster, HasCodec, HasHostConnectionLimit]): Service[Req, Rep]

    Permalink

    Construct a Service.

  7. def buildFactory()(implicit THE_BUILDER_IS_NOT_FULLY_SPECIFIED_SEE_ClientBuilder_DOCUMENTATION: ClientConfigEvidence[HasCluster, HasCodec, HasHostConnectionLimit]): ServiceFactory[Req, Rep]

    Permalink

    Construct a ServiceFactory.

    Construct a ServiceFactory. This is useful for stateful protocols (e.g., those that support transactions or authentication).

  8. def channelFactory(cf: ChannelFactory): This

    Permalink

    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().

  9. def clone(): AnyRef

    Permalink
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  10. def cluster(cluster: Cluster[SocketAddress]): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink

    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.

  11. def codec[Req1, Rep1](codecFactory: (ClientCodecConfig) ⇒ Codec[Req1, Rep1]): ClientBuilder[Req1, Rep1, HasCluster, Yes, HasHostConnectionLimit]

    Permalink

    A variation of codec for codecs that support only client-codecs.

  12. def codec[Req1, Rep1](codecFactory: CodecFactory[Req1, Rep1]): ClientBuilder[Req1, Rep1, HasCluster, Yes, HasHostConnectionLimit]

    Permalink

    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.

  13. def codec[Req1, Rep1](codec: Codec[Req1, Rep1]): ClientBuilder[Req1, Rep1, HasCluster, Yes, HasHostConnectionLimit]

    Permalink

    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.

  14. def connectTimeout(duration: Duration): This

    Permalink

    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.

  15. def daemon(daemonize: Boolean): This

    Permalink

    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.

  16. def dest(name: Name): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink

    The logical destination of requests dispatched through this client.

  17. def dest(addr: String): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink

    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.

  18. final def eq(arg0: AnyRef): Boolean

    Permalink
    Definition Classes
    AnyRef
  19. def equals(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  20. def exceptionCategorizer(exceptionStatsHandler: ExceptionStatsHandler): This

    Permalink

    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.

    exceptionStatsHandler

    function to record failure details.

  21. def expHostConnectionBufferSize(size: Int): This

    Permalink

    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.

    Note

    This will be integrated into the mainline pool, at which time the experimental option will go away.

  22. def failFast(enabled: Boolean): This

    Permalink

    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.

  23. def failureAccrualFactory(factory: (Timer) ⇒ ServiceFactoryWrapper): This

    Permalink

    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.

  24. def failureAccrualParams(pair: (Int, Duration)): This

    Permalink

    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.

  25. def finalize(): Unit

    Permalink
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  26. final def getClass(): Class[_]

    Permalink
    Definition Classes
    AnyRef → Any
  27. def group(group: Group[SocketAddress]): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink
  28. def hashCode(): Int

    Permalink
    Definition Classes
    AnyRef → Any
  29. def hostConnectionCoresize(value: Int): This

    Permalink

    The core size of the connection pool: the pool is not shrinked below this limit.

  30. def hostConnectionIdleTime(timeout: Duration): This

    Permalink

    The amount of time a connection is allowed to linger (when it otherwise would have been closed by the pool) before being closed.

  31. def hostConnectionLimit(value: Int): ClientBuilder[Req, Rep, HasCluster, HasCodec, Yes]

    Permalink

    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.

  32. def hostConnectionMaxIdleTime(timeout: Duration): This

    Permalink

    The maximum time a connection is allowed to linger unused.

  33. def hostConnectionMaxLifeTime(timeout: Duration): This

    Permalink

    The maximum time a connection is allowed to exist, regardless of occupancy.

  34. def hostConnectionMaxWaiters(nWaiters: Int): This

    Permalink

    The maximum queue size for the connection pool.

  35. def hosts(address: SocketAddress): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink

    A convenience method for specifying a one-host java.net.SocketAddress client.

  36. def hosts(addrs: Seq[SocketAddress]): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink

    A variant of {{hosts}} that takes a sequence of java.net.SocketAddress instead.

  37. def hosts(hostnamePortCombinations: String): ClientBuilder[Req, Rep, Yes, HasCodec, HasHostConnectionLimit]

    Permalink

    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.

    hostnamePortCombinations

    comma-separated "host:port" string.

  38. def httpProxy(httpProxy: SocketAddress): This

    Permalink

    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.

  39. def httpProxyUsernameAndPassword(credentials: Credentials): This

    Permalink

    For the http proxy use these Credentials for authentication.

  40. final def isInstanceOf[T0]: Boolean

    Permalink
    Definition Classes
    Any
  41. def keepAlive(value: Boolean): This

    Permalink

    Apply TCP keepAlive (SO_KEEPALIVE socket option).

  42. def loadBalancer(loadBalancer: LoadBalancerFactory): This

    Permalink

    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

  43. def logger(logger: Logger): This

    Permalink

    Log very detailed debug information to the given logger.

  44. def monitor(mFactory: (String) ⇒ Monitor): This

    Permalink
  45. def name(value: String): This

    Permalink

    Give a meaningful name to the client.

    Give a meaningful name to the client. Required.

  46. final def ne(arg0: AnyRef): Boolean

    Permalink
    Definition Classes
    AnyRef
  47. def noFailureAccrual: This

    Permalink

    Disables FailureAccrualFactory.

    Disables FailureAccrualFactory.

    To replace the FailureAccrualFactory use failureAccrualFactory.

  48. final def notify(): Unit

    Permalink
    Definition Classes
    AnyRef
  49. final def notifyAll(): Unit

    Permalink
    Definition Classes
    AnyRef
  50. def params: Params

    Permalink
  51. def readerIdleTimeout(duration: Duration): This

    Permalink

    The maximum time a connection may have received no data.

  52. def recvBufferSize(value: Int): This

    Permalink

    Sets the TCP recv buffer size.

  53. def reportHostStats(receiver: StatsReceiver): This

    Permalink

    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

  54. def reportTo(receiver: StatsReceiver): This

    Permalink

    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.

    Note

    Per hosts statistics will NOT be exported to this receiver

    See also

    ClientBuilder.reportHostStats

  55. def requestTimeout(duration: Duration): This

    Permalink

    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.

  56. def responseClassifier: ResponseClassifier

    Permalink

    The currently configured com.twitter.finagle.service.ResponseClassifier.

    Note

    If unspecified, the default classifier is com.twitter.finagle.service.ResponseClassifier.Default.

  57. def responseClassifier(classifier: ResponseClassifier): This

    Permalink

    Configure a com.twitter.finagle.service.ResponseClassifier which is used to determine the result of a request/response.

    Configure a com.twitter.finagle.service.ResponseClassifier which is used to determine the result of a request/response.

    This allows developers to give Finagle the additional application-specific knowledge necessary in order to properly classify them. Without this, Finagle cannot make judgements about application level failures as it only has a narrow understanding of failures (for example: transport level, timeouts, and nacks).

    As an example take an HTTP client that receives a response with a 500 status code back from a server. To Finagle this is a successful request/response based solely on the transport level. The application developer may want to treat all 500 status codes as failures and can do so via a com.twitter.finagle.service.ResponseClassifier.

    It is a PartialFunction and as such multiple classifiers can be composed together via PartialFunction.orElse.

    Note

    If unspecified, the default classifier is com.twitter.finagle.service.ResponseClassifier.Default which is a total function fully covering the input domain.

    See also

    com.twitter.finagle.http.service.HttpResponseClassifier for some HTTP classification tools.

  58. def retries(value: Int): This

    Permalink

    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 configured policy has jittered backoffs between retries.

    value

    the maximum number of attempts (including retries) that can be made.

    • A value of 1 means one attempt and no retries on failure.
    • A value of 2 means one attempt and then a single retry if the failure is known to be safe to retry.
    Note

    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()).

    See also

    retryBudget for governing how many failed requests are eligible for retries.

    com.twitter.finagle.service.RetryPolicy.tries

  59. def retryBudget(budget: RetryBudget, backoffSchedule: Stream[Duration]): This

    Permalink

    The budget is shared across requests and governs the number of retries that can be made.

    The budget is shared across requests and governs the number of retries that can be made. When used for requeues, includes a stream of delays used to delay each retry.

    Helps prevent clients from overwhelming the downstream service.

    See also

    retryPolicy for per-request rules on which failures are eligible for retries.

  60. def retryBudget(budget: RetryBudget): This

    Permalink

    The budget is shared across requests and governs the number of retries that can be made.

    The budget is shared across requests and governs the number of retries that can be made.

    Helps prevent clients from overwhelming the downstream service.

    See also

    retryPolicy for per-request rules on which failures are eligible for retries.

  61. def retryPolicy(value: RetryPolicy[Try[Nothing]]): This

    Permalink

    Retry failed requests according to the given RetryPolicy.

    Retry failed requests according to the given RetryPolicy.

    Note

    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()).

    See also

    retryBudget for governing how many failed requests are eligible for retries.

  62. def sendBufferSize(value: Int): This

    Permalink

    Sets the TCP send buffer size.

  63. def socksProxy(socksProxy: Option[SocketAddress]): This

    Permalink

    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.

  64. def socksUsernameAndPassword(credentials: (String, String)): This

    Permalink

    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

  65. def stack[Req1, Rep1](client: StackBasedClient[Req1, Rep1]): ClientBuilder[Req1, Rep1, HasCluster, Yes, Yes]

    Permalink

    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.

    client

    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.

  66. final def synchronized[T0](arg0: ⇒ T0): T0

    Permalink
    Definition Classes
    AnyRef
  67. def tcpConnectTimeout(duration: Duration): This

    Permalink

    Specify the TCP connection timeout.

  68. def timeout(duration: Duration): This

    Permalink

    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())

  69. def tls(sslContext: SSLContext, hostname: Option[String]): This

    Permalink

    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

  70. def tls(sslContext: SSLContext): This

    Permalink

    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

  71. def tls(hostname: String): This

    Permalink

    Encrypt the connection with SSL.

    Encrypt the connection with SSL. Hostname verification will be provided against the given hostname.

  72. def tlsWithoutValidation(): This

    Permalink

    Do not perform TLS validation.

    Do not perform TLS validation. Probably dangerous.

  73. def toString(): String

    Permalink
    Definition Classes
    ClientBuilder → AnyRef → Any
  74. def tracer(t: Tracer): This

    Permalink

    Specifies a tracer that receives trace events.

    Specifies a tracer that receives trace events. See com.twitter.finagle.tracing for details.

  75. def trafficClass(value: Option[Int]): This

    Permalink

    Configures the traffic class.

    Configures the traffic class.

    See also

    Transporter.TrafficClass

  76. def unsafeBuild(): Service[Req, Rep]

    Permalink

    Construct a Service, with runtime checks for builder completeness.

  77. def unsafeBuildFactory(): ServiceFactory[Req, Rep]

    Permalink

    Construct a ServiceFactory, with runtime checks for builder completeness.

  78. final def wait(): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  79. final def wait(arg0: Long, arg1: Int): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  80. final def wait(arg0: Long): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  81. def writerIdleTimeout(duration: Duration): This

    Permalink

    The maximum time a connection may not have sent any data.

Deprecated Value Members

  1. def build(THE_BUILDER_IS_NOT_FULLY_SPECIFIED_SEE_ClientBuilder_DOCUMENTATION: =:=[ThisConfig, FullySpecifiedConfig]): Service[Req, Rep]

    Permalink
    Annotations
    @deprecated
    Deprecated

    (Since version 5.0.1) Used for ABI compat

  2. def buildFactory(THE_BUILDER_IS_NOT_FULLY_SPECIFIED_SEE_ClientBuilder_DOCUMENTATION: =:=[ThisConfig, FullySpecifiedConfig]): ServiceFactory[Req, Rep]

    Permalink
    Annotations
    @deprecated
    Deprecated

    (Since version 5.0.1) Used for ABI compat

  3. def connectionTimeout(duration: Duration): This

    Permalink
    Annotations
    @deprecated
    Deprecated

    (Since version 5.0.1) Use tcpConnectTimeout instead

  4. def expFailFast(enabled: Boolean): This

    Permalink
    Annotations
    @deprecated
    Deprecated

    (Since version 5.3.10)

  5. def socksProxy(socksProxy: SocketAddress): This

    Permalink
    Annotations
    @deprecated
    Deprecated

    (Since version 2014-12-02) Use socksProxy(socksProxy: Option[SocketAddress])

  6. def tracerFactory(t: Tracer): This

    Permalink
    Annotations
    @deprecated
    Deprecated

    (Since version 7.0.0) Use tracer() instead

  7. def tracerFactory(factory: Factory): This

    Permalink

    Specifies a tracer that receives trace events.

    Specifies a tracer that receives trace events. See com.twitter.finagle.tracing for details.

    Annotations
    @deprecated
    Deprecated

    (Since version 7.0.0) Use tracer() instead

Inherited from AnyRef

Inherited from Any

Ungrouped