0
# Processing Options
1

2
APT compiler options for controlling code generation behavior, naming conventions, and processing rules. These options are passed to annotation processors via build tool configuration (Maven, Gradle) or IDE settings.
3

4
## Capabilities
5

6
### APT Options Constants
7

8
Central constants defining all supported annotation processing options.
9

10
```java { .api }
11
/**
12
 * APT options supported by Querydsl annotation processors
13
 */
14
public final class APTOptions {
15
    
16
    // Naming configuration
17
    public static final String QUERYDSL_PREFIX = "querydsl.prefix";
18
    public static final String QUERYDSL_SUFFIX = "querydsl.suffix"; 
19
    public static final String QUERYDSL_PACKAGE_SUFFIX = "querydsl.packageSuffix";
20
    
21
    // Code generation options
22
    public static final String QUERYDSL_CREATE_DEFAULT_VARIABLE = "querydsl.createDefaultVariable";
23
    public static final String QUERYDSL_ENTITY_ACCESSORS = "querydsl.entityAccessors";
24
    public static final String QUERYDSL_LIST_ACCESSORS = "querydsl.listAccessors";
25
    public static final String QUERYDSL_MAP_ACCESSORS = "querydsl.mapAccessors";
26
    
27
    // Property discovery options
28
    public static final String QUERYDSL_USE_FIELDS = "querydsl.useFields";
29
    public static final String QUERYDSL_USE_GETTERS = "querydsl.useGetters";
30
    public static final String QUERYDSL_UNKNOWN_AS_EMBEDDABLE = "querydsl.unknownAsEmbeddable";
31
    
32
    // Inclusion/exclusion options
33
    public static final String QUERYDSL_EXCLUDED_PACKAGES = "querydsl.excludedPackages";
34
    public static final String QUERYDSL_EXCLUDED_CLASSES = "querydsl.excludedClasses";
35
    public static final String QUERYDSL_INCLUDED_PACKAGES = "querydsl.includedPackages";
36
    public static final String QUERYDSL_INCLUDED_CLASSES = "querydsl.includedClasses";
37
    
38
    // Advanced configuration
39
    public static final String QUERYDSL_VARIABLE_NAME_FUNCTION_CLASS = "querydsl.variableNameFunctionClass";
40
}
41
```
42

43
### Naming Configuration Options
44

45
Control the naming conventions for generated query classes and their components.
46

47
```java { .api }
48
// Class name prefix (default: empty string)
49
public static final String QUERYDSL_PREFIX = "querydsl.prefix";
50

51
// Class name suffix (default: "Q")  
52
public static final String QUERYDSL_SUFFIX = "querydsl.suffix";
53

54
// Package suffix for generated classes (default: empty)
55
public static final String QUERYDSL_PACKAGE_SUFFIX = "querydsl.packageSuffix";
56
```
57

58
**Usage Examples:**
59

60
```xml
61
<!-- Maven APT plugin configuration -->
62
<plugin>
63
    <groupId>com.mysema.maven</groupId>
64
    <artifactId>apt-maven-plugin</artifactId>
65
    <configuration>
66
        <options>
67
            <!-- Generate QUser, QProduct, etc. (default) -->
68
            <querydsl.prefix></querydsl.prefix>
69
            <querydsl.suffix>Q</querydsl.suffix>
70
            
71
            <!-- Alternative: Generate QueryUser, QueryProduct -->
72
            <querydsl.prefix>Query</querydsl.prefix>
73
            <querydsl.suffix></querydsl.suffix>
74
            
75
            <!-- Put generated classes in separate package -->
76
            <querydsl.packageSuffix>.query</querydsl.packageSuffix>
77
        </options>
78
    </configuration>
79
</plugin>
80
```
81

82
**Naming Results:**
83
- **Default** (`prefix=""`, `suffix="Q"`): `User` → `QUser`
84
- **Query prefix** (`prefix="Query"`, `suffix=""`): `User` → `QueryUser`  
85
- **Package suffix**: `com.example.model.User` → `com.example.model.query.QUser`
86

87
### Code Generation Options
88

89
Control the structure and features of generated query classes.
90

91
```java { .api }
92
// Create static default variable instances (default: true)
93
public static final String QUERYDSL_CREATE_DEFAULT_VARIABLE = "querydsl.createDefaultVariable";
94

95
// Generate entity accessor methods (default: false)
96
public static final String QUERYDSL_ENTITY_ACCESSORS = "querydsl.entityAccessors";
97

98
// Generate list-specific accessor methods (default: false)  
99
public static final String QUERYDSL_LIST_ACCESSORS = "querydsl.listAccessors";
100

101
// Generate map-specific accessor methods (default: false)
102
public static final String QUERYDSL_MAP_ACCESSORS = "querydsl.mapAccessors";
103
```
104

105
**Code Generation Examples:**
106

107
```java
108
// With QUERYDSL_CREATE_DEFAULT_VARIABLE=true (default)
109
public class QUser extends EntityPathBase<User> {
110
    public static final QUser user = new QUser("user"); // Default variable created
111
    // ... properties
112
}
113

114
// With QUERYDSL_CREATE_DEFAULT_VARIABLE=false  
115
public class QUser extends EntityPathBase<User> {
116
    // No static default variable
117
    public QUser(String variable) { super(User.class, variable); }
118
    // ... properties
119
}
120

121
// With QUERYDSL_ENTITY_ACCESSORS=true
122
public class QUser extends EntityPathBase<User> {
123
    // Standard properties
124
    public final StringPath name = createString("name");
125
    public final ListPath<Order, QOrder> orders = this.<Order, QOrder>createList("orders", Order.class, QOrder.class, PathInits.DIRECT2);
126
    
127
    // Additional entity accessor methods generated
128
    public QOrder orders() { return new QOrder(forProperty("orders")); }
129
    public QOrder orders(int index) { return new QOrder(forProperty("orders", index)); }
130
}
131
```
132

133
### Property Discovery Options
134

135
Configure how annotation processors discover entity properties from source code.
136

137
```java { .api }
138
// Process field declarations (default: true)
139
public static final String QUERYDSL_USE_FIELDS = "querydsl.useFields";
140

141
// Process getter methods (default: true)
142
public static final String QUERYDSL_USE_GETTERS = "querydsl.useGetters";
143

144
// Treat unknown referenced types as embeddable (default: false)
145
public static final String QUERYDSL_UNKNOWN_AS_EMBEDDABLE = "querydsl.unknownAsEmbeddable";
146
```
147

148
**Property Discovery Modes:**
149

150
```xml
151
<!-- Process both fields and getters (default) -->
152
<querydsl.useFields>true</querydsl.useFields>
153
<querydsl.useGetters>true</querydsl.useGetters>
154

155
<!-- Fields only (ignore getter methods) -->
156
<querydsl.useFields>true</querydsl.useFields>
157
<querydsl.useGetters>false</querydsl.useGetters>
158

159
<!-- Getters only (ignore field declarations) -->
160
<querydsl.useFields>false</querydsl.useFields>
161
<querydsl.useGetters>true</querydsl.useGetters>
162
```
163

164
**Unknown Type Handling:**
165

166
```java
167
@Entity
168
public class User {
169
    private CustomType customProperty; // Unknown type
170
}
171

172
// With QUERYDSL_UNKNOWN_AS_EMBEDDABLE=false (default)
173
// CustomType ignored unless explicitly annotated
174

175
// With QUERYDSL_UNKNOWN_AS_EMBEDDABLE=true  
176
// CustomType treated as embeddable, QCustomType generated if possible
177
```
178

179
### Inclusion and Exclusion Options
180

181
Fine-grained control over which packages and classes are processed.
182

183
```java { .api }
184
// Comma-separated list of packages to exclude from processing
185
public static final String QUERYDSL_EXCLUDED_PACKAGES = "querydsl.excludedPackages";
186

187
// Comma-separated list of classes to exclude from processing
188
public static final String QUERYDSL_EXCLUDED_CLASSES = "querydsl.excludedClasses";
189

190
// Comma-separated list of packages to include (whitelist mode)
191
public static final String QUERYDSL_INCLUDED_PACKAGES = "querydsl.includedPackages";
192

193
// Comma-separated list of classes to include (whitelist mode)  
194
public static final String QUERYDSL_INCLUDED_CLASSES = "querydsl.includedClasses";
195
```
196

197
**Exclusion Examples:**
198

199
```xml
200
<!-- Exclude specific packages -->
201
<querydsl.excludedPackages>com.example.internal,com.example.test</querydsl.excludedPackages>
202

203
<!-- Exclude specific classes -->
204
<querydsl.excludedClasses>com.example.TempEntity,com.example.DebugEntity</querydsl.excludedClasses>
205

206
<!-- Whitelist mode - only process specified packages -->
207
<querydsl.includedPackages>com.example.model,com.example.domain</querydsl.includedPackages>
208

209
<!-- Whitelist mode - only process specified classes -->
210
<querydsl.includedClasses>com.example.User,com.example.Product</querydsl.includedClasses>
211
```
212

213
**Processing Rules:**
214
1. **Inclusion Priority**: If included packages/classes are specified, only those are processed
215
2. **Exclusion Filtering**: Excluded packages/classes are removed from processing
216
3. **Package Matching**: Uses `startsWith()` matching for package exclusions
217
4. **Class Matching**: Uses exact string matching for class exclusions
218

219
### Advanced Configuration Options
220

221
Specialized options for advanced customization scenarios.
222

223
```java { .api }
224
// Custom variable name function class (default: DefaultVariableNameFunction)
225
public static final String QUERYDSL_VARIABLE_NAME_FUNCTION_CLASS = "querydsl.variableNameFunctionClass";
226
```
227

228
**Custom Variable Naming:**
229

230
```java
231
// Implement custom variable naming strategy
232
public class CustomVariableNameFunction implements Function<EntityType, String> {
233
    @Override
234
    public String apply(EntityType entityType) {
235
        String className = entityType.getSimpleName();
236
        // Convert PascalCase to camelCase and make plural
237
        return className.substring(0, 1).toLowerCase() + 
238
               className.substring(1) + "s";
239
    }
240
}
241

242
// Configuration
243
<querydsl.variableNameFunctionClass>com.example.CustomVariableNameFunction</querydsl.variableNameFunctionClass>
244

245
// Result: User entity gets variable name "users" instead of "user"
246
public static final QUser users = new QUser("users");
247
```
248

249
### Build Tool Integration Examples
250

251
**Maven Integration:**
252

253
```xml
254
<plugin>
255
    <groupId>com.mysema.maven</groupId>
256
    <artifactId>apt-maven-plugin</artifactId>
257
    <version>1.1.3</version>
258
    <executions>
259
        <execution>
260
            <goals>
261
                <goal>process</goal>
262
            </goals>
263
            <configuration>
264
                <outputDirectory>target/generated-sources/java</outputDirectory>
265
                <processors>
266
                    <processor>com.mysema.query.apt.jpa.JPAAnnotationProcessor</processor>
267
                </processors>
268
                <options>
269
                    <querydsl.suffix>Q</querydsl.suffix>
270
                    <querydsl.packageSuffix>.query</querydsl.packageSuffix>
271
                    <querydsl.useFields>true</querydsl.useFields>
272
                    <querydsl.useGetters>false</querydsl.useGetters>
273
                    <querydsl.excludedPackages>com.example.internal</querydsl.excludedPackages>
274
                </options>
275
            </configuration>
276
        </execution>
277
    </executions>
278
</plugin>
279
```
280

281
**Gradle Integration:**
282

283
```gradle
284
compileJava {
285
    options.annotationProcessorPath = configurations.annotationProcessor
286
    options.compilerArgs += [
287
        '-Aquerydsl.suffix=Q',
288
        '-Aquerydsl.packageSuffix=.query', 
289
        '-Aquerydsl.useFields=true',
290
        '-Aquerydsl.useGetters=false'
291
    ]
292
}
293
```
294

295
**IDE Integration:**
296
Most IDEs automatically discover and apply annotation processor options from build configuration. For manual IDE configuration, add the options to the annotation processing settings using the `-A` prefix (e.g., `-Aquerydsl.suffix=Q`).