com.twitter.common.thrift
Class Thrift<T>

java.lang.Object
  extended by com.twitter.common.thrift.Thrift<T>

public class Thrift<T>
extends Object

A generic thrift client that handles reconnection in the case of protocol errors, automatic retries, call deadlines and call statistics tracking. This class aims for behavior compatible with the generic ruby thrift client.

In order to enforce call deadlines for synchronous clients, this class uses an ExecutorService. If a custom executor is supplied, it should throw a subclass of RejectedExecutionException to signal thread resource exhaustion, in which case the client will fail fast and propagate the event as a TResourceExhaustedException. TODO(William Farner): Before open sourcing, look into changing the current model of wrapped proxies to use a single proxy and wrapped functions for decorators.


Nested Class Summary
 class Thrift.ClientBuilder
          A builder class that allows modifications of call behavior to be made for a given Thrift client.
 
Field Summary
static Config DEFAULT_ASYNC_CONFIG
          The default thrift call configuration used for an async client if none is specified.
static Config DEFAULT_CONFIG
          The default thrift call configuration used if none is specified.
 
Constructor Summary
Thrift(Config config, ExecutorService executorService, ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool, RequestTracker<InetSocketAddress> requestTracker, String serviceName, Class<T> serviceInterface, Function<org.apache.thrift.transport.TTransport,T> clientFactory, boolean async, boolean ssl)
          Constructs a new Thrift factory for creating clients that make calls to a particular thrift service.
Thrift(Config config, ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool, RequestTracker<InetSocketAddress> requestTracker, String serviceName, Class<T> serviceInterface, Function<org.apache.thrift.transport.TTransport,T> clientFactory, boolean async, boolean ssl)
          Constructs an instance with a cached thread pool ExecutorService.
Thrift(ExecutorService executorService, ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool, RequestTracker<InetSocketAddress> requestTracker, String serviceName, Class<T> serviceInterface, Function<org.apache.thrift.transport.TTransport,T> clientFactory, boolean async, boolean ssl)
          Constructs an instance with the DEFAULT_CONFIG.
Thrift(ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool, RequestTracker<InetSocketAddress> requestTracker, String serviceName, Class<T> serviceInterface, Function<org.apache.thrift.transport.TTransport,T> clientFactory)
          Constructs an instance with the DEFAULT_CONFIG, cached thread pool ExecutorService, and synchronous calls.
Thrift(ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool, RequestTracker<InetSocketAddress> requestTracker, String serviceName, Class<T> serviceInterface, Function<org.apache.thrift.transport.TTransport,T> clientFactory, boolean async)
          Constructs an instance with the DEFAULT_CONFIG and cached thread pool ExecutorService.
Thrift(ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool, RequestTracker<InetSocketAddress> requestTracker, String serviceName, Class<T> serviceInterface, Function<org.apache.thrift.transport.TTransport,T> clientFactory, boolean async, boolean ssl)
          Constructs an instance with the DEFAULT_CONFIG and cached thread pool ExecutorService.
 
Method Summary
 Thrift.ClientBuilder builder()
          Creates a new thrift client builder that inherits this Thrift instance's default configuration.
 Thrift.ClientBuilder builder(Config config)
          Creates a new thrift client builder that inherits the given configuration.
 void close()
          Closes any open connections and prepares this thrift client for graceful shutdown.
 T create()
          Creates a new client using the default configuration specified for this Thrift instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_CONFIG

public static final Config DEFAULT_CONFIG
The default thrift call configuration used if none is specified. Specifies the following settings:


DEFAULT_ASYNC_CONFIG

public static final Config DEFAULT_ASYNC_CONFIG
The default thrift call configuration used for an async client if none is specified. Specifies the following settings:

Constructor Detail

Thrift

public Thrift(ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool,
              RequestTracker<InetSocketAddress> requestTracker,
              String serviceName,
              Class<T> serviceInterface,
              Function<org.apache.thrift.transport.TTransport,T> clientFactory)
Constructs an instance with the DEFAULT_CONFIG, cached thread pool ExecutorService, and synchronous calls.

See Also:
Thrift(Config, ExecutorService, ObjectPool, RequestTracker , String, Class, Function, boolean, boolean)

Thrift

public Thrift(ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool,
              RequestTracker<InetSocketAddress> requestTracker,
              String serviceName,
              Class<T> serviceInterface,
              Function<org.apache.thrift.transport.TTransport,T> clientFactory,
              boolean async)
Constructs an instance with the DEFAULT_CONFIG and cached thread pool ExecutorService.

See Also:
Thrift(Config, ExecutorService, ObjectPool, RequestTracker , String, Class, Function, boolean, boolean)

Thrift

public Thrift(ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool,
              RequestTracker<InetSocketAddress> requestTracker,
              String serviceName,
              Class<T> serviceInterface,
              Function<org.apache.thrift.transport.TTransport,T> clientFactory,
              boolean async,
              boolean ssl)
Constructs an instance with the DEFAULT_CONFIG and cached thread pool ExecutorService.

See Also:
Thrift(Config, ExecutorService, ObjectPool, RequestTracker , String, Class, Function, boolean, boolean)

Thrift

public Thrift(Config config,
              ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool,
              RequestTracker<InetSocketAddress> requestTracker,
              String serviceName,
              Class<T> serviceInterface,
              Function<org.apache.thrift.transport.TTransport,T> clientFactory,
              boolean async,
              boolean ssl)
Constructs an instance with a cached thread pool ExecutorService.

See Also:
Thrift(Config, ExecutorService, ObjectPool, RequestTracker , String, Class, Function, boolean, boolean)

Thrift

public Thrift(ExecutorService executorService,
              ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool,
              RequestTracker<InetSocketAddress> requestTracker,
              String serviceName,
              Class<T> serviceInterface,
              Function<org.apache.thrift.transport.TTransport,T> clientFactory,
              boolean async,
              boolean ssl)
Constructs an instance with the DEFAULT_CONFIG.

See Also:
Thrift(Config, ExecutorService, ObjectPool, RequestTracker , String, Class, Function, boolean, boolean)

Thrift

public Thrift(Config config,
              ExecutorService executorService,
              ObjectPool<Connection<org.apache.thrift.transport.TTransport,InetSocketAddress>> connectionPool,
              RequestTracker<InetSocketAddress> requestTracker,
              String serviceName,
              Class<T> serviceInterface,
              Function<org.apache.thrift.transport.TTransport,T> clientFactory,
              boolean async,
              boolean ssl)
Constructs a new Thrift factory for creating clients that make calls to a particular thrift service.

Note that the combination of config and connectionPool need to be chosen with care depending on usage of the generated thrift clients. In particular, if configured to not wait for connections, the connectionPool ought to be warmed up with a set of connections or else be actively building connections in the background.

TODO(John Sirois): consider adding an method to ObjectPool that would allow Thrift to handle this case by pro-actively warming the pool.

Parameters:
config - the default configuration to use for all thrift calls; also the configuration all Thrift.ClientBuilders start with
executorService - for invoking calls with a specified deadline
connectionPool - the source for thrift connections
serviceName - a /vars friendly name identifying the service clients will connect to
serviceInterface - the thrift compiler generate interface class for the remote service (Iface)
clientFactory - a function that can generate a concrete thrift client for the given serviceInterface
async - enable asynchronous API
ssl - enable TLS handshaking for Thrift calls
Method Detail

close

public void close()
Closes any open connections and prepares this thrift client for graceful shutdown. Any thrift client proxies returned from create() will become invalid.


builder

public Thrift.ClientBuilder builder()
Creates a new thrift client builder that inherits this Thrift instance's default configuration. This is useful for customizing a client for a particular thrift call that makes sense to treat differently from the rest of the calls to a given service.


builder

public Thrift.ClientBuilder builder(Config config)
Creates a new thrift client builder that inherits the given configuration. This is useful for customizing a client for a particular thrift call that makes sense to treat differently from the rest of the calls to a given service.


create

public T create()
Creates a new client using the default configuration specified for this Thrift instance.