0
# Immutables Value
1

2
Immutables Value is a Java annotation processing toolkit for generating immutable value objects at compile time. It enables developers to define value types using interfaces, abstract classes, or annotations, and automatically generates builder patterns, immutable implementations, and fluent APIs with compile-time validation.
3

4
## Package Information
5

6
- **Package Name**: org.immutables:value
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.immutables</groupId>
13
    <artifactId>value</artifactId>
14
    <version>2.10.1</version>
15
    <scope>provided</scope>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import org.immutables.value.Value;
23
```
24

25
For generated classes (typical pattern):
26
```java
27
// Generated class follows naming convention: Immutable + YourClassName
28
import com.example.ImmutablePerson;
29
```
30

31
## Basic Usage
32

33
```java
34
import org.immutables.value.Value;
35
import java.util.List;
36
import java.util.Optional;
37

38
// Define an immutable value type
39
@Value.Immutable
40
public interface Person {
41
    String name();
42
    int age();
43
    List<String> hobbies();
44
    Optional<String> email();
45
}
46

47
// Use the generated immutable implementation
48
Person person = ImmutablePerson.builder()
49
    .name("John Doe")
50
    .age(30)
51
    .addHobbies("reading", "swimming")
52
    .email("john@example.com")
53
    .build();
54

55
// Create modified copies
56
Person updatedPerson = person.withAge(31);
57

58
// Access values
59
String name = person.name();
60
int age = person.age();
61
List<String> hobbies = person.hobbies(); // Returns immutable list
62
```
63

64
## Architecture
65

66
Immutables Value is built around several key components:
67

68
- **Annotation Processing**: Compile-time code generation using standard Java annotation processing
69
- **Builder Pattern**: Automatic generation of fluent, type-safe builders for complex object construction
70
- **Immutable Implementation**: Generated classes with immutable state and structural sharing for efficient copying
71
- **Style System**: Comprehensive customization of naming conventions and generation behavior
72
- **Validation Framework**: Built-in support for constraint validation and invariant checking
73

74
The library generates immutable implementations that follow the "Immutable" prefix naming convention (customizable via Style), providing builders for construction, copy methods for modification, and standard object methods (equals, hashCode, toString).
75

76
## Capabilities
77

78
### Core Immutable Generation
79

80
Primary functionality for generating immutable value objects from abstract types with builder patterns, copy methods, and validation support.
81

82
```java { .api }
83
@interface Value.Immutable {
84
    boolean singleton() default false;
85
    boolean intern() default false;
86
    boolean copy() default true;
87
    boolean prehash() default false;
88
    boolean lazyhash() default false;
89
    boolean builder() default true;
90
}
91
```
92

93
[Core Immutable Generation](./core-immutable.md)
94

95
### Attribute Customization
96

97
Advanced attribute behavior including default values, lazy computation, derived values, and parameter configuration for flexible object modeling.
98

99
```java { .api }
100
@interface Value.Default { }
101
@interface Value.Lazy { }
102
@interface Value.Derived { }
103
@interface Value.Parameter {
104
    int order() default -1;
105
    boolean value() default true;
106
}
107
@interface Value.Auxiliary { }
108
```
109

110
[Attribute Customization](./attributes.md)
111

112
### Style and Configuration
113

114
Comprehensive styling system for customizing naming conventions, generation behavior, validation methods, and code structure.
115

116
```java { .api }
117
@interface Value.Style {
118
    // Naming templates (subset of 25+ naming options)
119
    String[] get() default "get*";
120
    String init() default "*";
121
    String with() default "with*";
122
    String add() default "add*";
123
    String builder() default "builder";
124
    String build() default "build";
125
    String copyOf() default "copyOf";
126
    String of() default "of";
127
    
128
    // Type naming templates (subset of 10+ type naming options)
129
    String typeImmutable() default "Immutable*";
130
    String typeBuilder() default "Builder";
131
    String typeModifiable() default "Modifiable*";
132
    
133
    // Behavioral configuration (subset of 50+ configuration options)
134
    boolean strictBuilder() default false;
135
    boolean stagedBuilder() default false;
136
    boolean allParameters() default false;
137
    boolean jdkOnly() default false;
138
    ValidationMethod validationMethod() default ValidationMethod.SIMPLE;
139
    ImplementationVisibility visibility() default ImplementationVisibility.SAME;
140
    BuilderVisibility builderVisibility() default BuilderVisibility.PUBLIC;
141
    
142
    // ... 60+ additional configuration options for advanced customization
143
}
144
```
145

146
[Style and Configuration](./style-configuration.md)
147

148
### Validation and Constraints
149

150
Built-in validation framework with constraint checking, invariant validation, and custom exception handling.
151

152
```java { .api }
153
@interface Value.Check { }
154
@interface Value.Redacted { }
155
@interface Value.NonAttribute { }
156

157
enum ValidationMethod {
158
    NONE, MANDATORY_ONLY, SIMPLE, VALIDATION_API
159
}
160

161
enum ImplementationVisibility {
162
    PUBLIC, SAME, PACKAGE, PRIVATE
163
}
164

165
enum BuilderVisibility {
166
    PUBLIC, SAME, PACKAGE
167
}
168
```
169

170
[Validation and Constraints](./validation.md)
171

172
### Advanced Features
173

174
Specialized features including modifiable companions, collection ordering, inclusion patterns, and enclosing type organization.
175

176
```java { .api }
177
@interface Value.Modifiable { }
178
@interface Value.Include {
179
    Class<?>[] value();
180
}
181
@interface Value.Enclosing { }
182
@interface Value.NaturalOrder { }
183
@interface Value.ReverseOrder { }
184
```
185

186
[Advanced Features](./advanced-features.md)
187

188
## Types
189

190
```java { .api }
191
@interface Value {
192
    // Main namespace annotation containing all nested annotations
193
}
194

195
@interface Generated {
196
    String from() default "";
197
    String generator() default "";
198
}
199
```