1 /* 2 * Copyright (C) 2012 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; 18 19 /** 20 * A handle to a lazily-computed value. Each {@code Lazy} computes its value on 21 * the first call to {@link #get()} and remembers that same value for all 22 * subsequent calls to {@code get()}. 23 * 24 * <p>All implementations are expected to be thread-safe and compute their value at most once. 25 * 26 * <h2>Example</h2> 27 * The differences between <strong>direct injection</strong>, <strong>provider 28 * injection</strong> and <strong>lazy injection</strong> are best demonstrated 29 * with an example. Start with a module that computes a different integer for 30 * each use:<pre><code> 31 * {@literal @Module} 32 * final class CounterModule { 33 * int next = 100; 34 * 35 * {@literal @Provides} Integer provideInteger() { 36 * System.out.println("computing..."); 37 * return next++; 38 * } 39 * } 40 * </code></pre> 41 * 42 * <h3>Direct Injection</h3> 43 * This class injects that integer and prints it 3 times:<pre><code> 44 * final class DirectCounter { 45 * {@literal @Inject} Integer value; 46 * 47 * void print() { 48 * System.out.println("printing..."); 49 * System.out.println(value); 50 * System.out.println(value); 51 * System.out.println(value); 52 * } 53 * } 54 * </code></pre> 55 * Injecting a {@code DirectCounter} and invoking {@code print()} reveals that 56 * the value is computed <i>before</i> it is required:<pre><code> 57 * computing... 58 * printing... 59 * 100 60 * 100 61 * 100 62 * </code></pre> 63 * 64 * <h3>Provider Injection</h3> 65 * This class injects a {@linkplain javax.inject.Provider provider} for the 66 * integer. It calls {@code Provider.get()} 3 times and prints each result: 67 * <pre><code> 68 * final class ProviderCounter { 69 * {@literal @Inject Provider<Integer> provider;} 70 * 71 * void print() { 72 * System.out.println("printing..."); 73 * System.out.println(provider.get()); 74 * System.out.println(provider.get()); 75 * System.out.println(provider.get()); 76 * } 77 * } 78 * </code></pre> 79 * Injecting a {@code ProviderCounter} and invoking {@code print()} shows that 80 * a new value is computed each time {@code Provider.get()} is used:<pre><code> 81 * printing... 82 * computing... 83 * 100 84 * computing... 85 * 101 86 * computing... 87 * 102 88 * </code></pre> 89 * 90 * <h3>Lazy Injection</h3> 91 * This class injects a {@code Lazy} for the integer. Like the provider above, 92 * it calls {@code Lazy.get()} 3 times and prints each result:<pre><code> 93 * final class LazyCounter { 94 * {@literal @Inject Lazy<Integer> lazy;} 95 * 96 * void print() { 97 * System.out.println("printing..."); 98 * System.out.println(lazy.get()); 99 * System.out.println(lazy.get()); 100 * System.out.println(lazy.get()); 101 * } 102 * } 103 * </code></pre> 104 * Injecting a {@code LazyCounter} and invoking {@code print()} shows that a new 105 * value is computed immediately before it is needed. The same value is returned 106 * for all subsequent uses:<pre><code> 107 * printing... 108 * computing... 109 * 100 110 * 100 111 * 100 112 * </code></pre> 113 * 114 * <h3>Lazy != Singleton</h3> 115 * Note that each injected {@code Lazy} is independent, and remembers its value 116 * in isolation of other {@code Lazy} instances. In this example, two {@code 117 * LazyCounter} objects are created and {@code print()} is called on each: 118 * <pre><code> 119 * final class LazyCounters { 120 * {@literal @Inject} LazyCounter counter1; 121 * {@literal @Inject} LazyCounter counter2; 122 * 123 * void print() { 124 * counter1.print(); 125 * counter2.print(); 126 * } 127 * } 128 * </code></pre> 129 * The output demonstrates that each {@code Lazy} works independently: 130 * <pre><code> 131 * printing... 132 * computing... 133 * 100 134 * 100 135 * 100 136 * printing... 137 * computing... 138 * 101 139 * 101 140 * 101 141 * </code></pre> 142 * Use {@link javax.inject.Singleton @Singleton} to share one instance among all 143 * clients, and {@code Lazy} for lazy computation in a single client. 144 */ 145 public interface Lazy<T> { 146 /** 147 * Return the underlying value, computing the value if necessary. All calls to 148 * the same {@code Lazy} instance will return the same result. 149 */ get()150 T get(); 151 } 152