• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2014 The Dagger Authors.
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 
17 package dagger.producers;
18 
19 import static java.lang.annotation.ElementType.TYPE;
20 import static java.lang.annotation.RetentionPolicy.RUNTIME;
21 
22 import com.google.common.util.concurrent.ListenableFuture;
23 import dagger.Component;
24 import dagger.Module;
25 import dagger.Provides;
26 import dagger.internal.Beta;
27 import java.lang.annotation.Documented;
28 import java.lang.annotation.Retention;
29 import java.lang.annotation.Target;
30 import javax.inject.Inject;
31 import javax.inject.Qualifier;
32 
33 /**
34  * Annotates an interface or abstract class for which a fully-formed, dependency-injected
35  * implementation is to be generated from a set of {@linkplain #modules modules}. The generated
36  * class will have the name of the type annotated with {@code @ProductionComponent} prepended with
37  * {@code Dagger}. For example, {@code @ProductionComponent interface MyComponent {...}} will
38  * produce an implementation named {@code DaggerMyComponent}.
39  *
40  * <p>Each {@link Produces} method that contributes to the component will be called at most once per
41  * component instance, no matter how many times that binding is used as a dependency. TODO(beder):
42  * Decide on how scope works for producers.
43  *
44  * <h2>Component methods</h2>
45  *
46  * <p>Every type annotated with {@code @ProductionComponent} must contain at least one abstract
47  * component method. Component methods must represent {@linkplain Producer production}.
48  *
49  * <p>Production methods have no arguments and return either a {@link ListenableFuture} or {@link
50  * Producer} of a type that is {@link Inject injected}, {@link Provides provided}, or {@link
51  * Produces produced}. Each may have a {@link Qualifier} annotation as well. The following are all
52  * valid production method declarations:
53  *
54  * <pre><code>
55  *   {@literal ListenableFuture<SomeType>} getSomeType();
56  *   {@literal Producer<Set<SomeType>>} getSomeTypes();
57  *   {@literal @Response ListenableFuture<Html>} getResponse();
58  * </code></pre>
59  *
60  * <h2>Exceptions</h2>
61  *
62  * <p>When a producer throws an exception, the exception will be propagated to its downstream
63  * producers in the following way: if the downstream producer injects a type {@code T}, then that
64  * downstream producer will be skipped, and the exception propagated to its downstream producers;
65  * and if the downstream producer injects a {@code Produced<T>}, then the downstream producer will
66  * be run with the exception stored in the {@code Produced<T>}.
67  *
68  * <p>If a non-execution exception is thrown (e.g., an {@code InterruptedException} or {@code
69  * CancellationException}), then exception is handled as in {@link
70  * com.google.common.util.concurrent.Futures#transform}.
71  * <!-- TODO(beder): Explain this more thoroughly, and update the javadocs of those utilities. -->
72  *
73  * <h2>Executor</h2>
74  *
75  * <p>The component must include a binding for <code>{@literal @}{@link Production}
76  * {@link java.util.concurrent.Executor}</code>; this binding will be called exactly once, and the
77  * provided executor will be used by the framework to schedule all producer methods (for this
78  * component, and any {@link ProductionSubcomponent} it may have.
79  *
80  * @since 2.0
81  */
82 @Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
83 @Documented
84 @Target(TYPE)
85 @Beta
86 public @interface ProductionComponent {
87   /**
88    * A list of classes annotated with {@link Module} or {@link ProducerModule} whose bindings are
89    * used to generate the component implementation.
90    */
modules()91   Class<?>[] modules() default {};
92 
93   /**
94    * A list of types that are to be used as component dependencies.
95    */
dependencies()96   Class<?>[] dependencies() default {};
97 
98   /**
99    * A builder for a production component.
100    *
101    * <p>This follows all the rules of {@link Component.Builder}, except it must appear in classes
102    * annotated with {@link ProductionComponent} instead of {@code Component}.
103    */
104   @Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
105   @Target(TYPE)
106   @Documented
107   @interface Builder {}
108 
109   /**
110    * A factory for a production component.
111    *
112    * <p>This follows all the rules of {@link Component.Factory}, except it must appear in classes
113    * annotated with {@link ProductionComponent} instead of {@code Component}.
114    *
115    * @since 2.22
116    */
117   @Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
118   @Target(TYPE)
119   @Documented
120   @interface Factory {}
121 }
122