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