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