0
# Multibindings
1

2
Advanced binding patterns for injecting collections (Set, Map) and optional values, enabling modular composition of dependencies.
3

4
## Capabilities
5

6
### Multibinder Class
7

8
Binds multiple values separately to be injected as a complete Set<T>.
9

10
```java { .api }
11
/**
12
 * An API to bind multiple values separately, only to later inject them as a
13
 * complete collection. Multibinder is intended for use in your application's
14
 * module. Instead of binding multiple values separately, Multibinder collects
15
 * the values and provides them as a single Set<T> binding.
16
 * @param <T> Type of elements in the set
17
 */
18
public class Multibinder<T> {
19
    /**
20
     * Creates a new multibinder that collects instances of type T in a Set.
21
     * @param binder Binder to configure
22
     * @param type Element type
23
     * @return New Multibinder instance
24
     */
25
    public static <T> Multibinder<T> newSetBinder(Binder binder, Class<T> type);
26
    
27
    /**
28
     * Creates a new multibinder that collects instances of type T in a Set.
29
     * @param binder Binder to configure
30
     * @param type Element type literal
31
     * @return New Multibinder instance
32
     */
33
    public static <T> Multibinder<T> newSetBinder(Binder binder, TypeLiteral<T> type);
34
    
35
    /**
36
     * Creates a new multibinder with a binding annotation.
37
     * @param binder Binder to configure
38
     * @param type Element type
39
     * @param annotation Binding annotation
40
     * @return New Multibinder instance
41
     */
42
    public static <T> Multibinder<T> newSetBinder(Binder binder, Class<T> type, Annotation annotation);
43
    
44
    /**
45
     * Configures the bound set to silently discard duplicate elements.
46
     * @return This multibinder instance
47
     */
48
    public Multibinder<T> permitDuplicates();
49
    
50
    /**
51
     * Returns a binding builder used to add a new element to the set.
52
     * @return Binding builder for adding elements
53
     */
54
    public LinkedBindingBuilder<T> addBinding();
55
}
56
```
57

58
### MapBinder Class
59

60
Binds multiple map entries separately to be injected as a complete Map<K,V>.
61

62
```java { .api }
63
/**
64
 * An API to bind multiple map entries separately, only to later inject them as
65
 * a complete map. MapBinder is intended for use in your application's module.
66
 * @param <K> Map key type
67
 * @param <V> Map value type
68
 */
69
public class MapBinder<K, V> {
70
    /**
71
     * Creates a new map binder that collects entries into a Map<K,V>.
72
     * @param binder Binder to configure
73
     * @param keyType Key type
74
     * @param valueType Value type
75
     * @return New MapBinder instance
76
     */
77
    public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType);
78
    
79
    /**
80
     * Creates a new map binder that collects entries into a Map<K,V>.
81
     * @param binder Binder to configure  
82
     * @param keyType Key type literal
83
     * @param valueType Value type literal
84
     * @return New MapBinder instance
85
     */
86
    public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, TypeLiteral<K> keyType, TypeLiteral<V> valueType);
87
    
88
    /**
89
     * Configures the bound map to silently ignore duplicate entries.
90
     * @return This MapBinder instance
91
     */
92
    public MapBinder<K, V> permitDuplicates();
93
    
94
    /**
95
     * Returns a binding builder used to add a new entry to the map.
96
     * @param key Map key
97
     * @return Binding builder for the value
98
     */
99
    public LinkedBindingBuilder<V> addBinding(K key);
100
}
101
```
102

103
**Usage Examples:**
104

105
```java
106
// Set multibinding
107
public class PluginModule extends AbstractModule {
108
    @Override
109
    protected void configure() {
110
        Multibinder<Plugin> pluginBinder = Multibinder.newSetBinder(binder(), Plugin.class);
111
        pluginBinder.addBinding().to(DatabasePlugin.class);
112
        pluginBinder.addBinding().to(CachePlugin.class);
113
        pluginBinder.addBinding().to(LoggingPlugin.class);
114
    }
115
}
116

117
// Map multibinding
118
public class ConfigModule extends AbstractModule {
119
    @Override
120
    protected void configure() {
121
        MapBinder<String, DatabaseConfig> mapBinder = MapBinder.newMapBinder(
122
            binder(), String.class, DatabaseConfig.class);
123
        mapBinder.addBinding("primary").toInstance(new DatabaseConfig("primary-db"));
124
        mapBinder.addBinding("secondary").toInstance(new DatabaseConfig("secondary-db"));
125
    }
126
}
127

128
// Injection
129
public class Application {
130
    @Inject Set<Plugin> plugins;
131
    @Inject Map<String, DatabaseConfig> databases;
132
}
133
```
134

135
### OptionalBinder Class
136

137
Binds optional values with possible defaults, injected as Optional<T>.
138

139
```java { .api }
140
/**
141
 * An API to bind optional values. OptionalBinder enables injecting dependencies
142
 * that may or may not be present, with optional default values.
143
 * @param <T> Type of the optional value
144
 */
145
public class OptionalBinder<T> {
146
    /**
147
     * Creates a new optional binder.
148
     * @param binder Binder to configure
149
     * @param type Value type
150
     * @return New OptionalBinder instance
151
     */
152
    public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, Class<T> type);
153
    
154
    /**
155
     * Sets the default binding for this optional value.
156
     * @return Binding builder for the default value
157
     */
158
    public LinkedBindingBuilder<T> setDefault();
159
    
160
    /**
161
     * Sets the actual binding for this optional value.
162
     * @return Binding builder for the actual value
163
     */
164
    public LinkedBindingBuilder<T> setBinding();
165
}
166
```