1 /*
2  * Copyright (C) 2014 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package dagger.producers;
17 
18 import com.google.common.util.concurrent.ListenableFuture;
19 import dagger.Module;
20 import dagger.Provides;
21 import dagger.internal.Beta;
22 import java.lang.annotation.Documented;
23 import java.lang.annotation.Target;
24 import javax.inject.Inject;
25 import javax.inject.Qualifier;
26 
27 import static java.lang.annotation.ElementType.TYPE;
28 
29 /**
30  * Annotates an interface or abstract class for which a fully-formed, dependency-injected
31  * implementation is to be generated from a set of {@linkplain #modules}. The generated class will
32  * have the name of the type annotated with {@code @ProductionComponent} prepended with
33  * {@code Dagger}.  For example, {@code @ProductionComponent interface MyComponent {...}} will
34  * produce an implementation named {@code DaggerMyComponent}.
35  *
36  * <p>Each {@link Produces} method that contributes to the component will be called at most once per
37  * component instance, no matter how many times that binding is used as a dependency.
38  * TODO(user): Decide on how scope works for producers.
39  *
40  * <h2>Component methods</h2>
41  *
42  * <p>Every type annotated with {@code @ProductionComponent} must contain at least one abstract
43  * component method. Component methods must represent {@linkplain Producer production}.
44  *
45  * Production methods have no arguments and return either a {@link ListenableFuture} or
46  * {@link Producer} of a type that is {@link Inject injected}, {@link Provides provided}, or
47  * {@link Produces produced}. Each may have a {@link Qualifier} annotation as well. The following
48  * are all valid production method declarations: <pre><code>
49  *   ListenableFuture<SomeType> getSomeType();
50  *   {@literal Producer<Set<SomeType>>} getSomeTypes();
51  *   {@literal @Response ListenableFuture<Html>} getResponse();
52  * </code></pre>
53  *
54  * <h2>Exceptions</h2>
55  *
56  * <p>When a producer throws an exception, the exception will be propagated to its downstream
57  * producers in the following way: if the downstream producer injects a type {@code T}, then that
58  * downstream producer will be skipped, and the exception propagated to its downstream producers;
59  * and if the downstream producer injects a {@code Produced<T>}, then the downstream producer will
60  * be run with the exception stored in the {@code Produced<T>}.
61  *
62  * <p>If a non-execution exception is thrown (e.g., an {@code InterruptedException} or
63  * {@code CancellationException}), then exception is handled as in
64  * {@link com.google.common.util.concurrent.Futures#transform}.
65  * <!-- TODO(beder): Explain this more thoroughly, and update the javadocs of those utilities. -->
66  *
67  * @author Jesse Beder
68  */
69 @Documented
70 @Target(TYPE)
71 @Beta
72 public @interface ProductionComponent {
73   /**
74    * A list of classes annotated with {@link Module} or {@link ProducerModule} whose bindings are
75    * used to generate the component implementation.
76    */
modules()77   Class<?>[] modules() default {};
78 
79   /**
80    * A list of types that are to be used as component dependencies.
81    */
dependencies()82   Class<?>[] dependencies() default {};
83 
84   /**
85    * A builder for a component. Components may have a single nested static abstract class or
86    * interface annotated with {@code @ProductionComponent.Builder}. If they do, then the component's
87    * generated builder will match the API in the type.  Builders must follow some rules:
88    * <ul>
89    * <li> A single abstract method with no arguments must exist, and must return the component.
90    *      (This is typically the {@code build()} method.)
91    * <li> All other abstract methods must take a single argument and must return void,
92    *      the builder type, or a supertype of the builder.
93    * <li> There <b>must</b> be an abstract method whose parameter is
94    *      {@link java.util.concurrent.Executor}.
95    * <li> Each component dependency <b>must</b> have an abstract setter method.
96    * <li> Each module dependency that Dagger can't instantiate itself (i.e., the module
97    *      doesn't have a visible no-args constructor) <b>must</b> have an abstract setter method.
98    *      Other module dependencies (ones that Dagger can instantiate) are allowed, but not
99    *      required.
100    * <li> Non-abstract methods are allowed, but ignored as far as validation and builder generation
101    *      are concerned.
102    * </ul>
103    *
104    * For example, this could be a valid {@code ProductionComponent} with a builder: <pre><code>
105    * {@literal @}ProductionComponent(modules = {BackendModule.class, FrontendModule.class})
106    * interface MyComponent {
107    *   {@literal ListenableFuture<MyWidget>} myWidget();
108    *
109    *   {@literal @}ProductionComponent.Builder
110    *   interface Builder {
111    *     MyComponent build();
112    *     Builder executor(Executor executor);
113    *     Builder backendModule(BackendModule bm);
114    *     Builder frontendModule(FrontendModule fm);
115    *   }
116    * }</code></pre>
117    */
118   @Target(TYPE)
119   @Documented
120   @interface Builder {}
121 }
122