0
# Google Guice
1

2
Google Guice is a lightweight dependency injection framework for Java 8 and above that eliminates the need for factories and the use of 'new' in Java code. It embraces Java's type-safe nature and provides runtime dependency resolution with helpful error messages.
3

4
## Package Information  
5

6
- **Package Name**: com.google.inject:guice
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Version**: 7.0.0
10
- **Installation**: Add to pom.xml: `<dependency><groupId>com.google.inject</groupId><artifactId>guice</artifactId><version>7.0.0</version></dependency>`
11

12
## Core Imports
13

14
```java
15
import com.google.inject.*;
16
import com.google.inject.name.Named;
17
```
18

19
## Basic Usage
20

21
```java
22
import com.google.inject.*;
23

24
// Define an interface and implementation
25
interface MessageService {
26
    String getMessage();
27
}
28

29
class EmailService implements MessageService {
30
    public String getMessage() {
31
        return "Email message";
32
    }
33
}
34

35
// Create a module to configure bindings
36
class AppModule extends AbstractModule {
37
    @Override
38
    protected void configure() {
39
        bind(MessageService.class).to(EmailService.class);
40
    }
41
}
42

43
// Create injector and get instances
44
public class MyApp {
45
    public static void main(String[] args) {
46
        Injector injector = Guice.createInjector(new AppModule());
47
        MessageService service = injector.getInstance(MessageService.class);
48
        System.out.println(service.getMessage());
49
    }
50
}
51
```
52

53
## Architecture
54

55
Guice is built around several key components:
56

57
- **Injector**: The core dependency injection engine that creates and provides instances
58
- **Module**: Configuration units that define how dependencies should be resolved
59
- **Binder**: API for configuring dependency bindings within modules
60
- **Key & TypeLiteral**: Type-safe identifiers for dependencies including generic types
61
- **Provider**: Custom factories for creating instances with complex initialization logic
62
- **Scopes**: Lifecycle management for instances (Singleton, etc.)
63
- **Annotations**: Markers for injection points (@Inject) and binding qualifiers (@Named)
64

65
## Capabilities
66

67
### Core Dependency Injection
68

69
Essential classes for creating injectors, configuring modules, and injecting dependencies. This is the primary API that most applications will use.
70

71
```java { .api }
72
public final class Guice {
73
    public static Injector createInjector(Module... modules);
74
    public static Injector createInjector(Stage stage, Module... modules);
75
}
76

77
public interface Injector {
78
    <T> T getInstance(Class<T> type);
79
    <T> T getInstance(Key<T> key);
80
    <T> Provider<T> getProvider(Class<T> type);
81
    void injectMembers(Object instance);
82
    Injector createChildInjector(Module... modules);
83
}
84
```
85

86
[Core Dependency Injection](./core-injection.md)
87

88
### Module Configuration  
89

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

92
```java { .api }
93
public interface Module {
94
    void configure(Binder binder);
95
}
96

97
public abstract class AbstractModule implements Module {
98
    protected <T> AnnotatedBindingBuilder<T> bind(Class<T> clazz);
99
    protected AnnotatedConstantBindingBuilder bindConstant();
100
    protected void install(Module module);
101
}
102
```
103

104
[Module Configuration](./modules.md)
105

106
### Type System & Keys
107

108
Type-safe dependency identification system supporting generic types and binding annotations for distinguishing multiple bindings of the same type.
109

110
```java { .api }
111
public class Key<T> {
112
    public static <T> Key<T> get(Class<T> type);
113
    public static <T> Key<T> get(Class<T> type, Class<? extends Annotation> annotationType);
114
    public static <T> Key<T> get(Class<T> type, Annotation annotation);
115
}
116

117
public class TypeLiteral<T> {
118
    public static <T> TypeLiteral<T> get(Class<T> type);
119
    public Class<? super T> getRawType();
120
    public Type getType();
121
}
122
```
123

124
[Type System & Keys](./types-keys.md)
125

126
### Providers & Scopes
127

128
Custom instance creation and lifecycle management including built-in scopes and provider interfaces for complex object construction.
129

130
```java { .api }
131
public interface Provider<T> {
132
    T get();
133
}
134

135
public interface Scope {
136
    <T> Provider<T> scope(Key<T> key, Provider<T> unscoped);
137
}
138

139
public final class Scopes {
140
    public static final Scope SINGLETON;
141
    public static final Scope NO_SCOPE;
142
}
143
```
144

145
[Providers & Scopes](./providers-scopes.md)
146

147
### Essential Annotations
148

149
Key annotations for marking injection points, scoping instances, and creating binding qualifiers.
150

151
```java { .api }
152
@Target({METHOD, CONSTRUCTOR, FIELD})
153
@Retention(RUNTIME)
154
public @interface Inject {
155
    boolean optional() default false;
156
}
157

158
@Target({TYPE, METHOD})
159
@Retention(RUNTIME)
160
@ScopeAnnotation
161
public @interface Singleton {}
162

163
@Target(METHOD)
164
@Retention(RUNTIME)
165
public @interface Provides {}
166
```
167

168
[Essential Annotations](./annotations.md)
169

170
### Multibindings
171

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

174
```java { .api }
175
public class Multibinder<T> {
176
    public static <T> Multibinder<T> newSetBinder(Binder binder, Class<T> type);
177
    public LinkedBindingBuilder<T> addBinding();
178
}
179

180
public class MapBinder<K, V> {
181
    public static <K, V> MapBinder<K, V> newMapBinder(Binder binder, Class<K> keyType, Class<V> valueType);
182
    public LinkedBindingBuilder<V> addBinding(K key);
183
}
184
```
185

186
[Multibindings](./multibindings.md)
187

188
### Advanced Features
189

190
AOP interceptors, method matching, private modules, and other advanced dependency injection patterns.
191

192
```java { .api }
193
public interface Matcher<T> {
194
    boolean matches(T t);
195
}
196

197
public final class Matchers {
198
    public static Matcher<Class> subclassesOf(Class<?> superclass);
199
    public static Matcher<AnnotatedElement> annotatedWith(Class<? extends Annotation> annotationType);
200
}
201

202
public abstract class PrivateModule implements Module {
203
    protected void expose(Class<?> type);
204
    protected void expose(Key<?> key);
205
}
206
```
207

208
[Advanced Features](./advanced.md)
209

210
### Service Provider Interface (SPI)
211

212
Introspection and tooling APIs for analyzing injector configuration, visiting bindings, and integrating with development tools.
213

214
```java { .api }
215
public final class Elements {
216
    public static List<Element> getElements(Module... modules);
217
    public static Module getModule(Iterable<? extends Element> elements);
218
}
219

220
public interface Element {
221
    Object getSource();
222
    <T> T acceptVisitor(ElementVisitor<T> visitor);
223
    void applyTo(Binder binder);
224
}
225
```
226

227
[Service Provider Interface](./spi.md)