15d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin/* 25d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Copyright (C) 2014 Google, Inc. 35d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 45d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Licensed under the Apache License, Version 2.0 (the "License"); 55d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * you may not use this file except in compliance with the License. 65d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * You may obtain a copy of the License at 75d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 85d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * http://www.apache.org/licenses/LICENSE-2.0 95d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 105d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Unless required by applicable law or agreed to in writing, software 115d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * distributed under the License is distributed on an "AS IS" BASIS, 125d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 135d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * See the License for the specific language governing permissions and 145d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * limitations under the License. 155d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin */ 165d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinpackage dagger; 175d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin 185d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport java.lang.annotation.Documented; 195d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport java.lang.annotation.Retention; 205d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport java.lang.annotation.Target; 215d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport javax.inject.Inject; 225d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport javax.inject.Provider; 235d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport javax.inject.Qualifier; 245d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport javax.inject.Scope; 255d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport javax.inject.Singleton; 265d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin 275d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport static java.lang.annotation.ElementType.TYPE; 285d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinimport static java.lang.annotation.RetentionPolicy.RUNTIME; 295d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin 305d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin/** 315d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Annotates an interface or abstract class for which a fully-formed, dependency-injected 325d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * implementation is to be generated from a set of {@linkplain #modules}. The generated class will 335d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * have the name of the type annotated with {@code @Component} prepended with {@code Dagger}. For 345d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * example, {@code @Component interface MyComponent {...}} will produce an implementation named 355d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@code DaggerMyComponent}. 365d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 375d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="component-methods"> 385d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h2>Component methods</h2> 395d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 405d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 415d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Every type annotated with {@code @Component} must contain at least one abstract component 425d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * method. Component methods may have any name, but must have signatures that conform to either 435d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@linkplain Provider provision} or {@linkplain MembersInjector members-injection} contracts. 445d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 455d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="provision-methods"> 465d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h3>Provision methods</h3> 475d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 485d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 495d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Provision methods have no parameters and return an {@link Inject injected} or 505d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@link Provides provided} type. Each method may have a {@link Qualifier} annotation as well. The 515d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * following are all valid provision method declarations: <pre><code> 525d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * SomeType getSomeType(); 535d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal Set<SomeType>} getSomeTypes(); 545d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @PortNumber} int getPortNumber(); 555d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 565d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 575d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Provision methods, like typical {@link Inject injection} sites, may use {@link Provider} or 585d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@link Lazy} to more explicitly control provision requests. A {@link Provider} allows the user 595d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * of the component to request provision any number of times by calling {@link Provider#get}. A 605d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@link Lazy} will only ever request a single provision, but will defer it until the first call to 615d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@link Lazy#get}. The following provision methods all request provision of the same type, but 625d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * each implies different semantics: <pre><code> 635d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * SomeType getSomeType(); 645d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal Provider<SomeType>} getSomeTypeProvider(); 655d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal Lazy<SomeType>} getLazySomeType(); 665d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 675d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 685d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="members-injection-methods"> 695d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h3>Members-injection methods</h3> 705d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 715d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 725d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Members-injection methods have a single parameter and inject dependencies into each of the 735d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@link Inject}-annotated fields and methods of the passed instance. A members-injection method 745d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * may be void or return its single parameter as a convenience for chaining. The following are all 755d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * valid members-injection method declarations: <pre><code> 765d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * void injectSomeType(SomeType someType); 775d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * SomeType injectAndReturnSomeType(SomeType someType); 785d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 795d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 805d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>A method with no parameters that returns a {@link MembersInjector} is equivalent to a members 815d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * injection method. Calling {@link MembersInjector#injectMembers} on the returned object will 825d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * perform the same work as a members injection method. For example: <pre><code> 835d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal MembersInjector<SomeType>} getSomeTypeMembersInjector(); 845d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 855d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 865d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h4>A note about covariance</h4> 875d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 885d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>While a members-injection method for a type will accept instances of its subtypes, only 895d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@link Inject}-annotated members of the parameter type and its supertypes will be injected; 905d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * members of subtypes will not. For example, given the following types, only {@code a} and 915d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@code b} will be injected into an instance of {@code Child} when it is passed to the 925d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * members-injection method {@code injectSelf(Self instance)}: <pre><code> 935d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * class Parent { 945d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Inject A a; 955d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 965d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 975d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * class Self extends Parent { 985d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Inject B b; 995d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 1005d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1015d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * class Child extends Self { 1025d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Inject C c; 1035d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 1045d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 1055d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1065d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="instantiation"> 1075d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h2>Instantiation</h2> 1085d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 1095d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1105d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Component implementations are primarily instantiated via a generated 1115d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a href="http://en.wikipedia.org/wiki/Builder_pattern">builder</a>. An instance of the builder 1125d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * is obtained using the {@code builder()} method on the component implementation. 1135d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * If a nested {@code @Component.Builder} type exists in the component, the {@code builder()} 1145d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * method will return a generated implementation of that type. If no nested 1155d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@code @Component.Builder} exists, the returned builder has a method to set each of the 1165d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@linkplain #modules} and component {@linkplain #dependencies} named with the 1175d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a href="http://en.wikipedia.org/wiki/CamelCase">lower camel case</a> version of the module 1185d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * or dependency type. Each component dependency and module without a visible default constructor 1195d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * must be set explicitly, but any module with a default or no-args constructor accessible to the 1205d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * component implementation may be elided. This is an example usage of a component builder: 1215d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <pre><code> 1225d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * public static void main(String[] args) { 1235d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * OtherComponent otherComponent = ...; 1245d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * MyComponent component = DaggerMyComponent.builder() 1255d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * // required because component dependencies must be set 1265d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * .otherComponent(otherComponent) 1275d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * // required because FlagsModule has constructor parameters 1285d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * .flagsModule(new FlagsModule(args)) 1295d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * // may be elided because a no-args constructor is visible 1305d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * .myApplicationModule(new MyApplicationModule()) 1315d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * .build(); 1325d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 1335d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 1345d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1355d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>In the case that a component has no component dependencies and only no-arg modules, the 1365d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * generated component will also have a factory method {@code create()}. 1375d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@code SomeComponent.create()} and {@code SomeComponent.builder().build()} are both valid and 1385d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * equivalent. 1395d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1405d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="scope"> 1415d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h2>Scope</h2> 1425d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 1435d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1445d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Each Dagger component can be associated with a scope by annotating it with the 1455d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@linkplain Scope scope annotation}. The component implementation ensures that there is only one 1465d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * provision of each scoped binding per instance of the component. If the component declares a 1475d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * scope, it may only contain unscoped bindings or bindings of that scope anywhere in the graph. For 1485d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * example: <pre><code> 1495d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Singleton {@literal @}Component 1505d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * interface MyApplicationComponent { 1515d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * // this component can only inject types using unscoped or {@literal @}Singleton bindings 1525d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 1535d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 1545d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1555d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>In order to get the proper behavior associated with a scope annotation, it is the caller's 1565d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * responsibility to instantiate new component instances when appropriate. A {@link Singleton} 1575d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * component, for instance, should only be instantiated once per application, while a 1585d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@code RequestScoped} component should be instantiated once per request. Because components are 1595d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * self-contained implementations, exiting a scope is as simple as dropping all references to the 1605d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * component instance. 1615d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1625d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="component-relationships"> 1635d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h2>Component relationships</h2> 1645d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 1655d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1665d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>While there is much utility in isolated components with purely unscoped bindings, many 1675d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * applications will call for multiple components with multiple scopes to interact. Dagger provides 1685d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * two mechanisms for relating components. 1695d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1705d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="subcomponents"> 1715d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h3>Subcomponents</h3> 1725d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 1735d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1745d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>The simplest way to relate two components is by declaring a {@link Subcomponent}. A 1755d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * subcomponent behaves exactly like a component, but has its implementation generated within 1765d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * a parent component or subcomponent. That relationship allows the subcomponent implementation to 1775d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * inherit the <em>entire</em> binding graph from its parent when it is declared. For that reason, 1785d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * a subcomponent isn't evaluated for completeness until it is associated with a parent. 1795d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1805d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>Subcomponents are declared via a factory method on a parent component or subcomponent. The 1815d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * method may have any name, but must return the subcomponent. The factory method's parameters may 1825d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * be any number of the subcomponent's modules, but must at least include those without visible 1835d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * no-arg constructors. The following is an example of a factory method that creates a 1845d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * request-scoped subcomponent from a singleton-scoped parent: <pre><code> 1855d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Singleton {@literal @}Component 1865d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * interface ApplicationComponent { 1875d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * // component methods... 1885d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1895d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * RequestComponent newRequestComponent(RequestModule requestModule); 1905d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 1915d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </code></pre> 1925d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1935d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <a name="component-dependencies"> 1945d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <h3>Component dependencies</h3> 1955d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </a> 1965d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 1975d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <p>While subcomponents are the simplest way to compose subgraphs of bindings, subcomponents are 1985d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * tightly coupled with the parents; they may use any binding defined by their ancestor component 1995d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * and subcomponents. As an alternative, components can use bindings only from another 2005d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <em>component interface</em> by declaring a {@linkplain #dependencies component dependency}. When 2015d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * a type is used as a component dependency, each <a href="#provision-methods">provision method</a> 2025d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * on the dependency is bound as a provider. Note that <em>only</em> the bindings exposed as 2035d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * provision methods are available through component dependencies. 2045d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 2055d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * @author Gregory Kick 2065d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * @since 2.0 2075d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin */ 2085d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger. 2095d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin@Target(TYPE) 2105d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin@Documented 2115d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffinpublic @interface Component { 2125d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin /** 2135d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * A list of classes annotated with {@link Module} whose bindings are used to generate the 2145d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * component implementation. Note that through the use of {@link Module#includes} the full set of 2155d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * modules used to implement the component may include more modules that just those listed here. 2165d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin */ 2175d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin Class<?>[] modules() default {}; 2185d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin 2195d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin /** 2205d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * A list of types that are to be used as <a href="#component-dependencies">component 2215d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * dependencies</a>. 2225d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin */ 2235d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin Class<?>[] dependencies() default {}; 2245d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin 2255d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin /** 2265d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * A builder for a component. Components may have a single nested static abstract class or 2275d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * interface annotated with {@code @Component.Builder}. If they do, then the component's 2285d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * generated builder will match the API in the type. Builders must follow some rules: 2295d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <ul> 2305d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <li> A single abstract method with no arguments must exist, and must return the component. 2315d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * (This is typically the {@code build()} method.) 2325d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <li> All other abstract methods must take a single argument and must return void, 2335d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * the Builder type, or a supertype of the builder. 2345d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <li> Each component dependency <b>must</b> have an abstract setter method. 2355d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <li> Each module dependency that Dagger can't instantiate itself (e.g, the module 2365d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * doesn't have a visible no-args constructor) <b>must</b> have an abstract setter method. 2375d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Other module dependencies (ones that Dagger can instantiate) are allowed, but not required. 2385d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * <li> Non-abstract methods are allowed, but ignored as far as validation and builder generation 2395d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * are concerned. 2405d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * </ul> 2415d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 2425d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * For example, this could be a valid Component with a Builder: <pre><code> 2435d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Component(modules = {BackendModule.class, FrontendModule.class}) 2445d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * interface MyComponent { 2455d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * MyWidget myWidget(); 2465d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * 2475d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * {@literal @}Component.Builder 2485d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * interface Builder { 2495d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * MyComponent build(); 2505d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Builder backendModule(BackendModule bm); 2515d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * Builder frontendModule(FrontendModule fm); 2525d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * } 2535d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin * }</code></pre> 2545d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin */ 2555d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin @Target(TYPE) 2565d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin @Documented 2575d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin @interface Builder {} 2585d3207ac2713386ed61c6ca8f0356e8f093a62e1Paul Duffin} 259