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 dagger.internal.Beta; 19 import com.google.common.util.concurrent.ListenableFuture; 20 21 /** 22 * An interface that represents the production of a type {@code T}. You can also inject 23 * {@code Producer<T>} instead of {@code T}, which will delay the execution of any code that 24 * produces the {@code T} until {@link #get} is called. 25 * 26 * <p>For example, you might inject {@code Producer} to lazily choose between several different 27 * implementations of some type: <pre><code> 28 * {@literal @Produces ListenableFuture<Heater>} getHeater( 29 * HeaterFlag flag, 30 * {@literal @Electric Producer<Heater>} electricHeater, 31 * {@literal @Gas Producer<Heater>} gasHeater) { 32 * return flag.useElectricHeater() ? electricHeater.get() : gasHeater.get(); 33 * } 34 * </code></pre> 35 * 36 * <p>Here is a complete example that demonstrates how calling {@code get()} will cause each 37 * method to be executed: <pre><code> 38 * 39 * {@literal @}ProducerModule 40 * final class MyModule { 41 * {@literal @Produces ListenableFuture<A>} a() { 42 * System.out.println("a"); 43 * return Futures.immediateFuture(new A()); 44 * } 45 * 46 * {@literal @Produces ListenableFuture<B>} b(A a) { 47 * System.out.println("b"); 48 * return Futures.immediateFuture(new B(a)); 49 * } 50 * 51 * {@literal @Produces ListenableFuture<C>} c(B b) { 52 * System.out.println("c"); 53 * return Futures.immediateFuture(new C(b)); 54 * } 55 * 56 * {@literal @Produces @Delayed ListenableFuture<C>} delayedC(A a, {@literal Producer<C>} c) { 57 * System.out.println("delayed c"); 58 * return c.get(); 59 * } 60 * } 61 * 62 * {@literal @}ProductionComponent(modules = MyModule.class) 63 * interface MyComponent { 64 * {@literal @Delayed ListenableFuture<C>} delayedC(); 65 * } 66 * </code></pre> 67 * Suppose we instantiate the generated implementation of this component and call 68 * {@code delayedC()}: <pre><code> 69 * MyComponent component = DaggerMyComponent 70 * .builder() 71 * .executor(MoreExecutors.directExecutor()) 72 * .build(); 73 * System.out.println("Constructed component"); 74 * {@literal ListenableFuture<C>} cFuture = component.delayedC(); 75 * System.out.println("Retrieved future"); 76 * C c = cFuture.get(); 77 * System.out.println("Retrieved c"); 78 * </code></pre> 79 * Here, we're using {@code MoreExecutors.directExecutor} in order to illustrate how each call 80 * directly causes code to execute. The above code will print: <pre><code> 81 * Constructed component 82 * a 83 * delayed c 84 * b 85 * c 86 * Retrieved future 87 * Retrieved c 88 * </code></pre> 89 * 90 * @author Jesse Beder 91 */ 92 @Beta 93 public interface Producer<T> { 94 /** 95 * Returns a future representing a running task that produces a value. Calling this method will 96 * trigger the submission of this task to the executor, if it has not already been triggered. In 97 * order to trigger this task's submission, the transitive dependencies required to produce the 98 * {@code T} will be submitted to the executor, as their dependencies become available. 99 * 100 * <p>If the key is bound to a {@link Produces} method, then calling this method multiple times 101 * will return the same future. 102 */ 103 ListenableFuture<T> get(); 104 } 105
