-
-
Notifications
You must be signed in to change notification settings - Fork 327
/
JsonMerge.java
65 lines (63 loc) · 3.07 KB
/
JsonMerge.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
package com.fasterxml.jackson.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Annotation to specify whether annotated property value should use "merging" approach:
* merging meaning that the current value is first accessed (with a getter or field) and then modified
* with incoming data. If merging is not used assignment happens without considering current state.
*<p>
* Merging is only option if there is a way to introspect current state:
* if there is accessor (getter, field) to use.
* Merging can not be enabled if no accessor exists
* or if assignment occurs using a Creator setter (constructor
* or factory method), since there is no instance with state to introspect.
* Merging also only has actual effect for structured types where there is an
* obvious way to update a state. For example, POJOs have default values for properties,
* and {@link java.util.Collection}s and {@link java.util.Map}s may have existing
* elements; whereas scalar types do not such state: an <code>int</code> has a value,
* but no obvious and non-ambiguous way to merge state.
*<p>
* Merging is applied by using a deserialization method that accepts existing state
* as an argument: it is then up to <code>JsonDeserializer</code> implementation
* to use that base state in a way that makes sense without further configuration.
* For structured types this is usually obvious; and for scalar types not -- if
* no obvious method exists, merging is not allowed; deserializer may choose to
* either quietly ignore it, or throw an exception.
* Specifically, for structured types:
*<ul>
* <li>For POJOs merging is done recursively, property by property.
* </li>
* <li>For {@link java.util.Map}s merging is done recursively, entry by entry .
* </li>
* <li>For {@link java.util.Collection} and Arrays, merging is done by appending
* incoming data into contents of existing Collection/array (and in case of Arrays,
* creating a new Array instance). NOTE! This is different from
* <a href="https://tools.ietf.org/html/rfc7396">JSON Merge Patch</a>.
* </li>
* <li>For Scalar values, incoming value replaces existing value, that is, no merging occurs.
* </li>
*</ul>
*<p>
* Note that use of merging usually adds some processing overhead since it adds
* an extra step of accessing the current state before assignment.
*<p>
* Note also that "root values" (values directly deserialized and not reached
* via POJO properties) can not use this annotation; instead, <code>ObjectMapper</code>
* and <code>Object</code> have "updating reader" operations.
*<p>
* Default value is {@link OptBoolean#TRUE}, that is, merging <b>is enabled</b>.
*
* @since 2.9
*/
@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonMerge
{
/**
* Whether merging should or should not be enabled for the annotated property.
*/
OptBoolean value() default OptBoolean.TRUE;
}