0
# Querydsl APT
1

2
Querydsl APT (Annotation Processing Tool) is a compile-time source code generation library that creates type-safe query classes (Q-classes) from annotated Java entity classes. It processes annotations from multiple persistence frameworks including JPA, Hibernate, JDO, Morphia (MongoDB), and Spring Roo to generate query domain models for the Querydsl type-safe query framework.
3

4
## Package Information
5

6
- **Package Name**: querydsl-apt
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `com.mysema.querydsl:querydsl-apt:3.7.4` (Maven dependency)
10
- **License**: Apache License, Version 2.0
11

12
## Core Imports
13

14
```java
15
// For general Querydsl annotations
16
import com.mysema.query.apt.QuerydslAnnotationProcessor;
17

18
// For JPA entities
19
import com.mysema.query.apt.jpa.JPAAnnotationProcessor;
20

21
// For configuration
22
import com.mysema.query.apt.Configuration;
23
import com.mysema.query.apt.DefaultConfiguration;
24
```
25

26
## Basic Usage
27

28
The annotation processors are automatically discovered through the Java service provider interface. Add the appropriate processor to your build configuration:
29

30
**Maven Configuration:**
31

32
```xml
33
<!-- Maven APT plugin configuration -->
34
<plugin>
35
  <groupId>com.mysema.maven</groupId>
36
  <artifactId>apt-maven-plugin</artifactId>
37
  <version>1.1.3</version>
38
  <executions>
39
    <execution>
40
      <goals>
41
        <goal>process</goal>
42
      </goals>
43
      <configuration>
44
        <outputDirectory>target/generated-sources</outputDirectory>
45
        <processors>
46
          <processor>com.mysema.query.apt.jpa.JPAAnnotationProcessor</processor>
47
        </processors>
48
      </configuration>
49
    </execution>
50
  </executions>
51
</plugin>
52
```
53

54
**Gradle Configuration:**
55

56
```gradle
57
dependencies {
58
    annotationProcessor 'com.mysema.querydsl:querydsl-apt:3.7.4'
59
    compileOnly 'com.mysema.querydsl:querydsl-apt:3.7.4'
60
    implementation 'com.mysema.querydsl:querydsl-core:3.7.4'
61
}
62

63
compileJava {
64
    options.annotationProcessorPath = configurations.annotationProcessor
65
}
66
```
67

68
For JPA entities:
69

70
```java
71
import javax.persistence.Entity;
72
import javax.persistence.Id;
73

74
@Entity  
75
public class User {
76
    @Id
77
    private Long id;
78
    private String name;
79
    private String email;
80
}
81

82
// APT generates QUser.java:
83
// public class QUser extends EntityPathBase<User> {
84
//     public static final QUser user = new QUser("user");
85
//     public final NumberPath<Long> id = createNumber("id", Long.class);
86
//     public final StringPath name = createString("name");  
87
//     public final StringPath email = createString("email");
88
// }
89
```
90

91
## Architecture
92

93
Querydsl APT uses a multi-phase annotation processing architecture:
94

95
- **Annotation Processors**: Framework-specific processors that discover annotated classes
96
- **Configuration System**: Flexible configuration for customizing code generation behavior
97
- **Type Factory**: Creates intermediate representations of entity types and properties
98
- **Serializers**: Generate the final Q-class source code from entity models
99
- **Service Registration**: Automatic processor discovery via META-INF/services
100

101
The processing flow: Annotation Discovery → Entity Model Creation → Property Analysis → Code Generation → Source File Writing
102

103
## Capabilities
104

105
### Core Annotation Processing
106

107
Central annotation processing functionality providing the base framework for generating type-safe query classes from annotated entities.
108

109
```java { .api }
110
public abstract class AbstractQuerydslProcessor extends AbstractProcessor {
111
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv);
112
    protected abstract Configuration createConfiguration(RoundEnvironment roundEnv);
113
}
114

115
public class QuerydslAnnotationProcessor extends AbstractQuerydslProcessor {
116
    // Handles @QueryEntity, @QuerySupertype, @QueryEmbeddable, @QueryEmbedded, @QueryTransient
117
}
118
```
119

120
[Core Processing](./core-processing.md)
121

122
### Framework-Specific Processors
123

124
Specialized annotation processors for different persistence frameworks, each handling framework-specific annotations and conventions.
125

126
```java { .api }
127
public class JPAAnnotationProcessor extends AbstractQuerydslProcessor {
128
    // Handles @Entity, @MappedSuperclass, @Embeddable, @Embedded, @Transient
129
}
130

131
public class HibernateAnnotationProcessor extends JPAAnnotationProcessor {
132
    // Extends JPA support with Hibernate-specific annotations
133
}
134

135
public class JDOAnnotationProcessor extends AbstractQuerydslProcessor {
136
    // Handles @PersistenceCapable, @EmbeddedOnly, @NotPersistent
137
}
138

139
public class MorphiaAnnotationProcessor extends AbstractQuerydslProcessor {
140
    // Handles MongoDB Morphia annotations: @Entity, @Embedded, @Transient
141
}
142

143
public class RooAnnotationProcessor extends AbstractQuerydslProcessor {
144
    // Handles Spring Roo annotations: @RooJpaEntity, @RooJpaActiveRecord
145
}
146
```
147

148
[Framework Processors](./framework-processors.md)
149

150
### Configuration System
151

152
Comprehensive configuration system for customizing annotation processing behavior, code generation options, and framework-specific settings.
153

154
```java { .api }
155
public interface Configuration {
156
    TypeMappings getTypeMappings();
157
    Class<? extends Annotation> getEntityAnnotation();
158
    boolean isUseFields();
159
    boolean isUseGetters();
160
    String getNamePrefix();
161
    String getNameSuffix();
162
    void addExcludedPackage(String packageName);
163
    void addExcludedClass(String className);
164
}
165

166
public class DefaultConfiguration implements Configuration {
167
    public DefaultConfiguration(RoundEnvironment roundEnv, Map<String,String> options, ...);
168
    public void setNamePrefix(String namePrefix);
169
    public void setNameSuffix(String nameSuffix);
170
    public <T> void addCustomType(Class<T> type, Class<? extends Expression<T>> queryType);
171
}
172
```
173

174
[Configuration](./configuration.md)
175

176
### Processing Options
177

178
APT compiler options for controlling code generation behavior, naming conventions, and processing rules.
179

180
```java { .api }
181
public final class APTOptions {
182
    public static final String QUERYDSL_PREFIX = "querydsl.prefix";
183
    public static final String QUERYDSL_SUFFIX = "querydsl.suffix";
184
    public static final String QUERYDSL_PACKAGE_SUFFIX = "querydsl.packageSuffix";
185
    public static final String QUERYDSL_USE_FIELDS = "querydsl.useFields"; 
186
    public static final String QUERYDSL_USE_GETTERS = "querydsl.useGetters";
187
    public static final String QUERYDSL_EXCLUDED_PACKAGES = "querydsl.excludedPackages";
188
    public static final String QUERYDSL_EXCLUDED_CLASSES = "querydsl.excludedClasses";
189
}
190
```
191

192
[Processing Options](./processing-options.md)
193

194
## Exception Handling
195

196
```java { .api }
197
public class APTException extends RuntimeException {
198
    public APTException(String msg);
199
    public APTException(String msg, Throwable t);
200
    public APTException(Throwable t);
201
}
202

203
public class UnsupportedTypeException extends APTException {
204
    public UnsupportedTypeException(TypeMirror mirror);
205
}
206
```
207

208
**Exception Hierarchy:**
209
- `APTException` extends `RuntimeException` - base exception for APT processing errors
210
- `UnsupportedTypeException` extends `APTException` - thrown for unsupported type scenarios
211

212
**Common processing errors include:**
213
- Missing required annotations on entity classes → `APTException`
214
- Unsupported type mappings in entity properties → `UnsupportedTypeException`
215
- Configuration validation failures → `APTException`
216
- Source file generation conflicts → `APTException`
217
- Illegal property initialization paths → Error messages to compiler