0
# Configuration Options
1

2
Comprehensive configuration options for controlling code generation behavior, including field visibility, annotations, template customization, and logical type support.
3

4
## Capabilities
5

6
### Field Visibility Configuration
7

8
Control the visibility and access pattern of generated class fields.
9

10
```java { .api }
11
/**
12
 * Field visibility options for generated classes
13
 */
14
public enum FieldVisibility {
15
    /** Generate public fields */
16
    PUBLIC,
17
    /** Generate private fields */
18
    PRIVATE
19
}
20

21
/** Set field visibility (PUBLIC or PRIVATE) */
22
public void setFieldVisibility(FieldVisibility fieldVisibility);
23

24
/** Check if fields should be public */
25
public boolean publicFields();
26

27
/** Check if fields should be private */
28
public boolean privateFields();
29
```
30

31
### Setter and Getter Configuration
32

33
Control generation of accessor methods for class fields.
34

35
```java { .api }
36
/** Check if setters should be created */
37
public boolean isCreateSetters();
38

39
/** Enable/disable setter creation */
40
public void setCreateSetters(boolean createSetters);
41

42
/** Check if optional getters should be created */
43
public boolean isCreateOptionalGetters();
44

45
/** Enable/disable optional getters */
46
public void setCreateOptionalGetters(boolean createOptionalGetters);
47

48
/** Check if getters return Optional */
49
public boolean isGettersReturnOptional();
50

51
/** Configure Optional return types for getters */
52
public void setGettersReturnOptional(boolean gettersReturnOptional);
53

54
/** Check if optional getters are only for nullable fields */
55
public boolean isOptionalGettersForNullableFieldsOnly();
56

57
/** Configure optional getters scope to nullable fields only */
58
public void setOptionalGettersForNullableFieldsOnly(boolean optionalGettersForNullableFieldsOnly);
59
```
60

61
### Constructor Configuration
62

63
Control constructor generation patterns.
64

65
```java { .api }
66
/** Check if all-args constructor should be created */
67
public boolean isCreateAllArgsConstructor();
68
```
69

70
### Annotation Configuration
71

72
Control generation of annotations for null safety and validation.
73

74
```java { .api }
75
/** Check if null-safe annotations should be created */
76
public boolean isCreateNullSafeAnnotations();
77

78
/** Enable/disable null-safe annotations */
79
public void setCreateNullSafeAnnotations(boolean createNullSafeAnnotations);
80
```
81

82
### Template Customization
83

84
Customize the code generation templates and output formatting.
85

86
```java { .api }
87
/** Set additional Velocity template tools */
88
public void setAdditionalVelocityTools(List<Object> additionalVelocityTools);
89

90
/** Set custom template directory for code generation */
91
public void setTemplateDir(String templateDir);
92

93
/** Set file suffix for generated classes */
94
public void setSuffix(String suffix);
95
```
96

97
### Logical Type Support
98

99
Configure support for Avro logical types and custom conversions.
100

101
```java { .api }
102
/** Enable decimal logical type support */
103
public void setEnableDecimalLogicalType(boolean enableDecimalLogicalType);
104

105
/** Add custom logical type conversion class */
106
public void addCustomConversion(Class<?> conversionClass);
107

108
/** Get conversion classes used by schema */
109
public Collection<String> getUsedConversionClasses(Schema schema);
110

111
/** Get custom logical type factories used by schema */
112
public Map<String, String> getUsedCustomLogicalTypeFactories(Schema schema);
113
```
114

115
### String Type Configuration (Ant Tasks)
116

117
Control string representation in generated classes when using Ant tasks.
118

119
```java { .api }
120
/** Set string type for generated classes (CharSequence, String, Utf8) */
121
public void setStringType(GenericData.StringType stringType);
122

123
/** Get current string type setting */
124
public GenericData.StringType getStringType();
125
```
126

127
## Configuration Examples
128

129
### Private Fields with Setters and Getters
130

131
```java
132
import org.apache.avro.compiler.specific.SpecificCompiler;
133
import org.apache.avro.compiler.specific.SpecificCompiler.FieldVisibility;
134

135
SpecificCompiler compiler = new SpecificCompiler(schema);
136

137
// Configure private fields with accessors
138
compiler.setFieldVisibility(FieldVisibility.PRIVATE);
139
compiler.setCreateSetters(true);
140
compiler.setCreateOptionalGetters(true);
141

142
compiler.compileToDestination(schemaFile, outputDir);
143
```
144

145
Generated code:
146
```java
147
public class User extends SpecificRecordBase implements SpecificRecord {
148
    private CharSequence name;  // Private field
149
    private Integer age;        // Private field
150
    
151
    // Setter methods
152
    public void setName(CharSequence name) { this.name = name; }
153
    public void setAge(Integer age) { this.age = age; }
154
    
155
    // Getter methods
156
    public CharSequence getName() { return name; }
157
    public Integer getAge() { return age; }
158
    
159
    // Optional getters
160
    public Optional<CharSequence> getNameOptional() { return Optional.ofNullable(name); }
161
    public Optional<Integer> getAgeOptional() { return Optional.ofNullable(age); }
162
}
163
```
164

165
### Optional Return Types Configuration
166

167
```java
168
SpecificCompiler compiler = new SpecificCompiler(schema);
169

170
// Configure getters to return Optional
171
compiler.setGettersReturnOptional(true);
172
compiler.setOptionalGettersForNullableFieldsOnly(true);
173

174
compiler.compileToDestination(schemaFile, outputDir);
175
```
176

177
Generated code:
178
```java
179
// For nullable fields
180
public Optional<String> getEmail() { return Optional.ofNullable(email); }
181

182
// For non-nullable fields (if optionalGettersForNullableFieldsOnly is true)
183
public String getName() { return name; }  // Returns String directly
184
```
185

186
### Null-Safe Annotations
187

188
```java
189
SpecificCompiler compiler = new SpecificCompiler(schema);
190

191
// Enable null-safe annotations
192
compiler.setCreateNullSafeAnnotations(true);
193

194
compiler.compileToDestination(schemaFile, outputDir);
195
```
196

197
Generated code:
198
```java
199
import javax.annotation.Nullable;
200
import javax.annotation.Nonnull;
201

202
public class User extends SpecificRecordBase {
203
    @Nullable
204
    private CharSequence email;
205
    
206
    @Nonnull
207
    private CharSequence name;
208
    
209
    public void setEmail(@Nullable CharSequence email) { this.email = email; }
210
    public void setName(@Nonnull CharSequence name) { this.name = name; }
211
}
212
```
213

214
### Logical Type Configuration
215

216
```java
217
import org.apache.avro.Conversions;
218
import org.apache.avro.data.TimeConversions;
219

220
SpecificCompiler compiler = new SpecificCompiler(schema);
221

222
// Enable decimal logical type
223
compiler.setEnableDecimalLogicalType(true);
224

225
// Add custom conversions
226
compiler.addCustomConversion(Conversions.DecimalConversion.class);
227
compiler.addCustomConversion(TimeConversions.DateConversion.class);
228
compiler.addCustomConversion(TimeConversions.TimeMillisConversion.class);
229
compiler.addCustomConversion(TimeConversions.TimeMicrosConversion.class);
230
compiler.addCustomConversion(TimeConversions.TimestampMillisConversion.class);
231
compiler.addCustomConversion(TimeConversions.TimestampMicrosConversion.class);
232

233
compiler.compileToDestination(schemaFile, outputDir);
234
```
235

236
### Custom Template Configuration
237

238
```java
239
import java.util.*;
240

241
SpecificCompiler compiler = new SpecificCompiler(schema);
242

243
// Set custom template directory
244
compiler.setTemplateDir("/path/to/custom/templates");
245

246
// Add custom Velocity tools
247
List<Object> velocityTools = new ArrayList<>();
248
velocityTools.add(new CustomStringUtil());
249
velocityTools.add(new CustomDateUtil());
250
compiler.setAdditionalVelocityTools(velocityTools);
251

252
// Custom file suffix
253
compiler.setSuffix(".generated.java");
254

255
compiler.compileToDestination(schemaFile, outputDir);
256
```
257

258
### Complete Configuration Example
259

260
```java
261
import org.apache.avro.Schema;
262
import org.apache.avro.compiler.specific.SpecificCompiler;
263
import org.apache.avro.compiler.specific.SpecificCompiler.FieldVisibility;
264
import org.apache.avro.Conversions;
265
import java.util.*;
266

267
Schema schema = new Schema.Parser().parse(new File("user.avsc"));
268
SpecificCompiler compiler = new SpecificCompiler(schema);
269

270
// Field visibility and accessors
271
compiler.setFieldVisibility(FieldVisibility.PRIVATE);
272
compiler.setCreateSetters(true);
273
compiler.setCreateOptionalGetters(true);
274
compiler.setGettersReturnOptional(false);  // Optional getters separate from regular getters
275
compiler.setOptionalGettersForNullableFieldsOnly(true);
276

277
// Annotations
278
compiler.setCreateNullSafeAnnotations(true);
279

280
// Logical types
281
compiler.setEnableDecimalLogicalType(true);
282
compiler.addCustomConversion(Conversions.DecimalConversion.class);
283

284
// Template customization
285
compiler.setSuffix(".java");
286
List<Object> tools = Arrays.asList(new CustomUtilityTool());
287
compiler.setAdditionalVelocityTools(tools);
288

289
compiler.compileToDestination(new File("user.avsc"), new File("src/main/java"));
290
```
291

292
### Ant Task Configuration
293

294
```xml
295
<!-- Configure string type in Ant task -->
296
<schema destdir="src/main/java" stringType="String">
297
    <fileset dir="src/main/avro">
298
        <include name="**/*.avsc"/>
299
    </fileset>
300
</schema>
301

302
<!-- All SpecificCompiler configuration options can be set as task attributes -->
303
<!-- Note: Most advanced options require direct SpecificCompiler usage -->
304
```
305

306
## Configuration Impact
307

308
### Field Visibility Effects
309

310
| Configuration | Generated Code | Access Pattern |
311
|---------------|----------------|----------------|
312
| `PUBLIC` | `public CharSequence name;` | Direct field access |
313
| `PRIVATE` + `setCreateSetters(true)` | `private CharSequence name; + setters/getters` | Method access only |
314
315
### Optional Getter Behavior
316

317
| Configuration | Nullable Field | Non-nullable Field |
318
|---------------|----------------|-------------------|
319
| `setCreateOptionalGetters(true)` | `Optional<T> getFieldOptional()` | `Optional<T> getFieldOptional()` |
320
| `setOptionalGettersForNullableFieldsOnly(true)` | `Optional<T> getFieldOptional()` | No optional getter |
321
322
### String Type Effects
323

324
| StringType | Generated Field Type | Usage |
325
|------------|---------------------|-------|
326
| `CharSequence` (default) | `CharSequence` | Generic string interface |
327
| `String` | `String` | Concrete string class |
328
| `Utf8` | `Utf8` | Avro's optimized string type |
329
330
## Best Practices
331

332
1. **Use private fields with setters** for encapsulation in production code
333
2. **Enable null-safe annotations** when using null-checking tools
334
3. **Configure logical types** to match your data precision requirements
335
4. **Use Optional getters selectively** to avoid API bloat
336
5. **Customize templates** only when standard generation doesn't meet requirements
337
6. **Test configuration changes** with sample schemas before applying to production