package com.fasterxml.jackson.annotation;

import java.lang.annotation.*;

Annotation that can be used to define a non-static, single-argument method to be used as a "setter" for a logical property as an alternative to recommended JsonProperty annotation; or (as of 2.9 and later), specify additional aspects of the assigning property a value during serialization. /**
 * Annotation that can be used to define a non-static,
 * single-argument method to be used as a "setter" for a logical property
 * as an alternative to recommended
 * {@link JsonProperty} annotation;
 * or (as of 2.9 and later), specify additional aspects of the
 * assigning property a value during serialization.
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
// ^^^ allowed on Fields, (constructor) parameters since 2.9
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonSetter
{
    
Optional default argument that defines logical property this
method is used to modify ("set"); this is the property
name used in JSON content.
/**
     * Optional default argument that defines logical property this
     * method is used to modify ("set"); this is the property
     * name used in JSON content.
     */
    String value() default "";

    
Specifies action to take when input contains explicit `null` value (if format has one). Default action, in absence of any explicit configuration, is usually Nulls.SET, meaning that the `null` is set as value using setter. 

NOTE: is not usually used in case property value is missing, unless
data format specifies that there is defaulting which would result
in an explicit null assignment.
/**
     * Specifies action to take when input contains explicit `null` value
     * (if format has one).
     * Default action, in absence of any explicit configuration,
     * is usually {@link Nulls#SET}, meaning that the `null` is set as
     * value using setter.
     *<p>
     * NOTE: is not usually used in case property value is missing, unless
     * data format specifies that there is defaulting which would result
     * in an explicit null assignment.
     */
    Nulls nulls() default Nulls.DEFAULT;

    
Specifies action to take when input to match into content value (of a Collection, Map, array, or referential value) contains explicit `null` value (if format has one) to bind. Default action, in absence of any explicit configuration, is usually Nulls.SET, meaning that the `null` is included as usual. /**
     * Specifies action to take when input to match into content value
     * (of a {@link java.util.Collection}, {@link java.util.Map}, array,
     * or referential value) contains explicit `null` value
     * (if format has one) to bind.
     * Default action, in absence of any explicit configuration,
     * is usually {@link Nulls#SET}, meaning that the `null` is included as usual.
     */
    Nulls contentNulls() default Nulls.DEFAULT;

    /*
    /**********************************************************
    /* Value class used to enclose information, allow for
    /* merging of layered configuration settings.
    /**********************************************************
     */

    
Helper class used to contain information from a single JsonSetter annotation, as well as to provide possible overrides from non-annotation sources. 
Since:
2.9/**
     * Helper class used to contain information from a single {@link JsonSetter}
     * annotation, as well as to provide possible overrides from non-annotation sources.
     *
     * @since 2.9
     */
    public static class Value
        implements JacksonAnnotationValue<JsonSetter>,
            java.io.Serializable
    {
        private static final long serialVersionUID = 1L;

        private final Nulls _nulls;

        private final Nulls _contentNulls;
        
        
Default instance used in place of "default settings".
/**
         * Default instance used in place of "default settings".
         */
        protected final static Value EMPTY = new Value(Nulls.DEFAULT, Nulls.DEFAULT);

        protected Value(Nulls nulls, Nulls contentNulls) {
            _nulls = nulls;
            _contentNulls = contentNulls;
        }

        @Override
        public Class<JsonSetter> valueFor() {
            return JsonSetter.class;
        }
        
        // for JDK serialization
        protected Object readResolve() {
            if (_empty(_nulls, _contentNulls)) {
                return EMPTY;
            }
            return this;
        }

        public static Value from(JsonSetter src) {
            if (src == null) {
                return EMPTY;
            }
            return construct(src.nulls(), src.contentNulls());
        }

        
Factory method that may be used (although is NOT the recommended way) to construct an instance from a full set of properties. Most users would be better of starting by empty() instance and using `withXxx`/`withoutXxx` methods, as this factory method may need to be changed if new properties are added in JsonIgnoreProperties annotation. /**
         * Factory method that may be used (although is NOT the recommended way)
         * to construct an instance from a full set of properties. Most users would
         * be better of starting by {@link #empty()} instance and using `withXxx`/`withoutXxx`
         * methods, as this factory method may need to be changed if new properties
         * are added in {@link JsonIgnoreProperties} annotation.
         */
        public static Value construct(Nulls nulls, Nulls contentNulls) {
            if (nulls == null) {
                nulls = Nulls.DEFAULT;
            }
            if (contentNulls == null) {
                contentNulls = Nulls.DEFAULT;
            }
            if (_empty(nulls, contentNulls)) {
                return EMPTY;
            }
            return new Value(nulls, contentNulls);
        }

        
Accessor for default instances which has "empty" settings; that is:

Null handling using global defaults, Nulls.DEFAULT. 

/**
         * Accessor for default instances which has "empty" settings; that is:
         *<ul>
         * <li>Null handling using global defaults, {@link Nulls#DEFAULT}.
         *  </li>
         * </ul>
         */
        public static Value empty() {
            return EMPTY;
        }

        
Helper method that will try to combine values from two Value instances, using one as base settings, and the other as overrides to use instead of base values when defined; base values are only use if override does not specify a value (matching value is null or logically missing). Note that one or both of value instances may be `null`, directly; if both are `null`, result will also be `null`; otherwise never null. /**
         * Helper method that will try to combine values from two {@link Value}
         * instances, using one as base settings, and the other as overrides
         * to use instead of base values when defined; base values are only
         * use if override does not specify a value (matching value is null
         * or logically missing).
         * Note that one or both of value instances may be `null`, directly;
         * if both are `null`, result will also be `null`; otherwise never null.
         */
        public static Value merge(Value base, Value overrides)
        {
            return (base == null) ? overrides
                    : base.withOverrides(overrides);
        }

        public static Value forValueNulls(Nulls nulls) {
            return construct(nulls, Nulls.DEFAULT);
        }

        public static Value forValueNulls(Nulls nulls, Nulls contentNulls) {
            return construct(nulls, contentNulls);
        }
        
        public static Value forContentNulls(Nulls nulls) {
            return construct(Nulls.DEFAULT, nulls);
        }

        
Mutant factory method that merges values of this value with given override
values, so that any explicitly defined inclusion in overrides has precedence over
settings of this value instance. If no overrides exist will return this instance; otherwise new Value with changed inclusion values. /**
         * Mutant factory method that merges values of this value with given override
         * values, so that any explicitly defined inclusion in overrides has precedence over
         * settings of this value instance. If no overrides exist will return <code>this</code>
         * instance; otherwise new {@link Value} with changed inclusion values.
         */
        public Value withOverrides(Value overrides) {
            if ((overrides == null) || (overrides == EMPTY)) {
                return this;
            }
            Nulls nulls = overrides._nulls;
            Nulls contentNulls = overrides._contentNulls;

            if (nulls == Nulls.DEFAULT) {
                nulls = _nulls;
            }
            if (contentNulls == Nulls.DEFAULT) {
                contentNulls = _contentNulls;
            }

            if ((nulls == _nulls) && (contentNulls == _contentNulls)) {
                return this;
            }
            return construct(nulls, contentNulls);
        }

        public Value withValueNulls(Nulls nulls) {
            if (nulls == null) {
                nulls = Nulls.DEFAULT;
            }
            if (nulls == _nulls) {
                return this;
            }
            return construct(nulls, _contentNulls);
        }

        public Value withValueNulls(Nulls valueNulls, Nulls contentNulls) {
            if (valueNulls == null) {
                valueNulls = Nulls.DEFAULT;
            }
            if (contentNulls == null) {
                contentNulls = Nulls.DEFAULT;
            }
            if ((valueNulls == _nulls) && (contentNulls == _contentNulls)) {
                return this;
            }
            return construct(valueNulls, contentNulls);
        }
        
        public Value withContentNulls(Nulls nulls) {
            if (nulls == null) {
                nulls = Nulls.DEFAULT;
            }
            if (nulls == _contentNulls) {
                return this;
            }
            return construct(_nulls, nulls);
        }

        public Nulls getValueNulls() { return _nulls; }
        public Nulls getContentNulls() { return _contentNulls; }

        
Returns same as getValueNulls() unless value would be Nulls.DEFAULT in which case `null` is returned. /**
         * Returns same as {@link #getValueNulls()} unless value would be
         * {@link Nulls#DEFAULT} in which case `null` is returned.
         */
        public Nulls nonDefaultValueNulls() {
            return (_nulls == Nulls.DEFAULT) ? null : _nulls;
        }

        
Returns same as getContentNulls() unless value would be Nulls.DEFAULT in which case `null` is returned. /**
         * Returns same as {@link #getContentNulls()} unless value would be
         * {@link Nulls#DEFAULT} in which case `null` is returned.
         */
        public Nulls nonDefaultContentNulls() {
            return (_contentNulls == Nulls.DEFAULT) ? null : _contentNulls;
        }

        /*
        /**********************************************************
        /* Std method overrides
        /**********************************************************
         */
        
        @Override
        public String toString() {
            return String.format("JsonSetter.Value(valueNulls=%s,contentNulls=%s)",
                    _nulls, _contentNulls);
        }

        @Override
        public int hashCode() {
            return _nulls.ordinal() + (_contentNulls.ordinal() << 2);
        }

        @Override
        public boolean equals(Object o) {
            if (o == this) return true;
            if (o == null) return false;
            if (o.getClass() == getClass()) {
                Value other = (Value) o;
                return (other._nulls == _nulls)
                        && (other._contentNulls == _contentNulls);
            }
            return false;
        }

        /*
        /**********************************************************
        /* Internal methods
        /**********************************************************
         */
        
        private static boolean _empty(Nulls nulls, Nulls contentNulls) {
            return (nulls == Nulls.DEFAULT)
                    && (contentNulls == Nulls.DEFAULT);
        }
    }
}