0
# Style and Naming Customization
1

2
Comprehensive style system for customizing generated class names, method names, builder patterns, and structural conventions. The `@Value.Style` annotation provides extensive control over how generated code looks and behaves.
3

4
## Capabilities
5

6
### Value.Style Annotation
7

8
Comprehensive style customization for generated code structure and naming conventions.
9

10
```java { .api }
11
/**
12
 * Comprehensive style customization for generated code.
13
 * Controls naming patterns, method signatures, and structural conventions
14
 * for all generated classes and methods.
15
 */
16
@Target({ElementType.TYPE, ElementType.PACKAGE})
17
@Retention(RetentionPolicy.SOURCE)
18
@interface Value.Style {
19
  /** Accessor method name patterns (e.g., "get*", "is*") */
20
  String[] get() default {};
21
  
22
  /** Builder setter method pattern */
23
  String init() default "*";
24
  
25
  /** Copy method pattern (withX methods) */
26
  String with() default "with*";
27
  
28
  /** Collection add method pattern */
29
  String add() default "add*";
30
  
31
  /** Collection addAll method pattern */
32
  String addAll() default "addAll*";
33
  
34
  /** Map put method pattern */
35
  String put() default "put*";
36
  
37
  /** Map putAll method pattern */
38
  String putAll() default "putAll*";
39
  
40
  /** Copy factory method name */
41
  String copyOf() default "copyOf";
42
  
43
  /** Static factory method name */
44
  String of() default "of";
45
  
46
  /** Singleton instance accessor name */
47
  String instance() default "instance";
48
  
49
  /** Builder factory method name */
50
  String builder() default "builder";
51
  
52
  /** Builder build method name */
53
  String build() default "build";
54
  
55
  /** Builder class name pattern */
56
  String typeBuilder() default "*Builder";
57
  
58
  /** Abstract type name detection patterns */
59
  String[] typeAbstract() default {};
60
  
61
  /** Immutable implementation name pattern */
62
  String typeImmutable() default "Immutable*";
63
  
64
  /** Umbrella/enclosing class name pattern */
65
  String typeImmutableEnclosing() default "*";
66
  
67
  /** Nested class name pattern */
68
  String typeImmutableNested() default "*";
69
  
70
  /** Default immutable annotation configuration */
71
  Immutable defaults() default @Immutable;
72
}
73
```
74

75
### Bean-Style Accessors
76

77
Configure bean-style getter patterns for enterprise compatibility.
78

79
**Usage Example:**
80

81
```java
82
import org.immutables.value.Value;
83

84
@Value.Style(get = {"get*", "is*"})
85
@Value.Immutable
86
public interface BeanStylePerson {
87
  String getName();
88
  int getAge();
89
  boolean isActive();
90
}
91

92
// Generated class has standard bean accessors
93
BeanStylePerson person = ImmutableBeanStylePerson.builder()
94
    .name("Alice")      // Builder uses simple names
95
    .age(30)
96
    .active(true)
97
    .build();
98

99
String name = person.getName();     // Bean-style getter
100
boolean active = person.isActive(); // Bean-style boolean getter
101
```
102

103
### Custom Builder Patterns
104

105
Customize builder method names and patterns.
106

107
**Usage Example:**
108

109
```java
110
import org.immutables.value.Value;
111

112
@Value.Style(
113
    init = "set*",           // Setter-style builder methods
114
    build = "create",        // Custom build method name
115
    typeBuilder = "*Factory" // Custom builder class name
116
)
117
@Value.Immutable
118
public interface CustomBuilderType {
119
  String name();
120
  int value();
121
}
122

123
// Usage with custom builder pattern
124
CustomBuilderType obj = ImmutableCustomBuilderType.factory()
125
    .setName("test")    // Custom setter pattern
126
    .setValue(42)
127
    .create();          // Custom build method
128
```
129

130
### Copy Method Customization
131

132
Customize copy method patterns and names.
133

134
**Usage Example:**
135

136
```java
137
@Value.Style(with = "update*")
138
@Value.Immutable
139
public interface UpdateablePerson {
140
  String name();
141
  int age();
142
  String email();
143
}
144

145
// Copy methods use custom pattern
146
UpdateablePerson person = ImmutableUpdateablePerson.builder()
147
    .name("Alice")
148
    .age(30)
149
    .email("alice@example.com")
150
    .build();
151

152
UpdateablePerson older = person.updateAge(31);        // updateAge instead of withAge
153
UpdateablePerson renamed = person.updateName("Alicia"); // updateName instead of withName
154
```
155

156
### Collection Method Patterns
157

158
Customize collection manipulation method names.
159

160
**Usage Example:**
161

162
```java
163
import org.immutables.value.Value;
164
import java.util.List;
165
import java.util.Map;
166
import java.util.Arrays;
167

168
@Value.Style(
169
    add = "append*",
170
    addAll = "appendAll*",
171
    put = "insert*",
172
    putAll = "insertAll*"
173
)
174
@Value.Immutable
175
public interface CustomCollectionType {
176
  List<String> items();
177
  Map<String, Integer> counts();
178
}
179

180
// Builder uses custom collection methods
181
CustomCollectionType obj = ImmutableCustomCollectionType.builder()
182
    .appendItems("a", "b", "c")           // appendItems instead of addItems
183
    .appendAllItems(Arrays.asList("d", "e")) // appendAllItems instead of addAllItems
184
    .insertCounts("key1", 10)             // insertCounts instead of putCounts
185
    .insertAllCounts(Map.of("key2", 20))  // insertAllCounts instead of putAllCounts
186
    .build();
187
```
188

189
### Type Name Patterns
190

191
Control generated class and interface naming.
192

193
**Usage Example:**
194

195
```java
196
@Value.Style(
197
    typeAbstract = {"Abstract*", "*Abstract"},  // Detect abstract types
198
    typeImmutable = "Concrete*",                // Custom implementation prefix
199
    typeBuilder = "*Creator"                    // Custom builder suffix
200
)
201
@Value.Immutable
202
public interface AbstractPersonData {
203
  String name();
204
  int age();
205
}
206

207
// Generated classes follow custom naming
208
// Implementation: ConcreteAbstractPersonData
209
// Builder: ConcreteAbstractPersonData.AbstractPersonDataCreator
210
AbstractPersonData person = ConcreteAbstractPersonData.creator()
211
    .name("Alice")
212
    .age(30)
213
    .build();
214
```
215

216
### Factory Method Customization
217

218
Customize static factory method names.
219

220
**Usage Example:**
221

222
```java
223
@Value.Style(
224
    of = "create",
225
    copyOf = "from",
226
    builder = "newBuilder"
227
)
228
@Value.Immutable
229
public interface FactoryStyleType {
230
  @Value.Parameter
231
  String value();
232
}
233

234
// Custom factory methods
235
FactoryStyleType obj1 = ImmutableFactoryStyleType.create("test");  // Custom 'of' method
236
FactoryStyleType obj2 = ImmutableFactoryStyleType.from(obj1);      // Custom 'copyOf' method
237
FactoryStyleType obj3 = ImmutableFactoryStyleType.newBuilder()     // Custom builder method
238
    .value("builder")
239
    .build();
240
```
241

242
### Package-Level Styles
243

244
Apply styles to entire packages via `package-info.java`.
245

246
**Usage Example:**
247

248
```java
249
// package-info.java
250
@Value.Style(
251
    get = {"get*"},
252
    typeImmutable = "Immutable*",
253
    visibility = ImplementationVisibility.PACKAGE
254
)
255
package com.example.model;
256

257
import org.immutables.value.Value;
258
```
259

260
### Nested Type Patterns
261

262
Control nested and enclosing class naming.
263

264
**Usage Example:**
265

266
```java
267
@Value.Style(
268
    typeImmutableEnclosing = "*Types",
269
    typeImmutableNested = "*"
270
)
271
public class ModelDefinitions {
272
  @Value.Immutable
273
  @Value.Nested
274
  public interface Person {
275
    String name();
276
  }
277
  
278
  @Value.Immutable
279
  @Value.Nested
280
  public interface Address {
281
    String street();
282
  }
283
}
284

285
// Generated: ModelDefinitionsTypes.Person, ModelDefinitionsTypes.Address
286
ModelDefinitionsTypes.Person person = ModelDefinitionsTypes.Person.builder()
287
    .name("Alice")
288
    .build();
289
```
290

291
### Default Configuration Override
292

293
Set default @Value.Immutable settings for styled types.
294

295
**Usage Example:**
296

297
```java
298
@Value.Style(
299
    defaults = @Value.Immutable(
300
        copy = false,           // Disable copy methods by default
301
        builder = true,         // Enable builders by default
302
        visibility = ImplementationVisibility.PACKAGE
303
    )
304
)
305
@Value.Immutable
306
public interface StyledType {
307
  String value();
308
}
309

310
// This type inherits the style defaults:
311
// - No copy methods generated
312
// - Builder enabled
313
// - Package-private implementation
314
```
315

316
## Pre-defined Style Patterns
317

318
### Enterprise/Bean Style
319

320
```java
321
@Value.Style(
322
    get = {"get*", "is*"},
323
    init = "set*",
324
    typeImmutable = "*Impl",
325
    visibility = ImplementationVisibility.PACKAGE
326
)
327
```
328

329
### Fluent Style
330

331
```java
332
@Value.Style(
333
    get = {},              // No get prefix
334
    with = "*",            // Simple copy method names
335
    typeImmutable = "*"    // No Immutable prefix
336
)
337
```
338

339
### Factory Style
340

341
```java
342
@Value.Style(
343
    of = "create",
344
    builder = "newBuilder",
345
    build = "build",
346
    typeBuilder = "*Factory"
347
)
348
```