1 /* 2 * Copyright (C) 2012 Google, Inc. 3 * Copyright (C) 2012 Square, Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 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 {@code get()} and remembers that same value for all 22 * subsequent calls to {@code get()}. 23 * 24 * <p>{@code null} is not a supported value. Implementations of {@code Lazy} 25 * are expected to throw {@link NullPointerException} if the computed value is 26 * {@code null}. 27 * 28 * <h2>Example</h2> 29 * The differences between <strong>direct injection</strong>, <strong>provider 30 * injection</strong> and <strong>lazy injection</strong> are best demonstrated 31 * with an example. Start with a module that computes a different integer for 32 * each use:<pre><code> 33 * {@literal @Module} 34 * final class CounterModule { 35 * int next = 100; 36 * 37 * {@literal @Provides} Integer provideInteger() { 38 * System.out.println("computing..."); 39 * return next++; 40 * } 41 * } 42 * </code></pre> 43 * 44 * <h3>Direct Injection</h3> 45 * This class injects that integer and prints it 3 times:<pre><code> 46 * final class DirectCounter { 47 * {@literal @Inject} Integer value; 48 * 49 * void print() { 50 * System.out.println("printing..."); 51 * System.out.println(value); 52 * System.out.println(value); 53 * System.out.println(value); 54 * } 55 * } 56 * </code></pre> 57 * Injecting a {@code DirectCounter} and invoking {@code print()} reveals that 58 * the value is computed <i>before</i> it is required:<pre><code> 59 * computing... 60 * printing... 61 * 100 62 * 100 63 * 100 64 * </code></pre> 65 * 66 * <h3>Provider Injection</h3> 67 * This class injects a {@linkplain javax.inject.Provider provider} for the 68 * integer. It calls {@code Provider.get()} 3 times and prints each result: 69 * <pre><code> 70 * final class ProviderCounter { 71 * {@literal @Inject Provider<Integer> provider;} 72 * 73 * void print() { 74 * System.out.println("printing..."); 75 * System.out.println(provider.get()); 76 * System.out.println(provider.get()); 77 * System.out.println(provider.get()); 78 * } 79 * } 80 * </code></pre> 81 * Injecting a {@code ProviderCounter} and invoking {@code print()} shows that 82 * a new value is computed each time {@code Provider.get()} is used:<pre><code> 83 * printing... 84 * computing... 85 * 100 86 * computing... 87 * 101 88 * computing... 89 * 102 90 * </code></pre> 91 * 92 * <h3>Lazy Injection</h3> 93 * This class injects a {@code Lazy} for the integer. Like the provider above, 94 * it calls {@code Lazy.get()} 3 times and prints each result:<pre><code> 95 * final class LazyCounter { 96 * {@literal @Inject Lazy<Integer> lazy;} 97 * 98 * void print() { 99 * System.out.println("printing..."); 100 * System.out.println(lazy.get()); 101 * System.out.println(lazy.get()); 102 * System.out.println(lazy.get()); 103 * } 104 * } 105 * </code></pre> 106 * Injecting a {@code LazyCounter} and invoking {@code print()} shows that a new 107 * value is computed immediately before it is needed. The same value is returned 108 * for all subsequent uses:<pre><code> 109 * printing... 110 * computing... 111 * 100 112 * 100 113 * 100 114 * </code></pre> 115 * 116 * <h3>Lazy != Singleton</h3> 117 * Note that each injected {@code Lazy} is independent, and remembers its value 118 * in isolation of other {@code Lazy} instances. In this example, two {@code 119 * LazyCounter} objects are created and {@code print()} is called on each: 120 * <pre><code> 121 * final class LazyCounters { 122 * {@literal @Inject} LazyCounter counter1; 123 * {@literal @Inject} LazyCounter counter2; 124 * 125 * void print() { 126 * counter1.print(); 127 * counter2.print(); 128 * } 129 * } 130 * </code></pre> 131 * The output demonstrates that each {@code Lazy} works independently: 132 * <pre><code> 133 * printing... 134 * computing... 135 * 100 136 * 100 137 * 100 138 * printing... 139 * computing... 140 * 101 141 * 101 142 * 101 143 * </code></pre> 144 * Use {@link javax.inject.Singleton @Singleton} to share one instance among all 145 * clients, and {@code Lazy} for lazy computation in a single client. 146 */ 147 public interface Lazy<T> { 148 /** 149 * Return the underlying value, computing the value if necessary. All calls to 150 * the same {@code Lazy} instance will return the same result. 151 * 152 * @throws NullPointerException if the computed value is {@code null}. 153 */ get()154 T get(); 155 } 156