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