Every type annotated with {@code @Component} must contain at least one abstract component
* method. Component methods may have any name, but must have signatures that conform to either
* {@linkplain Provider provision} or {@linkplain MembersInjector members-injection} contracts.
*
*
* Provision methods
*
*
*
Provision methods have no parameters and return an {@link Inject injected} or * {@link Provides provided} type. Each method may have a {@link Qualifier} annotation as well. The * following are all valid provision method declarations:
* SomeType getSomeType();
* {@literal Set} getSomeTypes();
* {@literal @PortNumber} int getPortNumber();
* Provision methods, like typical {@link Inject injection} sites, may use {@link Provider} or * {@link Lazy} to more explicitly control provision requests. A {@link Provider} allows the user * of the component to request provision any number of times by calling {@link Provider#get}. A * {@link Lazy} will only ever request a single provision, but will defer it until the first call to * {@link Lazy#get}. The following provision methods all request provision of the same type, but * each implies different semantics:
* SomeType getSomeType();
* {@literal Provider} getSomeTypeProvider();
* {@literal Lazy} getLazySomeType();
* Members-injection methods have a single parameter and inject dependencies into each of the * {@link Inject}-annotated fields and methods of the passed instance. A members-injection method * may be void or return its single parameter as a convenience for chaining. The following are all * valid members-injection method declarations:
* void injectSomeType(SomeType someType);
* SomeType injectAndReturnSomeType(SomeType someType);
* A method with no parameters that returns a {@link MembersInjector} is equivalent to a members * injection method. Calling {@link MembersInjector#injectMembers} on the returned object will * perform the same work as a members injection method. For example:
* {@literal MembersInjector} getSomeTypeMembersInjector();
* While a members-injection method for a type will accept instances of its subtypes, only * {@link Inject}-annotated members of the parameter type and its supertypes will be injected; * members of subtypes will not. For example, given the following types, only {@code a} and * {@code b} will be injected into an instance of {@code Child} when it is passed to the * members-injection method {@code injectSelf(Self instance)}:
* class Parent {
* {@literal @}Inject A a;
* }
*
* class Self extends Parent {
* {@literal @}Inject B b;
* }
*
* class Child extends Self {
* {@literal @}Inject C c;
* }
* Component implementations are primarily instantiated via a generated * builder. An instance of the builder * is obtained using the {@code builder()} method on the component implementation. * If a nested {@code @Component.Builder} type exists in the component, the {@code builder()} * method will return a generated implementation of that type. If no nested * {@code @Component.Builder} exists, the returned builder has a method to set each of the * {@linkplain #modules} and component {@linkplain #dependencies} named with the * lower camel case version of the module * or dependency type. Each component dependency and module without a visible default constructor * must be set explicitly, but any module with a default or no-args constructor accessible to the * component implementation may be elided. This is an example usage of a component builder: *
* public static void main(String[] args) {
* OtherComponent otherComponent = ...;
* MyComponent component = DaggerMyComponent.builder()
* // required because component dependencies must be set
* .otherComponent(otherComponent)
* // required because FlagsModule has constructor parameters
* .flagsModule(new FlagsModule(args))
* // may be elided because a no-args constructor is visible
* .myApplicationModule(new MyApplicationModule())
* .build();
* }
* In the case that a component has no component dependencies and only no-arg modules, the
* generated component will also have a factory method {@code create()}.
* {@code SomeComponent.create()} and {@code SomeComponent.builder().build()} are both valid and
* equivalent.
*
*
* Scope
*
*
*
Each Dagger component can be associated with a scope by annotating it with the * {@linkplain Scope scope annotation}. The component implementation ensures that there is only one * provision of each scoped binding per instance of the component. If the component declares a * scope, it may only contain unscoped bindings or bindings of that scope anywhere in the graph. For * example:
* {@literal @}Singleton {@literal @}Component
* interface MyApplicationComponent {
* // this component can only inject types using unscoped or {@literal @}Singleton bindings
* }
* In order to get the proper behavior associated with a scope annotation, it is the caller's
* responsibility to instantiate new component instances when appropriate. A {@link Singleton}
* component, for instance, should only be instantiated once per application, while a
* {@code RequestScoped} component should be instantiated once per request. Because components are
* self-contained implementations, exiting a scope is as simple as dropping all references to the
* component instance.
*
*
* Component relationships
*
*
*
While there is much utility in isolated components with purely unscoped bindings, many
* applications will call for multiple components with multiple scopes to interact. Dagger provides
* two mechanisms for relating components.
*
*
* Subcomponents
*
*
*
The simplest way to relate two components is by declaring a {@link Subcomponent}. A * subcomponent behaves exactly like a component, but has its implementation generated within * a parent component or subcomponent. That relationship allows the subcomponent implementation to * inherit the entire binding graph from its parent when it is declared. For that reason, * a subcomponent isn't evaluated for completeness until it is associated with a parent. * *
Subcomponents are declared via a factory method on a parent component or subcomponent. The * method may have any name, but must return the subcomponent. The factory method's parameters may * be any number of the subcomponent's modules, but must at least include those without visible * no-arg constructors. The following is an example of a factory method that creates a * request-scoped subcomponent from a singleton-scoped parent:
* {@literal @}Singleton {@literal @}Component
* interface ApplicationComponent {
* // component methods...
*
* RequestComponent newRequestComponent(RequestModule requestModule);
* }
* While subcomponents are the simplest way to compose subgraphs of bindings, subcomponents are * tightly coupled with the parents; they may use any binding defined by their ancestor component * and subcomponents. As an alternative, components can use bindings only from another * component interface by declaring a {@linkplain #dependencies component dependency}. When * a type is used as a component dependency, each provision method * on the dependency is bound as a provider. Note that only the bindings exposed as * provision methods are available through component dependencies. * * @author Gregory Kick * @since 2.0 */ @Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger. @Target(TYPE) @Documented public @interface Component { /** * A list of classes annotated with {@link Module} whose bindings are used to generate the * component implementation. Note that through the use of {@link Module#includes} the full set of * modules used to implement the component may include more modules that just those listed here. */ Class[] modules() default {}; /** * A list of types that are to be used as component * dependencies. */ Class[] dependencies() default {}; /** * A builder for a component. Components may have a single nested static abstract class or * interface annotated with {@code @Component.Builder}. If they do, then the component's * generated builder will match the API in the type. Builders must follow some rules: *
* {@literal @}Component(modules = {BackendModule.class, FrontendModule.class})
* interface MyComponent {
* MyWidget myWidget();
*
* {@literal @}Component.Builder
* interface Builder {
* MyComponent build();
* Builder backendModule(BackendModule bm);
* Builder frontendModule(FrontendModule fm);
* }
* }