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