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