0
# Configuration and Meta-Annotations
1

2
Auto-detection configuration, filtering, view support, and meta-annotation capabilities for creating custom annotation combinations.
3

4
## Capabilities
5

6
### JsonAutoDetect
7

8
Configure property auto-detection visibility levels for serialization and deserialization.
9

10
```java { .api }
11
/**
12
 * Configure property auto-detection visibility levels
13
 * @param getterVisibility Visibility level for getter methods
14
 * @param isGetterVisibility Visibility level for is-getter methods  
15
 * @param setterVisibility Visibility level for setter methods
16
 * @param creatorVisibility Visibility level for creator methods/constructors
17
 * @param fieldVisibility Visibility level for fields
18
 */
19
@JsonAutoDetect(JsonAutoDetect.Visibility getterVisibility = JsonAutoDetect.Visibility.DEFAULT,
20
                JsonAutoDetect.Visibility isGetterVisibility = JsonAutoDetect.Visibility.DEFAULT,
21
                JsonAutoDetect.Visibility setterVisibility = JsonAutoDetect.Visibility.DEFAULT,
22
                JsonAutoDetect.Visibility creatorVisibility = JsonAutoDetect.Visibility.DEFAULT,
23
                JsonAutoDetect.Visibility fieldVisibility = JsonAutoDetect.Visibility.DEFAULT)
24
public @interface JsonAutoDetect {
25
    
26
    enum Visibility {
27
        /** Detect members with any visibility */
28
        ANY,
29
        
30
        /** Detect non-private members (public, protected, package) */
31
        NON_PRIVATE,
32
        
33
        /** Detect protected and public members only */
34
        PROTECTED_AND_PUBLIC,
35
        
36
        /** Detect public members only */
37
        PUBLIC_ONLY,
38
        
39
        /** Do not auto-detect any members */
40
        NONE,
41
        
42
        /** Use default detection rules */
43
        DEFAULT;
44
        
45
        public boolean isVisible(Member member);
46
    }
47
}
48
```
49

50
**Usage Examples:**
51

52
```java
53
// Detect all fields regardless of visibility
54
@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
55
public class AllFieldsVisible {
56
    private String privateField;      // Will be serialized
57
    protected String protectedField;  // Will be serialized
58
    public String publicField;        // Will be serialized
59
}
60

61
// Only use explicitly annotated properties
62
@JsonAutoDetect(
63
    fieldVisibility = JsonAutoDetect.Visibility.NONE,
64
    getterVisibility = JsonAutoDetect.Visibility.NONE,
65
    setterVisibility = JsonAutoDetect.Visibility.NONE
66
)
67
public class ExplicitOnly {
68
    private String name;           // Won't be serialized
69
    private String description;    // Won't be serialized
70
    
71
    @JsonProperty
72
    private String title;          // Will be serialized (explicit annotation)
73
    
74
    @JsonGetter
75
    public String getName() {      // Will be serialized (explicit annotation)
76
        return name;
77
    }
78
}
79

80
// Custom visibility combinations
81
@JsonAutoDetect(
82
    fieldVisibility = JsonAutoDetect.Visibility.PROTECTED_AND_PUBLIC,
83
    getterVisibility = JsonAutoDetect.Visibility.PUBLIC_ONLY,
84
    setterVisibility = JsonAutoDetect.Visibility.ANY
85
)
86
public class MixedVisibility {
87
    private String privateField;      // Not serialized
88
    protected String protectedField;  // Serialized (field visibility)
89
    public String publicField;        // Serialized (field visibility)
90
    
91
    public String getPublicData() { return "data"; }    // Serialized (getter visibility)
92
    protected String getProtectedData() { return ""; }  // Not serialized (getter visibility)
93
    
94
    private void setPrivateValue(String value) { }      // Used for deserialization (setter visibility ANY)
95
}
96
```
97

98
### JsonFilter
99

100
Specify filter ID for property filtering during serialization.
101

102
```java { .api }
103
/**
104
 * Specify filter ID for property filtering
105
 * @param value Filter identifier used with SimpleFilterProvider
106
 */
107
@JsonFilter(String value)
108
public @interface JsonFilter;
109
```
110

111
**Usage Examples:**
112

113
```java
114
@JsonFilter("userFilter")
115
public class User {
116
    private String username;
117
    private String email;
118
    private String password;
119
    private String ssn;
120
    private String internalId;
121
}
122

123
// Usage with ObjectMapper:
124
SimpleFilterProvider filters = new SimpleFilterProvider();
125
filters.addFilter("userFilter", 
126
    SimpleBeanPropertyFilter.filterOutAllExcept("username", "email"));
127

128
ObjectMapper mapper = new ObjectMapper();
129
mapper.setFilterProvider(filters);
130

131
// Only username and email will be serialized
132
```
133

134
### JsonView
135

136
Define view classes for conditional property inclusion.
137

138
```java { .api }
139
/**
140
 * Define view classes for property inclusion
141
 * @param value Array of view classes
142
 */
143
@JsonView(Class<?>[] value = {})
144
public @interface JsonView;
145
```
146

147
**Usage Examples:**
148

149
```java
150
public class Views {
151
    public static class Public { }
152
    public static class Internal extends Public { }
153
    public static class Admin extends Internal { }
154
}
155

156
public class UserAccount {
157
    @JsonView(Views.Public.class)
158
    private String username;
159
    
160
    @JsonView(Views.Public.class)
161
    private String email;
162
    
163
    @JsonView(Views.Internal.class)
164
    private String fullName;
165
    
166
    @JsonView(Views.Internal.class)
167
    private LocalDateTime lastLogin;
168
    
169
    @JsonView(Views.Admin.class)
170
    private String passwordHash;
171
    
172
    @JsonView(Views.Admin.class)
173
    private List<String> permissions;
174
    
175
    // No view annotation - included in all views
176
    private String id;
177
}
178

179
// Usage:
180
ObjectMapper mapper = new ObjectMapper();
181

182
// Public view - only username, email, id
183
String publicJson = mapper.writerWithView(Views.Public.class)
184
    .writeValueAsString(user);
185

186
// Internal view - username, email, fullName, lastLogin, id
187
String internalJson = mapper.writerWithView(Views.Internal.class)
188
    .writeValueAsString(user);
189

190
// Admin view - all fields
191
String adminJson = mapper.writerWithView(Views.Admin.class)
192
    .writeValueAsString(user);
193
```
194

195
### JsonPropertyOrder
196

197
Define property serialization order.
198

199
```java { .api }
200
/**
201
 * Define property serialization order
202
 * @param value Array of property names in desired order
203
 * @param alphabetic Whether to order remaining properties alphabetically
204
 */
205
@JsonPropertyOrder(String[] value = {},
206
                   boolean alphabetic = false)
207
public @interface JsonPropertyOrder;
208
```
209

210
**Usage Examples:**
211

212
```java
213
@JsonPropertyOrder({"id", "name", "email", "created"})
214
public class OrderedUser {
215
    private String email;
216
    private String name;
217
    private Long id;
218
    private LocalDateTime created;
219
    private String department;  // Will appear after the ordered properties
220
}
221

222
@JsonPropertyOrder(alphabetic = true)
223
public class AlphabeticalUser {
224
    private String username;
225
    private String email;
226
    private String firstName;
227
    private String lastName;
228
    // All properties will be ordered alphabetically
229
}
230

231
@JsonPropertyOrder(value = {"priority", "status"}, alphabetic = true)
232
public class MixedOrderUser {
233
    private String status;
234
    private String priority;
235
    private String username;    // Alphabetical after priority/status
236
    private String email;       // Alphabetical
237
    private String firstName;   // Alphabetical
238
}
239
```
240

241
### JsonRootName
242

243
Define root element name when root wrapping is enabled.
244

245
```java { .api }
246
/**
247
 * Define root wrapper name
248
 * @param value Root element name
249
 * @param namespace XML namespace for root element
250
 */
251
@JsonRootName(String value,
252
              String namespace = "")
253
public @interface JsonRootName;
254
```
255

256
**Usage Examples:**
257

258
```java
259
@JsonRootName("user")
260
public class User {
261
    private String name;
262
    private String email;
263
}
264

265
// With root wrapping enabled:
266
// {"user": {"name": "John", "email": "john@email.com"}}
267

268
@JsonRootName(value = "product", namespace = "http://example.com/products")
269
public class Product {
270
    private String name;
271
    private BigDecimal price;
272
}
273

274
// With XML: <product xmlns="http://example.com/products"><name>...</name><price>...</price></product>
275
```
276

277
## Meta-Annotations
278

279
### JacksonAnnotation
280

281
Meta-annotation marking annotations as Jackson annotations.
282

283
```java { .api }
284
/**
285
 * Meta-annotation marking Jackson annotations for processing
286
 */
287
@JacksonAnnotation
288
public @interface JacksonAnnotation;
289
```
290

291
### JacksonAnnotationsInside
292

293
Meta-annotation for creating combination annotations.
294

295
```java { .api }
296
/**
297
 * Meta-annotation for creating combo annotations containing multiple Jackson annotations
298
 */
299
@JacksonAnnotationsInside
300
public @interface JacksonAnnotationsInside;
301
```
302

303
**Usage Examples:**
304

305
```java
306
// Custom combination annotation
307
@JacksonAnnotationsInside
308
@JsonIgnoreProperties(ignoreUnknown = true)
309
@JsonInclude(JsonInclude.Include.NON_NULL)
310
@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
311
public @interface FlexibleJson {
312
}
313

314
// Usage
315
@FlexibleJson
316
public class ApiResponse {
317
    private String status;
318
    private String message;
319
    private Object data;
320
    // Combines all the annotations from @FlexibleJson
321
}
322

323
// API-specific annotation
324
@JacksonAnnotationsInside
325
@JsonIgnoreProperties(ignoreUnknown = true)
326
@JsonPropertyOrder({"id", "type", "attributes"})
327
@JsonView(Views.Public.class)
328
public @interface ApiResource {
329
}
330

331
@ApiResource
332
public class ResourceEntity {
333
    private Long id;
334
    private String type;
335
    private Map<String, Object> attributes;
336
}
337
```
338

339
## Advanced Configuration Patterns
340

341
### Global Auto-Detection Configuration
342

343
```java
344
// Configure at class level
345
@JsonAutoDetect(
346
    fieldVisibility = JsonAutoDetect.Visibility.NONE,
347
    getterVisibility = JsonAutoDetect.Visibility.PUBLIC_ONLY,
348
    isGetterVisibility = JsonAutoDetect.Visibility.PUBLIC_ONLY,
349
    setterVisibility = JsonAutoDetect.Visibility.PUBLIC_ONLY,
350
    creatorVisibility = JsonAutoDetect.Visibility.PUBLIC_ONLY
351
)
352
public class RestrictedVisibility {
353
    // Only public getters/setters and explicitly annotated fields
354
}
355

356
// Or configure globally on ObjectMapper
357
ObjectMapper mapper = new ObjectMapper();
358
mapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.NONE);
359
mapper.setVisibility(PropertyAccessor.FIELD, JsonAutoDetect.Visibility.PUBLIC_ONLY);
360
```
361

362
### Complex View Hierarchies
363

364
```java
365
public class ViewHierarchy {
366
    public static class Basic { }
367
    public static class Detailed extends Basic { }
368
    public static class Admin extends Detailed { }
369
    
370
    public static class Export { }
371
    public static class AuditLog extends Export { }
372
}
373

374
public class Document {
375
    @JsonView({ViewHierarchy.Basic.class, ViewHierarchy.Export.class})
376
    private String title;
377
    
378
    @JsonView(ViewHierarchy.Detailed.class)
379
    private String content;
380
    
381
    @JsonView({ViewHierarchy.Admin.class, ViewHierarchy.AuditLog.class})
382
    private String createdBy;
383
    
384
    @JsonView(ViewHierarchy.AuditLog.class)
385
    private List<String> modifications;
386
}
387
```
388

389
### Dynamic Filtering
390

391
```java
392
@JsonFilter("dynamicFilter")
393
public class ConfigurableEntity {
394
    private String publicData;
395
    private String sensitiveData;
396
    private String internalData;
397
    private String adminData;
398
}
399

400
// Dynamic filter based on user role
401
public PropertyFilter createUserFilter(UserRole role) {
402
    switch (role) {
403
        case PUBLIC:
404
            return SimpleBeanPropertyFilter.filterOutAllExcept("publicData");
405
        case INTERNAL:
406
            return SimpleBeanPropertyFilter.serializeAllExcept("adminData");
407
        case ADMIN:
408
            return SimpleBeanPropertyFilter.serializeAll();
409
        default:
410
            return SimpleBeanPropertyFilter.filterOutAll();
411
    }
412
}
413
```
414

415
### JsonAutoDetect.Value
416

417
Configuration class for programmatic auto-detection control.
418

419
```java { .api }
420
/**
421
 * Value class for JsonAutoDetect configuration
422
 */
423
public static class JsonAutoDetect.Value implements JacksonAnnotationValue<JsonAutoDetect> {
424
    public static final JsonAutoDetect.Value DEFAULT;
425
    public static final JsonAutoDetect.Value NO_OVERRIDES;
426
    
427
    public static JsonAutoDetect.Value construct(
428
        JsonAutoDetect.Visibility getters,
429
        JsonAutoDetect.Visibility isGetters,
430
        JsonAutoDetect.Visibility setters,
431
        JsonAutoDetect.Visibility creators,
432
        JsonAutoDetect.Visibility fields);
433
    
434
    public JsonAutoDetect.Visibility getGetterVisibility();
435
    public JsonAutoDetect.Visibility getIsGetterVisibility();
436
    public JsonAutoDetect.Visibility getSetterVisibility();
437
    public JsonAutoDetect.Visibility getCreatorVisibility();
438
    public JsonAutoDetect.Visibility getFieldVisibility();
439
    
440
    public JsonAutoDetect.Value withGetterVisibility(JsonAutoDetect.Visibility v);
441
    public JsonAutoDetect.Value withIsGetterVisibility(JsonAutoDetect.Visibility v);
442
    public JsonAutoDetect.Value withSetterVisibility(JsonAutoDetect.Visibility v);
443
    public JsonAutoDetect.Value withCreatorVisibility(JsonAutoDetect.Visibility v);
444
    public JsonAutoDetect.Value withFieldVisibility(JsonAutoDetect.Visibility v);
445
}
446
```
447

448
### JsonClassDescription
449

450
Provide human-readable descriptions for classes, used in JSON schema generation.
451

452
```java { .api }
453
/**
454
 * Define human-readable description for annotated class
455
 * @param value Description text for the class
456
 */
457
@JsonClassDescription(String value = "")
458
public @interface JsonClassDescription;
459
```
460

461
**Usage Examples:**
462

463
```java
464
@JsonClassDescription("Represents a user account in the system")
465
public class User {
466
    private String username;
467
    private String email;
468
}
469

470
@JsonClassDescription("Configuration settings for application features")
471
@JsonIgnoreProperties(ignoreUnknown = true)
472
public class AppConfig {
473
    private boolean debugMode;
474
    private String environment;
475
    private Map<String, Object> features;
476
}
477

478
@JsonClassDescription("API response wrapper with status and data")
479
public class ApiResponse<T> {
480
    private String status;
481
    private T data;
482
    private List<String> errors;
483
}
484
```