0
# Project Lombok
1

2
Project Lombok is a comprehensive Java annotation processing library that dramatically reduces boilerplate code by automatically generating common methods and patterns at compile time. It integrates seamlessly with IDEs and build tools, generating code during compilation without affecting runtime performance.
3

4
## Package Information
5

6
- **Package Name**: lombok
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven/Gradle dependencies and configure annotation processing
10
- **Version**: 1.18.40
11

12
## Core Imports
13

14
```java
15
// Core annotations
16
import lombok.*;
17

18
// Data class annotations
19
import lombok.Data;
20
import lombok.Value;
21

22
// Property access
23
import lombok.Getter;
24
import lombok.Setter;
25

26
// Constructors
27
import lombok.NoArgsConstructor;
28
import lombok.AllArgsConstructor;
29
import lombok.RequiredArgsConstructor;
30

31
// Builder pattern
32
import lombok.Builder;
33
import lombok.Singular;
34

35
// Object methods
36
import lombok.ToString;
37
import lombok.EqualsAndHashCode;
38

39
// Immutable patterns
40
import lombok.With;
41

42
// Utility annotations
43
import lombok.NonNull;
44
import lombok.SneakyThrows;
45
import lombok.Synchronized;
46
import lombok.Cleanup;
47
import lombok.Locked;
48

49
// Type inference
50
import lombok.val;
51
import lombok.var;
52

53
// Logging frameworks
54
import lombok.extern.slf4j.Slf4j;
55
import lombok.extern.log4j.Log4j2;
56
import lombok.extern.java.Log;
57
import lombok.extern.apachecommons.CommonsLog;
58
import lombok.extern.jbosslog.JBossLog;
59
import lombok.extern.flogger.Flogger;
60

61
// Jackson integration
62
import lombok.extern.jackson.Jacksonized;
63

64
// Experimental features
65
import lombok.experimental.*;
66
import lombok.experimental.SuperBuilder;
67
import lombok.experimental.UtilityClass;
68
import lombok.experimental.FieldNameConstants;
69
import lombok.experimental.Accessors;
70
```
71

72
## Basic Usage
73

74
```java
75
import lombok.Data;
76
import lombok.Builder;
77
import lombok.extern.slf4j.Slf4j;
78

79
@Data
80
@Builder
81
@Slf4j
82
public class User {
83
    private final String name;
84
    private int age;
85
    private String email;
86
    
87
    public void greet() {
88
        log.info("Hello, I'm {}", name);
89
    }
90
}
91

92
// Usage
93
User user = User.builder()
94
    .name("John Doe")
95
    .age(30)
96
    .email("john@example.com")
97
    .build();
98
    
99
System.out.println(user.getName()); // Generated getter
100
user.setAge(31); // Generated setter
101
log.info(user.toString()); // Generated toString
102
```
103

104
## Architecture
105

106
Project Lombok is built around several key architectural components:
107

108
- **Annotation Processing**: Uses Java's annotation processing API to generate code at compile time
109
- **AST Transformation**: Modifies the Abstract Syntax Tree during compilation to add methods
110
- **IDE Integration**: Provides plugins for Eclipse, IntelliJ IDEA, and NetBeans for editor support
111
- **Configuration System**: Supports lombok.config files for project-wide settings
112
- **Type Safety**: Maintains full type safety and generic type preservation
113
- **Compile-Time Generation**: All code generation happens during compilation, not at runtime
114

115
## Capabilities
116

117
### Data Class Generation
118

119
Comprehensive data class support with automatic generation of getters, setters, constructors, and object methods.
120

121
```java { .api }
122
@Target(ElementType.TYPE)
123
@Retention(RetentionPolicy.SOURCE)
124
public @interface Data {
125
    String staticConstructor() default "";
126
}
127

128
@Target(ElementType.TYPE)
129
@Retention(RetentionPolicy.SOURCE)
130
public @interface Value {
131
    String staticConstructor() default "";
132
}
133
```
134

135
[Data Classes](./data-classes.md)
136

137
### Property Access
138

139
Automatic generation of getter and setter methods with configurable access levels and lazy evaluation support.
140

141
```java { .api }
142
@Target({ElementType.FIELD, ElementType.TYPE})
143
@Retention(RetentionPolicy.SOURCE)
144
public @interface Getter {
145
    AccessLevel value() default AccessLevel.PUBLIC;
146
    AnyAnnotation[] onMethod() default {};
147
    boolean lazy() default false;
148
}
149

150
@Target({ElementType.FIELD, ElementType.TYPE})
151
@Retention(RetentionPolicy.SOURCE)
152
public @interface Setter {
153
    AccessLevel value() default AccessLevel.PUBLIC;
154
    AnyAnnotation[] onMethod() default {};
155
    AnyAnnotation[] onParam() default {};
156
}
157
```
158

159
[Property Access](./property-access.md)
160

161
### Constructor Generation
162

163
Automatic constructor generation with support for required arguments, all arguments, and no-argument constructors.
164

165
```java { .api }
166
@Target(ElementType.TYPE)
167
@Retention(RetentionPolicy.SOURCE)
168
public @interface NoArgsConstructor {
169
    String staticName() default "";
170
    AnyAnnotation[] onConstructor() default {};
171
    AccessLevel access() default AccessLevel.PUBLIC;
172
    boolean force() default false;
173
}
174

175
@Target(ElementType.TYPE)
176
@Retention(RetentionPolicy.SOURCE)
177
public @interface AllArgsConstructor {
178
    String staticName() default "";
179
    AnyAnnotation[] onConstructor() default {};
180
    AccessLevel access() default AccessLevel.PUBLIC;
181
}
182

183
@Target(ElementType.TYPE)
184
@Retention(RetentionPolicy.SOURCE)
185
public @interface RequiredArgsConstructor {
186
    String staticName() default "";
187
    AnyAnnotation[] onConstructor() default {};
188
    AccessLevel access() default AccessLevel.PUBLIC;
189
}
190
```
191

192
[Constructors](./constructors.md)
193

194
### Builder Pattern
195

196
Comprehensive builder pattern implementation with support for inheritance, defaults, and collection handling.
197

198
```java { .api }
199
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR})
200
@Retention(RetentionPolicy.SOURCE)
201
public @interface Builder {
202
    String builderMethodName() default "builder";
203
    String buildMethodName() default "build";
204
    String builderClassName() default "";
205
    boolean toBuilder() default false;
206
    AccessLevel access() default AccessLevel.PUBLIC;
207
    String setterPrefix() default "";
208
}
209

210
@Target({ElementType.FIELD, ElementType.PARAMETER})
211
@Retention(RetentionPolicy.SOURCE)
212
public @interface Singular {
213
    String value() default "";
214
    boolean ignoreNullCollections() default false;
215
}
216
```
217

218
[Builder Pattern](./builder-pattern.md)
219

220
### Object Methods
221

222
Automatic generation of toString, equals, and hashCode methods with extensive customization options.
223

224
```java { .api }
225
@Target(ElementType.TYPE)
226
@Retention(RetentionPolicy.SOURCE)
227
public @interface ToString {
228
    boolean includeFieldNames() default true;
229
    String[] exclude() default {};
230
    String[] of() default {};
231
    boolean callSuper() default false;
232
    boolean doNotUseGetters() default false;
233
    boolean onlyExplicitlyIncluded() default false;
234
}
235

236
@Target(ElementType.TYPE)
237
@Retention(RetentionPolicy.SOURCE)
238
public @interface EqualsAndHashCode {
239
    String[] exclude() default {};
240
    String[] of() default {};
241
    boolean callSuper() default false;
242
    boolean doNotUseGetters() default false;
243
    CacheStrategy cacheStrategy() default CacheStrategy.NEVER;
244
    AnyAnnotation[] onParam() default {};
245
    boolean onlyExplicitlyIncluded() default false;
246
}
247
```
248

249
[Object Methods](./object-methods.md)
250

251
### Logging Integration
252

253
Seamless integration with popular Java logging frameworks through field generation.
254

255
```java { .api }
256
@Target(ElementType.TYPE)
257
@Retention(RetentionPolicy.SOURCE)
258
public @interface Slf4j {
259
    String topic() default "";
260
}
261

262
@Target(ElementType.TYPE)
263
@Retention(RetentionPolicy.SOURCE)
264
public @interface Log4j2 {
265
    String topic() default "";
266
}
267

268
@Target(ElementType.TYPE)
269
@Retention(RetentionPolicy.SOURCE)
270
public @interface CustomLog {
271
    String topic() default "";
272
}
273
```
274

275
[Logging](./logging.md)
276

277
### Utility Annotations
278

279
Practical utilities for common programming tasks including null checking, exception handling, and synchronization.
280

281
```java { .api }
282
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE})
283
@Retention(RetentionPolicy.SOURCE)
284
public @interface NonNull {
285
}
286

287
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
288
@Retention(RetentionPolicy.SOURCE)
289
public @interface SneakyThrows {
290
    Class<? extends Throwable>[] value() default java.lang.Throwable.class;
291
}
292

293
@Target(ElementType.METHOD)
294
@Retention(RetentionPolicy.SOURCE)
295
public @interface Synchronized {
296
    String value() default "";
297
}
298

299
@Target(ElementType.LOCAL_VARIABLE)
300
@Retention(RetentionPolicy.SOURCE)
301
public @interface Cleanup {
302
    String value() default "close";
303
}
304
```
305

306
[Utilities](./utilities.md)
307

308
### Type Inference
309

310
Local variable type inference for cleaner, more readable code.
311

312
```java { .api }
313
public final class val {
314
    private val() {}
315
}
316

317
public final class var {
318
    private var() {}
319
}
320
```
321

322
[Type Inference](./type-inference.md)
323

324
### Immutable Patterns
325

326
Generate immutable "wither" methods that create copies of objects with modified field values.
327

328
```java { .api }
329
@Target({ElementType.FIELD, ElementType.TYPE})
330
@Retention(RetentionPolicy.SOURCE)
331
public @interface With {
332
    AccessLevel value() default AccessLevel.PUBLIC;
333
    AnyAnnotation[] onMethod() default {};
334
    AnyAnnotation[] onParam() default {};
335
}
336
```
337

338
[Immutable Patterns](./immutable-patterns.md)
339

340
### Experimental Features
341

342
Advanced and experimental features including utility classes, field name constants, and enhanced builder patterns.
343

344
```java { .api }
345
@Target(ElementType.TYPE)
346
@Retention(RetentionPolicy.SOURCE)
347
public @interface SuperBuilder {
348
    String builderMethodName() default "builder";
349
    String buildMethodName() default "build";
350
    boolean toBuilder() default false;
351
    String setterPrefix() default "";
352
}
353

354
@Target(ElementType.TYPE)
355
@Retention(RetentionPolicy.SOURCE)
356
public @interface UtilityClass {
357
}
358

359
@Target(ElementType.TYPE)
360
@Retention(RetentionPolicy.SOURCE)
361
public @interface FieldNameConstants {
362
    AccessLevel level() default AccessLevel.PUBLIC;
363
    boolean asEnum() default false;
364
    String innerTypeName() default "Fields";
365
    boolean onlyExplicitlyIncluded() default false;
366
}
367
```
368

369
[Experimental Features](./experimental.md)
370

371
## Types
372

373
```java { .api }
374
public enum AccessLevel {
375
    PUBLIC, MODULE, PROTECTED, PACKAGE, PRIVATE, NONE
376
}
377

378
public enum CacheStrategy {
379
    NEVER, LAZY
380
}
381

382
public final class ConfigurationKeys {
383
    // Configuration key constants for lombok.config
384
}
385

386
public final class Lombok {
387
    /**
388
     * Throws any throwable 'sneakily' - you don't need to catch it, nor declare that you throw it onwards.
389
     * The exception is still thrown - javac will just stop whining about it.
390
     */
391
    public static RuntimeException sneakyThrow(Throwable t);
392
    
393
    /**
394
     * Returns the parameter directly.
395
     * This method can be used to prevent a static analyzer to determine the nullness of the passed parameter.
396
     */
397
    public static <T> T preventNullAnalysis(T value);
398
    
399
    /**
400
     * Ensures that the value is not null.
401
     * @throws NullPointerException with the message if the value is null.
402
     */
403
    public static <T> T checkNotNull(T value, String message);
404
}
405
```