0
# Module Configuration
1

2
Classes and interfaces for defining how dependencies are bound, including the fluent binding DSL and provider methods.
3

4
## Capabilities
5

6
### Module Interface
7

8
The base interface for contributing configuration information to an injector.
9

10
```java { .api }
11
/**
12
 * A module contributes configuration information, typically interface bindings,
13
 * which will be used to create an Injector.
14
 */
15
public interface Module {
16
    /**
17
     * Contributes bindings and other configurations for this module to binder.
18
     * Do not invoke this method directly to install submodules. Instead use
19
     * Binder.install(Module), which ensures that @Provides provider methods are discovered.
20
     * @param binder The binder to configure
21
     */
22
    void configure(Binder binder);
23
}
24
```
25

26
### AbstractModule Class
27

28
Helper class that provides a streamlined syntax for creating modules.
29

30
```java { .api }
31
/**
32
 * AbstractModule is a helper class used to add bindings to the Guice injector.
33
 * Simply extend this class and implement configure(), then call the inherited
34
 * methods which mirror those found in Binder.
35
 */
36
public abstract class AbstractModule implements Module {
37
    /**
38
     * Configures a Binder via the exposed methods. Override this method
39
     * to define your module's bindings.
40
     */
41
    protected void configure() {}
42
    
43
    /**
44
     * Creates a binding for the given type.
45
     * @param clazz Type to bind
46
     * @return Binding builder for further configuration
47
     */
48
    protected <T> AnnotatedBindingBuilder<T> bind(Class<T> clazz);
49
    
50
    /**
51
     * Creates a binding for the given key.
52
     * @param key Key to bind
53
     * @return Binding builder for further configuration  
54
     */
55
    protected <T> LinkedBindingBuilder<T> bind(Key<T> key);
56
    
57
    /**
58
     * Creates a binding for the given type literal.
59
     * @param typeLiteral Type literal to bind
60
     * @return Binding builder for further configuration
61
     */
62
    protected <T> AnnotatedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral);
63
    
64
    /**
65
     * Binds a constant value.
66
     * @return Constant binding builder
67
     */
68
    protected AnnotatedConstantBindingBuilder bindConstant();
69
    
70
    /**
71
     * Installs another module into this module.
72
     * @param module Module to install
73
     */
74
    protected void install(Module module);
75
    
76
    /**
77
     * Binds a scope annotation to a scope implementation.
78
     * @param scopeAnnotation Scope annotation class
79
     * @param scope Scope implementation
80
     */
81
    protected void bindScope(Class<? extends Annotation> scopeAnnotation, Scope scope);
82
    
83
    /**
84
     * Binds method interceptors to methods matched by class and method matchers.
85
     * @param classMatcher Matcher for classes to intercept
86
     * @param methodMatcher Matcher for methods to intercept
87
     * @param interceptors Method interceptors to apply
88
     */
89
    protected void bindInterceptor(
90
        Matcher<? super Class<?>> classMatcher,
91
        Matcher<? super Method> methodMatcher,
92
        MethodInterceptor... interceptors
93
    );
94
    
95
    /**
96
     * Requests injection of static fields and methods.
97
     * @param type Type with static members to inject
98
     */
99
    protected void requestStaticInjection(Class<?>... types);
100
    
101
    /**
102
     * Adds an error message to be reported during injector creation.
103
     * @param message Error message
104
     * @param arguments Message format arguments
105
     */
106
    protected void addError(String message, Object... arguments);
107
    
108
    /**
109
     * Adds an error message to be reported during injector creation.
110
     * @param t Throwable representing the error
111
     */
112
    protected void addError(Throwable t);
113
    
114
    /**
115
     * Adds an error message to be reported during injector creation.
116
     * @param message Error message object
117
     */
118
    protected void addError(Message message);
119
    
120
    /**
121
     * Returns the current binder.
122
     * @return Current binder instance
123
     */
124
    protected Binder binder();
125
    
126
    /**
127
     * Gets a provider for the given key.
128
     * @param key Key to get provider for
129
     * @return Provider for the key
130
     * @since 2.0
131
     */
132
    protected <T> Provider<T> getProvider(Key<T> key);
133
    
134
    /**
135
     * Gets a provider for the given type.
136
     * @param type Type to get provider for
137
     * @return Provider for the type
138
     * @since 2.0
139
     */
140
    protected <T> Provider<T> getProvider(Class<T> type);
141
    
142
    /**
143
     * Gets a members injector for the given type.
144
     * @param type Type to get members injector for
145
     * @return MembersInjector for the type
146
     * @since 2.0
147
     */
148
    protected <T> MembersInjector<T> getMembersInjector(Class<T> type);
149
    
150
    /**
151
     * Gets a members injector for the given type literal.
152
     * @param type TypeLiteral to get members injector for
153
     * @return MembersInjector for the type
154
     * @since 2.0
155
     */
156
    protected <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> type);
157
    
158
    /**
159
     * Returns the current stage.
160
     * @return Current injector creation stage
161
     * @since 2.0
162
     */
163
    protected Stage currentStage();
164
}
165
```
166

167
**Usage Examples:**
168

169
```java
170
public class DatabaseModule extends AbstractModule {
171
    @Override
172
    protected void configure() {
173
        // Bind interface to implementation
174
        bind(DatabaseService.class).to(PostgreSQLService.class);
175
        
176
        // Bind with annotations
177
        bind(Cache.class).annotatedWith(Names.named("primary"))
178
                         .to(RedisCache.class)
179
                         .in(Singleton.class);
180
        
181
        // Bind to instance
182
        bind(String.class).annotatedWith(Names.named("dbUrl"))
183
                          .toInstance("jdbc:postgresql://localhost/mydb");
184
        
185
        // Install other modules
186
        install(new ConfigurationModule());
187
        install(new LoggingModule());
188
    }
189
    
190
    // Provider methods
191
    @Provides
192
    @Singleton
193
    DatabaseConnection provideConnection(@Named("dbUrl") String url) {
194
        return DriverManager.getConnection(url);
195
    }
196
}
197
```
198

199
### Binder Interface
200

201
The API for configuring dependency bindings within modules.
202

203
```java { .api }
204
/**
205
 * Collects configuration information (primarily bindings) which will be used
206
 * to create an Injector.
207
 */
208
public interface Binder {
209
    /**
210
     * Creates a binding for the given type.
211
     * @param type Type to bind
212
     * @return Binding builder for configuration
213
     */
214
    <T> AnnotatedBindingBuilder<T> bind(Class<T> type);
215
    
216
    /**
217
     * Creates a binding for the given key.
218
     * @param key Key to bind
219
     * @return Binding builder for configuration
220
     */
221
    <T> LinkedBindingBuilder<T> bind(Key<T> key);
222
    
223
    /**
224
     * Creates a binding for the given type literal.
225
     * @param typeLiteral Type literal to bind
226
     * @return Binding builder for configuration
227
     */
228
    <T> LinkedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral);
229
    
230
    /**
231
     * Binds a constant value.
232
     * @return Constant binding builder
233
     */
234
    AnnotatedConstantBindingBuilder bindConstant();
235
    
236
    /**
237
     * Installs the given module.
238
     * @param module Module to install
239
     */
240
    void install(Module module);
241
    
242
    /**
243
     * Binds a scope annotation to a scope implementation.
244
     * @param annotationType Scope annotation
245
     * @param scope Scope implementation
246
     */
247
    void bindScope(Class<? extends Annotation> annotationType, Scope scope);
248
    
249
    /**
250
     * Binds method interceptors.
251
     * @param classMatcher Class matcher
252
     * @param methodMatcher Method matcher  
253
     * @param interceptors Interceptors to bind
254
     */
255
    void bindInterceptor(
256
        Matcher<? super Class<?>> classMatcher,
257
        Matcher<? super Method> methodMatcher,
258
        MethodInterceptor... interceptors
259
    );
260
    
261
    /**
262
     * Gets the current stage.
263
     * @return Current development stage
264
     */
265
    Stage currentStage();
266
    
267
    /**
268
     * Records an error message.
269
     * @param message Error message
270
     * @param arguments Format arguments
271
     */
272
    void addError(String message, Object... arguments);
273
    
274
    /**
275
     * Records an error.
276
     * @param t Throwable to record
277
     */
278
    void addError(Throwable t);
279
    
280
    /**
281
     * Records an error message.
282
     * @param message Message to record
283
     */
284
    void addError(Message message);
285
    
286
    /**
287
     * Returns a binder that skips class loading and method scanning.
288
     * @return Restricted binder
289
     */
290
    Binder skipSources(Class<?>... classesToSkip);
291
    
292
    /**
293
     * Returns a binder that uses the given source for newly created elements.
294
     * @param source Source object
295
     * @return Binder with specified source
296
     */
297
    Binder withSource(Object source);
298
}
299
```
300

301
## Binding Builder Interfaces
302

303
### AnnotatedBindingBuilder
304

305
Allows specifying binding annotations in the fluent binding DSL.
306

307
```java { .api }
308
/**
309
 * Builder for bindings that can be annotated.
310
 * @param <T> Type being bound
311
 */
312
public interface AnnotatedBindingBuilder<T> extends LinkedBindingBuilder<T> {
313
    /**
314
     * Annotates the binding with the given annotation type.
315
     * @param annotationType Annotation type
316
     * @return LinkedBindingBuilder for further configuration
317
     */
318
    LinkedBindingBuilder<T> annotatedWith(Class<? extends Annotation> annotationType);
319
    
320
    /**
321
     * Annotates the binding with the given annotation instance.
322
     * @param annotation Annotation instance
323
     * @return LinkedBindingBuilder for further configuration
324
     */
325
    LinkedBindingBuilder<T> annotatedWith(Annotation annotation);
326
}
327
```
328

329
### LinkedBindingBuilder
330

331
Allows specifying what a binding targets (implementation, provider, instance).
332

333
```java { .api }
334
/**
335
 * Builder for specifying binding targets.
336
 * @param <T> Type being bound
337
 */
338
public interface LinkedBindingBuilder<T> extends ScopedBindingBuilder {
339
    /**
340
     * Binds to the given implementation class.
341
     * @param implementation Implementation class
342
     * @return ScopedBindingBuilder for scope configuration
343
     */
344
    ScopedBindingBuilder to(Class<? extends T> implementation);
345
    
346
    /**
347
     * Binds to the given key.
348
     * @param targetKey Target key  
349
     * @return ScopedBindingBuilder for scope configuration
350
     */
351
    ScopedBindingBuilder to(Key<? extends T> targetKey);
352
    
353
    /**
354
     * Binds to the given type literal.
355
     * @param implementation Target type literal
356
     * @return ScopedBindingBuilder for scope configuration
357
     */
358
    ScopedBindingBuilder to(TypeLiteral<? extends T> implementation);
359
    
360
    /**
361
     * Binds to a provider class.
362
     * @param providerType Provider class
363
     * @return ScopedBindingBuilder for scope configuration
364
     */
365
    ScopedBindingBuilder toProvider(Class<? extends Provider<? extends T>> providerType);
366
    
367
    /**
368
     * Binds to a provider key.
369
     * @param providerKey Provider key
370
     * @return ScopedBindingBuilder for scope configuration
371
     */
372
    ScopedBindingBuilder toProvider(Key<? extends Provider<? extends T>> providerKey);
373
    
374
    /**
375
     * Binds to a provider instance.
376
     * @param provider Provider instance
377
     * @return ScopedBindingBuilder for scope configuration
378
     */
379
    ScopedBindingBuilder toProvider(Provider<? extends T> provider);
380
    
381
    /**
382
     * Binds to the given instance.
383
     * @param instance Instance to bind to
384
     */
385
    void toInstance(T instance);
386
    
387
    /**
388
     * Binds to the given constructor.
389
     * @param constructor Constructor to bind to
390
     * @return ScopedBindingBuilder for scope configuration
391
     */
392
    <S extends T> ScopedBindingBuilder toConstructor(Constructor<S> constructor);
393
    
394
    /**
395
     * Binds to the given constructor with type literal.
396
     * @param constructor Constructor to bind to
397
     * @param type Type literal for the constructor's declaring class
398
     * @return ScopedBindingBuilder for scope configuration
399
     */
400
    <S extends T> ScopedBindingBuilder toConstructor(Constructor<S> constructor, TypeLiteral<? extends S> type);
401
}
402
```
403

404
### ScopedBindingBuilder
405

406
Allows specifying the scope of a binding.
407

408
```java { .api }
409
/**
410
 * Builder for specifying binding scope.
411
 */
412
public interface ScopedBindingBuilder {
413
    /**
414
     * Scopes the binding with the given scope annotation.
415
     * @param scopeAnnotation Scope annotation
416
     */
417
    void in(Class<? extends Annotation> scopeAnnotation);
418
    
419
    /**
420
     * Scopes the binding with the given scope.
421
     * @param scope Scope implementation
422
     */
423
    void in(Scope scope);
424
    
425
    /**
426
     * Scopes the binding as an eager singleton.
427
     */
428
    void asEagerSingleton();
429
}
430
```
431

432
### ConstantBindingBuilder
433

434
Binds constants to various primitive types.
435

436
```java { .api }
437
/**
438
 * Builder for binding constants.
439
 */
440
public interface ConstantBindingBuilder {
441
    /**
442
     * Binds to a string value.
443
     * @param value String value
444
     */
445
    void to(String value);
446
    
447
    /**
448
     * Binds to an int value.
449
     * @param value int value
450
     */
451
    void to(int value);
452
    
453
    /**
454
     * Binds to a long value.
455
     * @param value long value
456
     */
457
    void to(long value);
458
    
459
    /**
460
     * Binds to a boolean value.
461
     * @param value boolean value
462
     */
463
    void to(boolean value);
464
    
465
    /**
466
     * Binds to a double value.
467
     * @param value double value
468
     */
469
    void to(double value);
470
    
471
    /**
472
     * Binds to a float value.
473
     * @param value float value
474
     */
475
    void to(float value);
476
    
477
    /**
478
     * Binds to a byte value.
479
     * @param value byte value
480
     */
481
    void to(byte value);
482
    
483
    /**
484
     * Binds to a short value.
485
     * @param value short value
486
     */
487
    void to(short value);
488
    
489
    /**
490
     * Binds to a char value.
491
     * @param value char value
492
     */
493
    void to(char value);
494
    
495
    /**
496
     * Binds to a Class value.
497
     * @param value Class value
498
     */
499
    void to(Class<?> value);
500
    
501
    /**
502
     * Binds to an enum value.
503
     * @param value Enum value
504
     */
505
    <E extends Enum<E>> void to(E value);
506
}
507
```