Function to determine if the request should be "sampled", e.g. sent to the dark service.

Binds a type converter derived from a Flaggable, making it possible to inject flags of all kinds. The injector will use a provided Flaggable to perform type conversion during an injection.

For example (in Java):

import java.util.List;
import com.google.inject.TypeLiteral;
import com.google.inject.matcher.Matchers;
import com.twitter.app.Flaggable;

addFlagConverter(
  Matchers.only(new TypeLiteral<List<scala.Tuple2<Integer, Integer>>>() {}),
  Flaggable.ofJavaList(Flaggable.ofTuple(Flaggable.ofJavaInteger(), Flaggable.ofJavaInteger())
);

Binds a type converter derived from a Flaggable, making it possible to inject flags of all kinds. The injector will use a provided Flaggable to perform type conversion during an injection.

For example (in Scala):

addFlagConverter[List[(Int, Int)]] // support injecting flags of type List[(Int, Int)]

Binds a type converter. The injector will use the given converter to convert string constants to matching types as needed.

This method should be overridden by implementors IF the ClientType does not extend Closable. This method should wrap an underlying client as a Closable to ensure that resources are dealt with cleanly upon shutdown.

Create a base Finagle Stack Client of type ClientType. This method should not try to do any configuration on the created client.

Provides for installing and building a factory that combines the caller's arguments with injector-supplied values to construct objects. This is preferable to calling install on the TwitterModule which provides the factory as install is not supported for TwitterModule types.

Returns a new com.google.inject.multibindings.Multibinder that collects instances of type T in a scala.collection.immutable.Set that is itself bound with a binding annotation.

An API to bind multiple values separately, only to later inject them as a complete collection. "Multibinding" is intended for use in your application's module:

class SnacksModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindMultiple[Snack].addBinding.toInstance(new Twix())
    bindMultiple[Snack].addBinding.toProvider[SnickersProvider]
    bindMultiple[Snack].addBinding.to[Skittles]
  }
}

With this binding, a Set[Snack] can now be injected:

class SnackMachine @Inject()(Set[Snack] snacks)

Contributing multibindings from different modules is also supported. For example, it is okay for both CandyModule and ChipsModule to create their own Multibinder[Snack], and to each contribute bindings to the set of snacks. When that set is injected, it will contain elements from both modules.

The set's iteration order is consistent with the binding order. This is convenient when multiple elements are contributed by the same module because that module can order its bindings appropriately. Avoid relying on the iteration order of elements contributed by different modules, since there is no equivalent mechanism to order modules.

The set is unmodifiable. Elements can only be added to the set by configuring the multibinder. Elements can never be removed from the set.

Elements are resolved at set injection time. If an element is bound to a provider, that provider's get method will be called each time the set is injected (unless the binding is also scoped).

Annotations can be used to create different sets of the same element type. Each distinct annotation gets its own independent collection of elements.

Elements MUST be distinct. If multiple bound elements have the same value, set injection will fail.

Elements MUST be non-null. If any set element is null, set injection will fail.

Returns a new com.google.inject.multibindings.Multibinder that collects instances of type T in a scala.collection.immutable.Set that is itself bound with a binding annotation A.

An API to bind multiple values separately, only to later inject them as a complete collection. "Multibinding" is intended for use in your application's module:

class SnacksModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindMultiple[Snack].addBinding.toInstance(new Twix())
    bindMultiple[Snack].addBinding.toProvider[SnickersProvider]
    bindMultiple[Snack].addBinding.to[Skittles]
  }
}

With this binding, a Set[Snack] can now be injected:

class SnackMachine @Inject()(Set[Snack] snacks)

Contributing multibindings from different modules is also supported. For example, it is okay for both CandyModule and ChipsModule to create their own Multibinder[Snack], and to each contribute bindings to the set of snacks. When that set is injected, it will contain elements from both modules.

The set's iteration order is consistent with the binding order. This is convenient when multiple elements are contributed by the same module because that module can order its bindings appropriately. Avoid relying on the iteration order of elements contributed by different modules, since there is no equivalent mechanism to order modules.

The set is unmodifiable. Elements can only be added to the set by configuring the multibinder. Elements can never be removed from the set.

Elements are resolved at set injection time. If an element is bound to a provider, that provider's get method will be called each time the set is injected (unless the binding is also scoped).

Annotations can be used to create different sets of the same element type. Each distinct annotation gets its own independent collection of elements.

Elements MUST be distinct. If multiple bound elements have the same value, set injection will fail.

Elements MUST be non-null. If any set element is null, set injection will fail.

Returns a new com.google.inject.multibindings.Multibinder that collects instances of type T in a scala.collection.immutable.Set that is itself bound with no binding annotation.

An API to bind multiple values separately, only to later inject them as a complete collection. "Multibinding" is intended for use in your application's module:

class SnacksModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindMultiple[Snack].addBinding.toInstance(new Twix())
    bindMultiple[Snack].addBinding.toProvider[SnickersProvider]
    bindMultiple[Snack].addBinding.to[Skittles]
  }
}

With this binding, a Set[Snack] can now be injected:

class SnackMachine @Inject()(Set[Snack] snacks)

Contributing multibindings from different modules is also supported. For example, it is okay for both CandyModule and ChipsModule to create their own Multibinder[Snack], and to each contribute bindings to the set of snacks. When that set is injected, it will contain elements from both modules.

The set's iteration order is consistent with the binding order. This is convenient when multiple elements are contributed by the same module because that module can order its bindings appropriately. Avoid relying on the iteration order of elements contributed by different modules, since there is no equivalent mechanism to order modules.

The set is unmodifiable. Elements can only be added to the set by configuring the multibinder. Elements can never be removed from the set.

Elements are resolved at set injection time. If an element is bound to a provider, that provider's get method will be called each time the set is injected (unless the binding is also scoped).

Annotations can be used to create different sets of the same element type. Each distinct annotation gets its own independent collection of elements.

Elements MUST be distinct. If multiple bound elements have the same value, set injection will fail.

Elements MUST be non-null. If any set element is null, set injection will fail.

Returns a new com.google.inject.multibindings.OptionalBinder that binds an instance of T in a scala.Option that is itself bound with a binding annotation.

Calling this method will always supply the bindings: Option[T] and Option[Provider[T]]. If setBinding or setDefault are called, it will also bind T.

setDefault is intended for use by frameworks that need a default value. User code can call setBinding to override the default.

Warning: even if setBinding is called, the default binding will still exist in the object graph. If it is a singleton, it will be instantiated in Stage.PRODUCTION.

If setDefault or setBinding are linked to Providers, the Provider may return null. If it does, the Option bindings will be a None. Binding setBinding to a Provider that returns null will not cause OptionalBinder to fall back to the setDefault binding.

If neither setDefault nor setBinding are called, it will try to link to a user-supplied binding of the same type. If no binding exists, the options will be absent. Otherwise, if a user-supplied binding of that type exists, or if setBinding or setDefault are called, the options will return Some(T) if they are bound to a non-null value, otherwise None.

Values are resolved at injection time. If a value is bound to a provider, that provider's get method will be called each time the option is injected (unless the binding is also scoped, or an option of provider is injected).

Annotations are used to create different options of the same key/value type. Each distinct annotation gets its own independent binding. For example:

class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[Renamer]
  }
}

With this module, an Option[Renamer] can now be injected. With no other bindings, the option will be None. Users can specify bindings in one of two ways:

Option 1:

class UserRenamerModule extends TwitterModule {
  override protected def configure(): Unit = {
    bind[Renamer].to[ReplacingRenamer]
  }
}

or Option 2:

class UserRenamerModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[Renamer].setBinding.to[ReplacingRenamer]
  }
}

With both options, the Option[Renamer] will be present and supply the ReplacingRenamer.

Default values can be supplied using:

 class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setDefault.toInstance(DefaultLookupUrl)
  }
}

With the above module, code can inject an @LookupUrl-annotated String and it will supply the DefaultLookupUrl. A user can change this value by binding:

class UserLookupModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setBinding.toInstance(CustomLookupUrl)
  }
}

which will override the default value.

If one module uses setDefault the only way to override the default is to use setBinding. It is an error for a user to specify the binding without using com.google.inject.multibindings.OptionalBinder if setDefault or setBinding are called. For example:

 class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setDefault.toInstance(DefaultLookupUrl)
  }
}
class UserLookupModule extends TwitterModule {
  override protected def configure(): Unit = {
    bind[String, LookupUrl].toInstance(CustomLookupUrl);
  }
}

would generate an error, because both the framework and the user are trying to bind @LookupUrl String.

Returns a new com.google.inject.multibindings.OptionalBinder that binds an instance of T in a scala.Option that is itself bound with a binding annotation A.

Calling this method will always supply the bindings: Option[T] and Option[Provider[T]]. If setBinding or setDefault are called, it will also bind T.

setDefault is intended for use by frameworks that need a default value. User code can call setBinding to override the default.

Warning: even if setBinding is called, the default binding will still exist in the object graph. If it is a singleton, it will be instantiated in Stage.PRODUCTION.

If setDefault or setBinding are linked to Providers, the Provider may return null. If it does, the Option bindings will be a None. Binding setBinding to a Provider that returns null will not cause OptionalBinder to fall back to the setDefault binding.

If neither setDefault nor setBinding are called, it will try to link to a user-supplied binding of the same type. If no binding exists, the options will be absent. Otherwise, if a user-supplied binding of that type exists, or if setBinding or setDefault are called, the options will return Some(T) if they are bound to a non-null value, otherwise None.

Values are resolved at injection time. If a value is bound to a provider, that provider's get method will be called each time the option is injected (unless the binding is also scoped, or an option of provider is injected).

Annotations are used to create different options of the same key/value type. Each distinct annotation gets its own independent binding. For example:

class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[Renamer]
  }
}

With this module, an Option[Renamer] can now be injected. With no other bindings, the option will be None. Users can specify bindings in one of two ways:

Option 1:

class UserRenamerModule extends TwitterModule {
  override protected def configure(): Unit = {
    bind[Renamer].to[ReplacingRenamer]
  }
}

or Option 2:

class UserRenamerModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[Renamer].setBinding.to[ReplacingRenamer]
  }
}

With both options, the Option[Renamer] will be present and supply the ReplacingRenamer.

Default values can be supplied using:

 class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setDefault.toInstance(DefaultLookupUrl)
  }
}

With the above module, code can inject an @LookupUrl-annotated String and it will supply the DefaultLookupUrl. A user can change this value by binding:

class UserLookupModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setBinding.toInstance(CustomLookupUrl)
  }
}

which will override the default value.

If one module uses setDefault the only way to override the default is to use setBinding. It is an error for a user to specify the binding without using com.google.inject.multibindings.OptionalBinder if setDefault or setBinding are called. For example:

 class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setDefault.toInstance(DefaultLookupUrl)
  }
}
class UserLookupModule extends TwitterModule {
  override protected def configure(): Unit = {
    bind[String, LookupUrl].toInstance(CustomLookupUrl);
  }
}

would generate an error, because both the framework and the user are trying to bind @LookupUrl String.

Returns a new com.google.inject.multibindings.OptionalBinder that binds an instance of T in a scala.Option.

Calling this method will always supply the bindings: Option[T] and Option[Provider[T]]. If setBinding or setDefault are called, it will also bind T.

setDefault is intended for use by frameworks that need a default value. User code can call setBinding to override the default.

Warning: even if setBinding is called, the default binding will still exist in the object graph. If it is a singleton, it will be instantiated in Stage.PRODUCTION.

If setDefault or setBinding are linked to Providers, the Provider may return null. If it does, the Option bindings will be a None. Binding setBinding to a Provider that returns null will not cause OptionalBinder to fall back to the setDefault binding.

If neither setDefault nor setBinding are called, it will try to link to a user-supplied binding of the same type. If no binding exists, the options will be absent. Otherwise, if a user-supplied binding of that type exists, or if setBinding or setDefault are called, the options will return Some(T) if they are bound to a non-null value, otherwise None.

Values are resolved at injection time. If a value is bound to a provider, that provider's get method will be called each time the option is injected (unless the binding is also scoped, or an option of provider is injected).

Annotations are used to create different options of the same key/value type. Each distinct annotation gets its own independent binding. For example:

class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[Renamer]
  }
}

With this module, an Option[Renamer] can now be injected. With no other bindings, the option will be None. Users can specify bindings in one of two ways:

Option 1:

class UserRenamerModule extends TwitterModule {
  override protected def configure(): Unit = {
    bind[Renamer].to[ReplacingRenamer]
  }
}

or Option 2:

class UserRenamerModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[Renamer].setBinding.to[ReplacingRenamer]
  }
}

With both options, the Option[Renamer] will be present and supply the ReplacingRenamer.

Default values can be supplied using:

 class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setDefault.toInstance(DefaultLookupUrl)
  }
}

With the above module, code can inject an @LookupUrl-annotated String and it will supply the DefaultLookupUrl. A user can change this value by binding:

class UserLookupModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setBinding.toInstance(CustomLookupUrl)
  }
}

which will override the default value.

If one module uses setDefault the only way to override the default is to use setBinding. It is an error for a user to specify the binding without using com.google.inject.multibindings.OptionalBinder if setDefault or setBinding are called. For example:

 class FrameworkModule extends TwitterModule {
  override protected def configure(): Unit = {
    bindOption[String, LookupUrl].setDefault.toInstance(DefaultLookupUrl)
  }
}
class UserLookupModule extends TwitterModule {
  override protected def configure(): Unit = {
    bind[String, LookupUrl].toInstance(CustomLookupUrl);
  }
}

would generate an error, because both the framework and the user are trying to bind @LookupUrl String.

Override to supply a custom ClientId, e.g., override protected def clientId(injector: Injector): ClientId = ClientId("myclient") }}}

Name of the flag which captures the value for the Thrift ClientId to pass to the dark service

This method allows for further configuration of the ClientType client for parameters not exposed by this module or for overriding defaults provided herein, e.g.,

override protected def configureClient(client: Example.Client): Example.Client = {
  client
    .withStatsReceiver(someOtherScopedStatsReceiver)
    .withMonitor(myAwesomeMonitor)
    .withTracer(notTheDefaultTracer)
}

This method allows for further configuration of the ThriftMux client for parameters not exposed by this module or for overriding defaults provided herein, e.g.,

override def configureThriftMuxClient(client: ThriftMux.Client): ThriftMux.Client = {
  client
    .withProtocolFactory(myCustomProtocolFactory))
    .withStatsReceiver(someOtherScopedStatsReceiver)
    .withMonitor(myAwesomeMonitor)
    .withTracer(notTheDefaultTracer)
    .withResponseClassifier(ThriftResponseClassifier.ThriftExceptionsAsFailures)
}

A Java-friendly method for creating a named Flag.

A Java-friendly way to create a "mandatory" Flag. "Mandatory" flags MUST have a value provided as an application argument (as they have no default value to be used).

Default amount of time to block in Duration) on a Closable to close that is registered in a closeOnExit block.

Default amount of time to wait for any Closable being registered in a closeOnExit block. Note that this timeout is advisory, as it attempts to give the close function some leeway, for example to drain clients or finish up other tasks.

Destination of Finagle client.

Name of the flag which captures the destination to which to send dark traffic.

This is akin to the c.t.inject.app.App#failfastOnFlagsNotParsed and serves a similar purpose but for new com.twitter.app.Flag instances created in this TwitterModule. The value is 'true' by default. This is to ensure that the value of a com.twitter.app.Flag instance created in this TwitterModule cannot be incorrectly accessed before the application has parsed any passed command line input. This mirrors the framework default for com.twitter.inject.app.App#failfastOnFlagsNotParsed for Flag instances created within the application container.

Create a "mandatory" flag and add it to this Module's flags list."Mandatory" flags MUST have a value provided as an application argument (as they have no default value to be used).

Create a Flag and add it to this Module's flags list.

Forward the dark request after the service has processed the request instead of concurrently.

Additional framework modules to be composed into this module.

Initial configuration of the underlying client. This is exposed to allow for customization of the base client configuration. All user facing extensions should be done via configureClient.

Uses the given com.google.inject.Module to configure more bindings. This is not supported for instances of type TwitterModule and will throw an UnsupportedOperationException if attempted on an instance of TwitterModule. This is to properly support the TwitterModuleLifecycle for TwitterModule instances.

Additional modules to be composed into this module from Java

Name of dark service client for use in metrics.

Additional modules to be composed into this module. This list of modules is generally used instead of the TwitterModule.install method to properly support the TwitterModuleLifecycle for TwitterModule instances.

Function to add a user-defined Monitor. A com.twitter.finagle.util.DefaultMonitor will be installed implicitly which handles all exceptions caught in the stack. Exceptions that are not handled by a user-defined monitor are propagated to the com.twitter.finagle.util.DefaultMonitor.

NullMonitor has no influence on DefaultMonitor behavior here.

This method will generate a fully configured ClientType

This method will generate a Service[Req, Rep] from the configured ClientType generated by calling newClient().

Collects functions over a com.twitter.util.Closables. These functions will be passed to the application onExit function to be executed on graceful shutdown of the application.

Configures a "global" request timeout on the Finagle client (default: unbounded). This will set *all* requests to *every* method to have the same total timeout.

Default com.twitter.finagle.service.RetryBudget. It is highly recommended that budgets be shared between all filters that retry or re-queue requests to prevent retry storms.

Provide a customized base scope for the StatsReceiver exposed by this module, e.g., * *

override protected def scopeStatsReceiver(injector: Injector, statsReceiver: StatsReceiver): StatsReceiver =
 statsReceiver.scope("clnt", "custom_scope")

Configures the session acquisition timeout of this client (default: unbounded).

Invoke after external ports are bound and any clients are resolved

This method should only get singleton instances from the injector.

Invoked on graceful shutdown of the application.

This method should only get singleton instances from the injector.

Invoked after the injector is started.

This method should only get singleton instances from the injector.