0
# Configuration System
1

2
Comprehensive configuration system for customizing annotation processing behavior, code generation options, and framework-specific settings. The configuration controls how entities are discovered, processed, and serialized into Q-class files.
3

4
## Capabilities
5

6
### Configuration Interface
7

8
Core configuration interface defining all customization options for annotation processing.
9

10
```java { .api }
11
/**
12
 * Configuration interface for APT-based Querydsl code generation
13
 */
14
public interface Configuration {
15
    
16
    // Annotation handling
17
    Class<? extends Annotation> getEntityAnnotation();
18
    Class<? extends Annotation> getAlternativeEntityAnnotation();
19
    Set<Class<? extends Annotation>> getEntityAnnotations();
20
    Class<? extends Annotation> getEntitiesAnnotation();
21
    Class<? extends Annotation> getSuperTypeAnnotation();
22
    Class<? extends Annotation> getEmbeddableAnnotation();
23
    Class<? extends Annotation> getEmbeddedAnnotation();
24
    Class<? extends Annotation> getSkipAnnotation();
25
    
26
    // Property discovery configuration
27
    boolean isUseFields();
28
    boolean isUseGetters();
29
    boolean isUnknownAsEmbedded();
30
    VisitorConfig getConfig(TypeElement e, List<? extends Element> elements);
31
    
32
    // Validation methods
33
    boolean isValidField(VariableElement field);
34
    boolean isValidGetter(ExecutableElement getter);
35
    boolean isValidConstructor(ExecutableElement constructor);
36
    boolean isBlockedField(VariableElement field);
37
    boolean isBlockedGetter(ExecutableElement getter);
38
    
39
    // Type and naming configuration
40
    TypeMappings getTypeMappings();
41
    QueryTypeFactory getQueryTypeFactory();
42
    String getNamePrefix();
43
    String getNameSuffix();
44
    Function<EntityType, String> getVariableNameFunction();
45
    
46
    // Serialization configuration
47
    Serializer getEntitySerializer();
48
    Serializer getEmbeddableSerializer();
49
    Serializer getSupertypeSerializer();
50
    Serializer getDTOSerializer();
51
    SerializerConfig getSerializerConfig(EntityType entityType);
52
    
53
    // Exclusion/inclusion rules
54
    void addExcludedPackage(String packageName);
55
    void addExcludedClass(String className);
56
    boolean isExcludedPackage(String packageName);
57
    boolean isExcludedClass(String className);
58
    
59
    // Type inspection
60
    TypeMirror getRealType(ExecutableElement method);
61
    TypeMirror getRealType(VariableElement field);
62
    void inspect(Element element, Annotations annotations);
63
    
64
    // Processing modes
65
    boolean isStrictMode();
66
    Collection<String> getKeywords();
67
}
68
```
69

70
### Default Configuration
71

72
Standard implementation of the Configuration interface with sensible defaults and extensive customization options.
73

74
```java { .api }
75
/**
76
 * Default implementation of the Configuration interface
77
 */
78
public class DefaultConfiguration implements Configuration {
79
    
80
    /**
81
     * Primary constructor for creating configuration instance
82
     * @param roundEnv Processing environment for current round
83
     * @param options Processor options from build configuration
84
     * @param keywords Reserved keywords to avoid in generated code  
85
     * @param entitiesAnn Package-level entities annotation (nullable)
86
     * @param entityAnn Primary entity annotation class
87
     * @param superTypeAnn Supertype annotation class (nullable)
88
     * @param embeddableAnn Embeddable annotation class (nullable)  
89
     * @param embeddedAnn Embedded annotation class (nullable)
90
     * @param skipAnn Skip/transient annotation class (nullable)
91
     */
92
    public DefaultConfiguration(
93
        RoundEnvironment roundEnv,
94
        Map<String, String> options,
95
        Collection<String> keywords,
96
        Class<? extends Annotation> entitiesAnn,
97
        Class<? extends Annotation> entityAnn,
98
        Class<? extends Annotation> superTypeAnn,
99
        Class<? extends Annotation> embeddableAnn,
100
        Class<? extends Annotation> embeddedAnn,
101
        Class<? extends Annotation> skipAnn);
102
    
103
    // Naming configuration methods
104
    public void setNamePrefix(String namePrefix);
105
    public void setNameSuffix(String nameSuffix);
106
    public void setUseFields(boolean useFields);
107
    public void setUseGetters(boolean useGetters);
108
    public void setStrictMode(boolean strictMode);
109
    public void setUnknownAsEmbedded(boolean unknownAsEmbedded);
110
    
111
    // Alternative annotation support
112
    public void setAlternativeEntityAnnotation(Class<? extends Annotation> ann);
113
    
114
    // Custom type mappings
115
    public <T> void addCustomType(Class<T> type, Class<? extends Expression<T>> queryType);
116
}
117
```
118

119
**Configuration Creation Example:**
120

121
```java
122
// JPA Configuration example
123
RoundEnvironment roundEnv = ...; // From processor
124
Map<String, String> options = ...; // From build configuration
125

126
Configuration config = new DefaultConfiguration(
127
    roundEnv,
128
    options,
129
    Collections.emptySet(), // keywords
130
    null, // entitiesAnn
131
    Entity.class, // entityAnn - javax.persistence.Entity
132
    MappedSuperclass.class, // superTypeAnn
133
    Embeddable.class, // embeddableAnn  
134
    Embedded.class, // embeddedAnn
135
    Transient.class  // skipAnn
136
);
137

138
// Customize naming
139
config.setNamePrefix(""); // Default empty
140
config.setNameSuffix("Q"); // Default "Q" 
141
config.setUseFields(true);
142
config.setUseGetters(true);
143
```
144

145
### Framework-Specific Configurations
146

147
Specialized configuration classes for different persistence frameworks.
148

149
```java { .api }
150
/**
151
 * JPA-specific configuration
152
 */
153
public class JPAConfiguration extends DefaultConfiguration {
154
    public JPAConfiguration(RoundEnvironment roundEnv, 
155
                           Map<String,String> options,
156
                           Class<? extends Annotation> entity,
157
                           Class<? extends Annotation> superType,
158
                           Class<? extends Annotation> embeddable,
159
                           Class<? extends Annotation> embedded,
160
                           Class<? extends Annotation> skip);
161
}
162

163
/**
164
 * Hibernate-specific configuration with enhanced type support
165
 */
166
public class HibernateConfiguration extends JPAConfiguration {
167
    public HibernateConfiguration(RoundEnvironment roundEnv, 
168
                                 Map<String,String> options,
169
                                 Class<? extends Annotation> entity,
170
                                 Class<? extends Annotation> superType,
171
                                 Class<? extends Annotation> embeddable,
172
                                 Class<? extends Annotation> embedded,
173
                                 Class<? extends Annotation> skip) throws ClassNotFoundException;
174
}
175

176
/**
177
 * JDO-specific configuration
178
 */  
179
public class JDOConfiguration extends DefaultConfiguration {
180
    public JDOConfiguration(RoundEnvironment roundEnv,
181
                           Map<String,String> options,
182
                           Class<? extends Annotation> entities,
183
                           Class<? extends Annotation> entity,
184
                           Class<? extends Annotation> superType,
185
                           Class<? extends Annotation> embeddable,
186
                           Class<? extends Annotation> embedded,
187
                           Class<? extends Annotation> skip);
188
}
189
```
190

191
### Property Discovery Configuration
192

193
Controls how annotation processors discover and process entity properties from classes.
194

195
```java { .api }
196
/**
197
 * Configuration for controlling property visitor behavior
198
 */
199
public class VisitorConfig {
200
    // Pre-defined visitor configurations
201
    public static final VisitorConfig ALL = new VisitorConfig(true, true);
202
    public static final VisitorConfig FIELDS_ONLY = new VisitorConfig(true, false);
203
    public static final VisitorConfig METHODS_ONLY = new VisitorConfig(false, true);
204
    public static final VisitorConfig NONE = new VisitorConfig(false, false);
205
    
206
    /**
207
     * Whether to visit and process field properties
208
     * @return true if fields should be processed
209
     */
210
    public boolean visitFieldProperties();
211
    
212
    /**
213
     * Whether to visit and process method properties (getters)
214
     * @return true if methods should be processed  
215
     */
216
    public boolean visitMethodProperties();
217
}
218
```
219

220
**Property Discovery Rules:**
221

222
**Field Processing** (`visitFieldProperties() == true`):
223
- Process all non-static, non-transient fields
224
- Skip fields marked with skip annotation (e.g., `@Transient`)  
225
- Include fields marked with `@QueryType` regardless of modifiers
226

227
**Method Processing** (`visitMethodProperties() == true`):
228
- Process getter methods matching naming conventions:
229
  - `getPropertyName()` for general properties
230
  - `isPropertyName()` for boolean properties
231
- Methods must have no parameters and appropriate return types
232
- Skip methods marked with skip annotation
233
- Include methods marked with `@QueryType` regardless of modifiers
234

235
### Custom Type Mappings
236

237
Configure custom type mappings for domain-specific types or framework extensions.
238

239
```java { .api }
240
/**
241
 * Type mappings configuration for custom type handling
242
 */
243
public interface TypeMappings {
244
    void register(Type type, Type queryType);
245
    Type getPathType(EntityType entityType, EntityType model, boolean forProperty);
246
}
247

248
/**
249
 * Query type factory for creating path types
250
 */
251
public interface QueryTypeFactory {
252
    Type create(EntityType model);
253
}
254
```
255

256
**Custom Type Example:**
257

258
```java
259
// Add custom type mapping for spatial types
260
DefaultConfiguration config = new DefaultConfiguration(...);
261

262
// Map java.awt.Point to custom query expression type
263
config.addCustomType(java.awt.Point.class, PointExpression.class);
264

265
// Map custom domain types
266
config.addCustomType(Money.class, MoneyExpression.class);
267
config.addCustomType(EmailAddress.class, StringExpression.class);
268
```
269

270
### Validation Configuration
271

272
Configure field and method validation rules for entity processing.
273

274
```java { .api }
275
/**
276
 * Field validation - determines which fields are processed
277
 * @param field Field element to validate
278
 * @return true if field should be included in query type
279
 */
280
boolean isValidField(VariableElement field);
281

282
/**
283
 * Method validation - determines which methods are processed  
284
 * @param getter Method element to validate
285
 * @return true if method should be included in query type
286
 */
287
boolean isValidGetter(ExecutableElement getter);
288

289
/**
290
 * Constructor validation - for projection types
291
 * @param constructor Constructor element to validate
292
 * @return true if constructor is valid for projections
293
 */
294
boolean isValidConstructor(ExecutableElement constructor);
295
```
296

297
**Default Validation Rules:**
298

299
**Valid Fields:**
300
- Non-static, non-transient fields
301
- Fields not marked with skip annotation
302
- Fields explicitly marked with `@QueryType` (overrides other rules)
303

304
**Valid Getters:**
305
- Non-static methods with getter naming convention
306
- Methods not marked with skip annotation  
307
- Methods explicitly marked with `@QueryType` (overrides other rules)
308

309
**Valid Constructors (for projections):**
310
- Public constructors
311
- Marked with `@QueryProjection` annotation
312
- Have at least one parameter
313

314
### Serializer Configuration
315

316
Configure how entity models are serialized into Java source code.
317

318
```java { .api }
319
/**
320
 * Configuration for controlling code generation serialization  
321
 */
322
public interface SerializerConfig {
323
    boolean entityAccessors();
324
    boolean listAccessors();
325
    boolean mapAccessors(); 
326
    boolean createDefaultVariable();
327
    String javadocSuffix();
328
}
329

330
/**
331
 * Simple serializer configuration implementation
332
 */
333
public class SimpleSerializerConfig implements SerializerConfig {
334
    public SimpleSerializerConfig(boolean entityAccessors,
335
                                 boolean listAccessors,
336
                                 boolean mapAccessors,
337
                                 boolean createDefaultVariable,
338
                                 String javadocSuffix);
339
    
340
    public static SerializerConfig getConfig(Config annotation);
341
}
342
```
343

344
**Serialization Options:**
345
- **Entity Accessors**: Generate accessor methods for entity references
346
- **List Accessors**: Generate specialized methods for list properties
347
- **Map Accessors**: Generate specialized methods for map properties  
348
- **Default Variable**: Create static default instance (e.g., `QUser.user`)
349
- **Javadoc Suffix**: Custom suffix for generated Javadoc comments