0
# Core Annotation Processing
1

2
Central annotation processing functionality providing the base framework for generating type-safe query classes from annotated Java entities. This module handles the core processing logic shared across all framework-specific processors.
3

4
## Capabilities
5

6
### AbstractQuerydslProcessor
7

8
Base abstract processor containing the main processing logic and lifecycle management.
9

10
```java { .api }
11
/**
12
 * Base class for Querydsl annotation processors, contains the main processing logic
13
 */
14
public abstract class AbstractQuerydslProcessor extends AbstractProcessor {
15
    
16
    /**
17
     * Main processing entry point called by the Java compiler
18
     * @param annotations Set of annotation types being processed
19
     * @param roundEnv Processing environment for current round
20
     * @return Whether annotations were claimed by this processor
21
     */
22
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv);
23
    
24
    /**
25
     * Create configuration for this processor - must be implemented by subclasses
26
     * @param roundEnv Processing environment
27
     * @return Configuration instance for this processor
28
     */
29
    protected abstract Configuration createConfiguration(RoundEnvironment roundEnv);
30
    
31
    /**
32
     * Get supported source version
33
     * @return Latest supported Java source version
34
     */
35
    public SourceVersion getSupportedSourceVersion();
36
    
37
    // Static utilities available to all processors
38
    public static Types TYPES;
39
    public static Elements ELEMENTS;
40
    public static final Boolean ALLOW_OTHER_PROCESSORS_TO_CLAIM_ANNOTATIONS = Boolean.FALSE;
41
}
42
```
43

44
**Processing Flow:**
45

46
1. **Initialization**: Set up type utilities and processing environment
47
2. **Configuration**: Create processor-specific configuration
48
3. **Element Collection**: Discover annotated classes and delegate methods  
49
4. **Model Creation**: Build intermediate entity type representations
50
5. **Property Analysis**: Extract fields and methods from entity classes
51
6. **Validation**: Validate entity models and property relationships
52
7. **Serialization**: Generate Q-class source code files
53

54
### QuerydslAnnotationProcessor
55

56
Default processor for general Querydsl annotations, handling the core Querydsl annotation set.
57

58
```java { .api }
59
/**
60
 * Default annotation processor for Querydsl annotations
61
 * Handles @QueryEntity, @QuerySupertype, @QueryEmbeddable, @QueryEmbedded, @QueryTransient
62
 */
63
@SupportedAnnotationTypes({"com.mysema.query.annotations.*"})
64
public class QuerydslAnnotationProcessor extends AbstractQuerydslProcessor {
65
    
66
    /**
67
     * Creates configuration for Querydsl-specific annotations
68
     * @param roundEnv Processing environment
69
     * @return DefaultConfiguration with Querydsl annotation mappings
70
     */
71
    @Override
72
    protected Configuration createConfiguration(RoundEnvironment roundEnv);
73
}
74
```
75

76
**Supported Annotations:**
77
- `@QueryEntity`: Marks a class as a query entity
78
- `@QuerySupertype`: Marks a superclass for query type inheritance
79
- `@QueryEmbeddable`: Marks a class as embeddable in queries
80
- `@QueryEmbedded`: Marks a field/property as embedded
81
- `@QueryTransient`: Marks a field/property to skip in query generation
82
- `@QueryEntities`: Package-level annotation listing entities
83

84
**Usage Example:**
85

86
```java
87
import com.mysema.query.annotations.QueryEntity;
88
import com.mysema.query.annotations.QueryTransient;
89

90
@QueryEntity
91
public class Product {
92
    private Long id;
93
    private String name;
94
    private BigDecimal price;
95
    
96
    @QueryTransient  // Will not be included in generated QProduct
97
    private transient String tempField;
98
}
99

100
// Generates QProduct.java with id, name, and price properties
101
```
102

103
### Type Processing Utilities
104

105
Core utilities for type analysis and extraction during annotation processing.
106

107
```java { .api }
108
/**
109
 * Utility for extracting TypeElement from TypeMirror instances
110
 */
111
public class TypeExtractor {
112
    public TypeExtractor(boolean create);
113
    public TypeElement visit(TypeMirror type);
114
}
115

116
/**
117
 * Static utility methods for type processing operations
118
 */
119
public class TypeUtils {
120
    public static boolean hasAnnotationOfType(TypeElement element, Set<Class<? extends Annotation>> annotations);
121
    public static AnnotationMirror getAnnotationMirrorOfType(Element element, Class<? extends Annotation> type);
122
    public static TypeMirror getAnnotationValueAsTypeMirror(AnnotationMirror annotation, String key);
123
    public static Collection<TypeElement> getAnnotationValuesAsElements(AnnotationMirror annotation, String key);
124
    public static boolean isAnnotationMirrorOfType(AnnotationMirror annotation, Class<? extends Annotation> type);
125
}
126

127
/**
128
 * Factory for creating extended type representations
129
 */
130
public class ExtendedTypeFactory {
131
    public ExtendedTypeFactory(ProcessingEnvironment env, Configuration conf, ...);
132
    public EntityType getEntityType(TypeMirror type, boolean create);
133
    public Collection<EntityType> getEntityTypes();
134
    public void extendTypes();
135
}
136

137
/**
138
 * Handler for processing TypeElement instances into entity models
139
 */
140
public class TypeElementHandler {
141
    public TypeElementHandler(Configuration conf, ExtendedTypeFactory factory, TypeMappings typeMappings, QueryTypeFactory queryTypeFactory);
142
    public EntityType handleEntityType(TypeElement element);
143
    public EntityType handleProjectionType(TypeElement element);
144
    public List<Parameter> transformParams(List<? extends VariableElement> parameters);
145
}
146
```
147

148
### Processing Context
149

150
Context object that maintains state during annotation processing rounds.
151

152
```java { .api }
153
/**
154
 * Processing context for storing intermediate results
155
 */
156
public class Context {
157
    // Entity type collections organized by category
158
    public final Map<String, EntityType> entityTypes = new HashMap<>();
159
    public final Map<String, EntityType> embeddableTypes = new HashMap<>();
160
    public final Map<String, EntityType> supertypes = new HashMap<>();
161
    public final Map<String, EntityType> extensionTypes = new HashMap<>(); 
162
    public final Map<String, EntityType> projectionTypes = new HashMap<>();
163
    public final Map<String, EntityType> allTypes = new HashMap<>();
164
    
165
    // Type element mappings for source tracking
166
    public final Map<String, Set<TypeElement>> typeElements = new HashMap<>();
167
    
168
    public void clean();
169
}
170
```
171

172
### Visitor Configuration
173

174
Controls how annotation processors discover and process entity properties.
175

176
```java { .api }
177
/**
178
 * Configuration for controlling property visitor behavior
179
 */
180
public enum VisitorConfig {
181
    /** Visit both fields and getters */
182
    ALL(true, true, true),
183
    /** Visit fields only */
184
    FIELDS_ONLY(true, false, true),
185
    /** Visit methods only */
186
    METHODS_ONLY(false, true, true),
187
    /** Visit none */
188
    NONE(false, false, false);
189
    
190
    public static VisitorConfig get(boolean fields, boolean methods);
191
    public static VisitorConfig get(boolean fields, boolean methods, VisitorConfig defaultConfig);
192
    
193
    public boolean visitFieldProperties();
194
    public boolean visitMethodProperties();
195
    public boolean visitConstructors();
196
}
197
```
198

199
**Property Discovery Modes:**
200
- **Fields Only**: Process only field declarations
201
- **Methods Only**: Process only getter/setter methods  
202
- **All**: Process both fields and methods (default)
203
- **None**: Skip property discovery (for extension types)
204

205
The processor automatically detects getter methods using naming conventions (`getPropertyName()`, `isPropertyName()` for booleans) and validates that they have no parameters and appropriate return types.