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.
 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 Collections and Maps may have existing elements; whereas scalar types do not such state: an int has a value,
but no obvious and non-ambiguous way to merge state.

Merging is applied by using a deserialization method that accepts existing state
as an argument: it is then up to JsonDeserializer 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:

For POJOs merging is done recursively, property by property.
 
For Maps merging is done recursively, entry by entry . 
For 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 JSON Merge Patch.
 
For Scalar values, incoming value replaces existing value, that is, no merging occurs.
 


Note that use of merging usually adds some processing overhead since it adds
an extra step of accessing the current state before assignment.

Note also that "root values" (values directly deserialized and not reached
via POJO properties) can not use this annotation; instead, ObjectMapper
and Object have "updating reader" operations.
 Default value is OptBoolean.TRUE, that is, merging is enabled.
Since:
2.9/**
 * 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.
/**
     * Whether merging should or should not be enabled for the annotated property.
     */
    OptBoolean value() default OptBoolean.TRUE;
}