forked from google/dagger
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathComponent.java
More file actions
365 lines (358 loc) · 16.5 KB
/
Copy pathComponent.java
File metadata and controls
365 lines (358 loc) · 16.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/*
* Copyright (C) 2014 The Dagger Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package dagger;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import javax.inject.Inject;
import javax.inject.Provider;
import javax.inject.Qualifier;
import javax.inject.Scope;
import javax.inject.Singleton;
/**
* Annotates an interface or abstract class for which a fully-formed, dependency-injected
* implementation is to be generated from a set of {@linkplain #modules}. The generated class will
* have the name of the type annotated with {@code @Component} prepended with {@code Dagger}. For
* example, {@code @Component interface MyComponent {...}} will produce an implementation named
* {@code DaggerMyComponent}.
*
* <a name="component-methods"></a>
* <h2>Component methods</h2>
*
* <p>Every type annotated with {@code @Component} must contain at least one abstract component
* method. Component methods may have any name, but must have signatures that conform to either
* {@linkplain Provider provision} or {@linkplain MembersInjector members-injection} contracts.
*
* <a name="provision-methods"></a>
* <h3>Provision methods</h3>
*
* <p>Provision methods have no parameters and return an {@link Inject injected} or {@link Provides
* provided} type. Each method may have a {@link Qualifier} annotation as well. The following are
* all valid provision method declarations:
*
* <pre><code>
* SomeType getSomeType();
* {@literal Set<SomeType>} getSomeTypes();
* {@literal @PortNumber} int getPortNumber();
* </code></pre>
*
* <p>Provision methods, like typical {@link Inject injection} sites, may use {@link Provider} or
* {@link Lazy} to more explicitly control provision requests. A {@link Provider} allows the user of
* the component to request provision any number of times by calling {@link Provider#get}. A {@link
* Lazy} will only ever request a single provision, but will defer it until the first call to {@link
* Lazy#get}. The following provision methods all request provision of the same type, but each
* implies different semantics:
*
* <pre><code>
* SomeType getSomeType();
* {@literal Provider<SomeType>} getSomeTypeProvider();
* {@literal Lazy<SomeType>} getLazySomeType();
* </code></pre>
*
* <a name="members-injection-methods"></a>
* <h3>Members-injection methods</h3>
*
* <p>Members-injection methods have a single parameter and inject dependencies into each of the
* {@link Inject}-annotated fields and methods of the passed instance. A members-injection method
* may be void or return its single parameter as a convenience for chaining. The following are all
* valid members-injection method declarations:
*
* <pre><code>
* void injectSomeType(SomeType someType);
* SomeType injectAndReturnSomeType(SomeType someType);
* </code></pre>
*
* <p>A method with no parameters that returns a {@link MembersInjector} is equivalent to a members
* injection method. Calling {@link MembersInjector#injectMembers} on the returned object will
* perform the same work as a members injection method. For example:
*
* <pre><code>
* {@literal MembersInjector<SomeType>} getSomeTypeMembersInjector();
* </code></pre>
*
* <h4>A note about covariance</h4>
*
* <p>While a members-injection method for a type will accept instances of its subtypes, only {@link
* Inject}-annotated members of the parameter type and its supertypes will be injected; members of
* subtypes will not. For example, given the following types, only {@code a} and {@code b} will be
* injected into an instance of {@code Child} when it is passed to the members-injection method
* {@code injectSelf(Self instance)}:
*
* <pre><code>
* class Parent {
* {@literal @}Inject A a;
* }
*
* class Self extends Parent {
* {@literal @}Inject B b;
* }
*
* class Child extends Self {
* {@literal @}Inject C c;
* }
* </code></pre>
*
* <a name="instantiation"></a>
* <h2>Instantiation</h2>
*
* <p>Component implementations are primarily instantiated via a generated <a
* href="http://en.wikipedia.org/wiki/Builder_pattern">builder</a> or <a
* href="https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)">factory</a>.
*
* <p>If a nested {@link Builder @Component.Builder} or {@link Factory @Component.Factory} type
* exists in the component, Dagger will generate an implementation of that type. If neither exists,
* Dagger will generate a builder type that has a method to set each of the {@linkplain #modules}
* and component {@linkplain #dependencies} named with the <a
* href="http://en.wikipedia.org/wiki/CamelCase">lower camel case</a> version of the module or
* dependency type.
*
* <p>In either case, the Dagger-generated component type will have a static method, named either
* {@code builder()} or {@code factory()}, that returns a builder or factory instance.
*
* <p>Example of using a builder:
*
* <pre>{@code
* public static void main(String[] args) {
* OtherComponent otherComponent = ...;
* MyComponent component = DaggerMyComponent.builder()
* // required because component dependencies must be set
* .otherComponent(otherComponent)
* // required because FlagsModule has constructor parameters
* .flagsModule(new FlagsModule(args))
* // may be elided because a no-args constructor is visible
* .myApplicationModule(new MyApplicationModule())
* .build();
* }
* }</pre>
*
* <p>Example of using a factory:
*
* <pre>{@code
* public static void main(String[] args) {
* OtherComponent otherComponent = ...;
* MyComponent component = DaggerMyComponent.factory()
* .create(otherComponent, new FlagsModule(args), new MyApplicationModule());
* // Note that all parameters to a factory method are required, even if one is for a module
* // that Dagger could instantiate. The only case where null is legal is for a
* // @BindsInstance @Nullable parameter.
* }
* }</pre>
*
* <p>In the case that a component has no component dependencies and only no-arg modules, the
* generated component will also have a factory method {@code create()}. {@code
* SomeComponent.create()} and {@code SomeComponent.builder().build()} are both valid and
* equivalent.
*
* <a name="scope"></a>
* <h2>Scope</h2>
*
* <p>Each Dagger component can be associated with a scope by annotating it with the {@linkplain
* Scope scope annotation}. The component implementation ensures that there is only one provision of
* each scoped binding per instance of the component. If the component declares a scope, it may only
* contain unscoped bindings or bindings of that scope anywhere in the graph. For example:
*
* <pre><code>
* {@literal @}Singleton {@literal @}Component
* interface MyApplicationComponent {
* // this component can only inject types using unscoped or {@literal @}Singleton bindings
* }
* </code></pre>
*
* <p>In order to get the proper behavior associated with a scope annotation, it is the caller's
* responsibility to instantiate new component instances when appropriate. A {@link Singleton}
* component, for instance, should only be instantiated once per application, while a {@code
* RequestScoped} component should be instantiated once per request. Because components are
* self-contained implementations, exiting a scope is as simple as dropping all references to the
* component instance.
*
* <a name="component-relationships"></a>
* <h2>Component relationships</h2>
*
* <p>While there is much utility in isolated components with purely unscoped bindings, many
* applications will call for multiple components with multiple scopes to interact. Dagger provides
* two mechanisms for relating components.
*
* <a name="subcomponents"></a>
* <h3>Subcomponents</h3>
*
* <p>The simplest way to relate two components is by declaring a {@link Subcomponent}. A
* subcomponent behaves exactly like a component, but has its implementation generated within a
* parent component or subcomponent. That relationship allows the subcomponent implementation to
* inherit the <em>entire</em> binding graph from its parent when it is declared. For that reason, a
* subcomponent isn't evaluated for completeness until it is associated with a parent.
*
* <p>Subcomponents are declared by listing the class in the {@link Module#subcomponents()}
* attribute of one of the parent component's modules. This binds the {@link Subcomponent.Builder}
* or {@link Subcomponent.Factory} for that subcomponent within the parent component.
*
* <p>Subcomponents may also be declared via a factory method on a parent component or subcomponent.
* The method may have any name, but must return the subcomponent. The factory method's parameters
* may be any number of the subcomponent's modules, but must at least include those without visible
* no-arg constructors. The following is an example of a factory method that creates a
* request-scoped subcomponent from a singleton-scoped parent:
*
* <pre><code>
* {@literal @}Singleton {@literal @}Component
* interface ApplicationComponent {
* // component methods...
*
* RequestComponent newRequestComponent(RequestModule requestModule);
* }
* </code></pre>
*
* <a name="component-dependencies"></a>
* <h3>Component dependencies</h3>
*
* <p>While subcomponents are the simplest way to compose subgraphs of bindings, subcomponents are
* tightly coupled with the parents; they may use any binding defined by their ancestor component
* and subcomponents. As an alternative, components can use bindings only from another <em>component
* interface</em> by declaring a {@linkplain #dependencies component dependency}. When a type is
* used as a component dependency, each <a href="#provision-methods">provision method</a> on the
* dependency is bound as a provider. Note that <em>only</em> the bindings exposed as provision
* methods are available through component dependencies.
*
* @since 2.0
*/
@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
@Target(TYPE)
@Documented
public @interface Component {
/**
* A list of classes annotated with {@link Module} whose bindings are used to generate the
* component implementation. Note that through the use of {@link Module#includes} the full set of
* modules used to implement the component may include more modules that just those listed here.
*/
Class<?>[] modules() default {};
/**
* A list of types that are to be used as <a href="#component-dependencies">component
* dependencies</a>.
*/
Class<?>[] dependencies() default {};
/**
* A builder for a component.
*
* <p>A builder is a type with setter methods for the {@linkplain Component#modules modules},
* {@linkplain Component#dependencies dependencies} and {@linkplain BindsInstance bound instances}
* required by the component and a single no-argument build method that creates a new component
* instance.
*
* <p>Components may have a single nested {@code static abstract class} or {@code interface}
* annotated with {@code @Component.Builder}. If they do, then Dagger will generate a builder
* class that implements that type. Note that a component with a {@code @Component.Builder} may
* not also have a {@code @Component.Factory}.
*
* <p>Builder types must follow some rules:
*
* <ul>
* <li>There <i>must</i> be exactly one abstract no-argument method that returns the component
* type or one of its supertypes, called the "build method".
* <li>There <i>may</i> be other other abstract methods, called "setter methods".
* <li>Setter methods <i>must</i> take a single argument and return {@code void}, the builder
* type or a supertype of the builder type.
* <li>There <i>must</i> be a setter method for each {@linkplain Component#dependencies
* component dependency}.
* <li>There <i>must</i> be a setter method for each non-{@code abstract} {@linkplain
* Component#modules module} that has non-{@code static} binding methods, unless Dagger can
* instantiate that module with a visible no-argument constructor.
* <li>There <i>may</i> be setter methods for modules that Dagger can instantiate or does not
* need to instantiate.
* <li>There <i>may</i> be setter methods annotated with {@code @BindsInstance}. These methods
* bind the instance passed to them within the component. See {@link
* BindsInstance @BindsInstance} for more information.
* <li>There <i>may</i> be non-{@code abstract} methods, but they are ignored as far as
* validation and builder generation are concerned.
* </ul>
*
* For example, this could be a valid {@code Component} with a {@code Builder}:
*
* <pre><code>
* {@literal @}Component(modules = {BackendModule.class, FrontendModule.class})
* interface MyComponent {
* MyWidget myWidget();
*
* {@literal @}Component.Builder
* interface Builder {
* Builder backendModule(BackendModule bm);
* Builder frontendModule(FrontendModule fm);
* {@literal @}BindsInstance
* Builder foo(Foo foo);
* MyComponent build();
* }
* }</code></pre>
*/
@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
@Target(TYPE)
@Documented
@interface Builder {}
/**
* A factory for a component.
*
* <p>A factory is a type with a single method that returns a new component instance each time it
* is called. The parameters of that method allow the caller to provide the {@linkplain
* Component#modules modules}, {@linkplain Component#dependencies dependencies} and {@linkplain
* BindsInstance bound instances} required by the component.
*
* <p>Components may have a single nested {@code static abstract class} or {@code interface}
* annotated with {@code @Component.Factory}. If they do, then Dagger will generate a factory
* class that will implement that type. Note that a component with a {@code @Component.Factory}
* may not also have a {@code @Component.Builder}.
*
* <p>Factory types must follow some rules:
*
* <ul>
* <li>There <i>must</i> be exactly one abstract method, which must return the component type or
* one of its supertypes.
* <li>The method <i>must</i> have a parameter for each {@linkplain Component#dependencies
* component dependency}.
* <li>The method <i>must</i> have a parameter for each non-{@code abstract} {@linkplain
* Component#modules module} that has non-{@code static} binding methods, unless Dagger can
* instantiate that module with a visible no-argument constructor.
* <li>The method <i>may</i> have parameters for modules that Dagger can instantiate or does not
* need to instantiate.
* <li>The method <i>may</i> have parameters annotated with {@code @BindsInstance}. These
* parameters bind the instance passed for that parameter within the component. See {@link
* BindsInstance @BindsInstance} for more information.
* <li>There <i>may</i> be non-{@code abstract} methods, but they are ignored as far as
* validation and factory generation are concerned.
* </ul>
*
* For example, this could be a valid {@code Component} with a {@code Factory}:
*
* <pre><code>
* {@literal @}Component(modules = {BackendModule.class, FrontendModule.class})
* interface MyComponent {
* MyWidget myWidget();
*
* {@literal @}Component.Factory
* interface Factory {
* MyComponent newMyComponent(
* BackendModule bm, FrontendModule fm, {@literal @}BindsInstance Foo foo);
* }
* }</code></pre>
*
* <p>For a root component, if a {@code @Component.Factory} is defined, the generated component
* type will have a {@code static} method named {@code factory()} that returns an instance of that
* factory.
*
* @since 2.22
*/
@Retention(RUNTIME) // Allows runtimes to have specialized behavior interoperating with Dagger.
@Target(TYPE)
@Documented
@interface Factory {}
}