JsonInclude.java

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 used to indicate when value of the annotated property (when
 * used for a field, method or constructor parameter), or all
 * properties of the annotated class (when used for a class), is to be serialized.
 * Without annotation property values are always included, but by using
 * this annotation one can specify simple exclusion rules to reduce
 * amount of properties to write out.
 *<p>
 * Note that the main inclusion criteria (one annotated with {@link #value})
 * is checked on <b>Java object level</b>, for the annotated type,
 * and <b>NOT</b> on JSON output -- so even with {@link Include#NON_NULL}
 * it is possible that JSON null values are output, if object reference
 * in question is not `null`. An example is {@link java.util.concurrent.atomic.AtomicReference}
 * instance constructed to reference <code>null</code> value: such a value
 * would be serialized as JSON {@code null}, and not filtered out.
 *<p>
 * To base inclusion on value of <b>contained</b> value(s) (like {@code java.util.Map}
 * entries), you will typically also need
 * to specify {@link #content()} annotation; for example, specifying only
 * {@link #value} as {@link Include#NON_EMPTY} for a {@link java.util.Map} would
 * exclude {@link java.util.Map}s with no entries (empty {@code Map}s),
 * but would include <code>Map</code>s elements with {@code null} values (even
 * though {@code null}s are considered "empty" values).
 * To exclude {@code Map}s with only `null`-valued entries,
 * you would use both annotations like so:
 *<pre>
 *public class Bean {
 *   {@literal @JsonInclude}(value=Include.NON_EMPTY, content=Include.NON_NULL)
 *   public Map&lt;String,String&gt; entries;
 *}
 *</pre>
 * (in which case filtering first excludes {@code Map} entries with {@code null} values
 * and then excludes {@code Map}s that have no entries left).
 * <br>
 * Similarly you could exclude <code>Map</code>s map entries with
 * "empty" values, or "non-default" values (see {@link Include#NON_EMPTY} and
 * {@link Include#NON_DEFAULT} for more details).
 *<p>
 * In addition to {@code Map}s, {@code content} concept is also supported for referential
 * types (like {@link java.util.concurrent.atomic.AtomicReference}).
 *<p>
 * (For Jackson 2 only) Note that `content` is NOT currently (as of Jackson 2.20) supported for
 * arrays or {@link java.util.Collection}s; support may be added in
 * future versions (but if so, will be configurable to allow disabling it).
 *<p>
 * (For Jackson 3 only) As of Jackson 3.1.0, {@link #content()} also supports {@link java.util.Collection}s
 * and Arrays when {@code tools.jackson.databind.SerializationFeature#APPLY_JSON_INCLUDE_FOR_CONTAINERS}
 * feature is enabled -- disabled by default for backward-compatibility (see [databind#5369] for more detail).
 *
 * @since 2.0
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD,
    ElementType.TYPE, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonInclude
{
    /**
     * Inclusion rule to use for instances (values) of types (Classes) or
     * properties annotated; defaults to {@link Include#ALWAYS}.
     *
     * @return Inclusion rule for value itself
     */
    public Include value() default Include.ALWAYS;

    /**
     * Inclusion rule to use for entries ("content") of annotated
     * {@link java.util.Map}s and referential types (like
     * {@link java.util.concurrent.atomic.AtomicReference});
     * defaults to {@link Include#ALWAYS}.
     *
     * @return Inclusion rule for content (elements, values of structured types)
     *
     * @since 2.5
     */
    public Include content() default Include.ALWAYS;

    /**
     * Specifies type of "Filter Object" to use in case
     * {@link #value} is {@link JsonInclude.Include#CUSTOM}:
     * if so, an instance is created by calling {@code HandlerInstantiator}
     * (of  {@code ObjectMapper}), which by default simply calls
     * zero-argument constructor of the Filter Class.
     *<p>
     * Whether the value is to be included or not is determined by calling
     * Filter's {@code equals(value)} method: if it returns {@code true}
     * value is NOT included (it is "filtered out"); if {@code false} value
     * IS included ("not filtered out").
     *
     * @since 2.9
     */
    public Class<?> valueFilter() default Void.class;

    /**
     * Specifies type of "Filter Object" to use in case
     * {@link #content} is {@link JsonInclude.Include#CUSTOM}:
     * if so, an instance is created by calling  {@code HandlerInstantiator}
     * (of  {@code ObjectMapper}), which by default simply calls
     * zero-argument constructor of the Filter Class.
     *<p>
     * Whether the content value is to be included or not is determined by calling
     * Filter's {@code equals(value)} method: if it returns {@code true}
     * content value is NOT included (it is "filtered out"); if {@code false} content value
     * IS included ("not filtered out").
     *
     * @since 2.9
     */
    public Class<?> contentFilter() default Void.class;

    /*
    /**********************************************************************
    /* Value enumerations
    /**********************************************************************
     */

    /**
     * Enumeration used with {@link JsonInclude}
     * to define which properties
     * of Java Beans are to be included in serialization.
     */
    public enum Include
    {
        /**
         * Value that indicates that property is to be always included,
         * independent of value of the property.
         */
        ALWAYS,

        /**
         * Value that indicates that only properties with non-null
         * values are to be included.
         */
        NON_NULL,

        /**
         * Value that indicates that properties are included unless their value
         * is:
         *<ul>
         *  <li>null</li>
         *  <li>"absent" value of a referential type (like Java 8 `Optional`, or
         *     {@link java.util.concurrent.atomic.AtomicReference}); that is, something
         *     that would not deference to a non-null value.
         * </ul>
         * This option is mostly used to work with "Optional"s (Java 8, Guava).
         *
         * @since 2.6
         */
        NON_ABSENT,

        /**
         * Value that indicates that only properties with null value,
         * or what is considered empty, are not to be included.
         * Definition of emptiness is data type specific; see below
         * for details on actual handling.
         *<p>
         * Default emptiness for all types includes:
         *<ul>
         * <li><code>Null</code> values.</li>
         * <li>"Absent" values (see {@link #NON_ABSENT})</li>
         *</ul>
         * so that as baseline, "empty" set includes values that would be
         * excluded by both {@link #NON_NULL} and {@link #NON_ABSENT}.
         *<br>
         * Beyond this base, following types have additional empty values:
         *<ul>
         * <li>For {@link java.util.Collection}s and {@link java.util.Map}s,
         *    method <code>isEmpty()</code> is called;
         *   </li>
         * <li>For Java arrays, empty arrays are ones with length of 0
         *   </li>
         * <li>For Java {@link java.lang.String}s, <code>length()</code> is called,
         *   and return value of 0 indicates empty String
         *   </li>
         * </ul>
         *  and for other types, null values are excluded but other exclusions (if any).
         *<p>
         * Note that this default handling can be overridden by custom
         * <code>JsonSerializer</code> (2.x) / <code>ValueSerializer</code> (3.x)
         * implementation: if method <code>isEmpty()</code>
         * is overridden, it will be called to see if non-null values are
         * considered empty (null is always considered empty).
         *<p>
         * Compatibility note: Jackson 2.6 included a wider range of "empty" values than
         * either earlier (up to 2.5) or later (2.7 and beyond) types; specifically:
         *<ul>
         * <li>Default values of primitive types (like <code>0</code> for `int`/`java.lang.Integer`
         *  and `false` for `bool`/`Boolean`)
         *  </li>
         * <li>Timestamp 0 for date/time types
         *  </li>
         *</ul>
         * With 2.7, definition has been tightened back to only containing types explained
         * above (null, absent, empty String, empty containers), and now
         * extended definition may be specified using {@link #NON_DEFAULT}.
         */
        NON_EMPTY,

        /**
         * Meaning of this setting depends on context: whether annotation is
         * specified for POJO type (class), or not. In latter case annotation
         * is either used as the global default, or as property override.
         *<p>
         * When used for a POJO, definition is that only values that differ from
         * the default values of POJO properties are included. This is done
         * by creating an instance of POJO using zero-argument constructor,
         * and accessing property values: value is used as the default value
         * by using <code>equals()</code> method, except for the case where property
         * has `null` value in which case straight null check is used.
         *<p>
         * When NOT used for a POJO (that is, as a global default, or as property
         * override), definition is such that:
         *<ul>
         * <li>All values considered "empty" (as per {@link #NON_EMPTY}) are excluded</li>
         * <li>Primitive/wrapper default values are excluded</li>
         * <li>Date/time values that have timestamp (`long` value of milliseconds since
         *   epoch, see {@link java.util.Date}) of `0L` are excluded</li>
         * </ul>
         *<p>
         * NOTE: Jackson 3.2 has more configurability (via new {@code MapperFeature})
         * to configure applicability of this setting for global default inclusion.
         */
        NON_DEFAULT,

        /**
         * Value that indicates that separate {@code filter} Object (specified by
         * {@link JsonInclude#valueFilter} for value itself, and/or
         * {@link JsonInclude#contentFilter} for contents of structured types)
         * is to be used for determining inclusion criteria.
         * Filter object's {@code equals(value)} method is called with value
         * to serialize; if it returns {@code true} value is <b>excluded</b>
         * (that is, filtered out); if {@code false} value is <b>included</b>.
         *<p>
         * NOTE: the filter will be called for each non-{@code null} value,
         * but handling of {@code null} value differs: up to Jackson 2.13, call
         * was only made once, but with 2.14 and later filter will be called
         * once for each {@code null} value too.
         *
         * @since 2.9
         */
        CUSTOM,

        /**
         * Pseudo-value used to indicate that the higher-level defaults make
         * sense, to avoid overriding inclusion value. For example, if returned
         * for a property this would use defaults for the class that contains
         * property, if any defined; and if none defined for that, then
         * global serialization inclusion details.
         *
         * @since 2.6
         */
        USE_DEFAULTS
        ;
    }

    /*
    /**********************************************************************
    /* Value class used to enclose information
    /**********************************************************************
     */

    /**
     * Helper class used to contain information from a single {@link JsonInclude}
     * annotation.
     *
     * @since 2.6
     */
    public static class Value
        implements JacksonAnnotationValue<JsonInclude>, // since 2.6
            java.io.Serializable
    {
        private static final long serialVersionUID = 1L;

        /**
         * Constant that indicates that property is to be always included,
         * independent of value of the property.
         * <p>
         * This will specify the same setting for including a value both
         * on <b>Java object level</b> as well as when <b>contained</b>
         * in an object reference (see {@link JsonInclude} for further
         * details on this distinction).
         *
         * @since 2.21
         */
        public final static Value ALL_ALWAYS = Value
                .construct(Include.ALWAYS, Include.ALWAYS);

        /**
         * Constant that indicates that only properties with non-null
         * values are to be included.
         * <p>
         * This will specify the same setting for including a value both
         * on <b>Java object level</b> as well as when <b>contained</b>
         * in an object reference (see {@link JsonInclude} for further
         * details on this distinction).
         *
         * @since 2.21
         */
        public final static Value ALL_NON_NULL = Value
                .construct(Include.NON_NULL, Include.NON_NULL);

        /**
         * Constant that indicates that properties are included unless their value
         * is:
         * <ul>
         *  <li>null</li>
         *  <li>"absent" value of a referential type (like Java 8 `Optional`, or
         *     {@link java.util.concurrent.atomic.AtomicReference}); that is, something
         *     that would not deference to a non-null value.
         * </ul>
         * This option is mostly used to work with "Optional"s (Java 8, Guava).
         * <p>
         * This will specify the same setting for including a value both
         * on <b>Java object level</b> as well as when <b>contained</b>
         * in an object reference (see {@link JsonInclude} for further
         * details on this distinction).
         *
         * @since 2.21
         */
        public final static Value ALL_NON_ABSENT = Value
                .construct(Include.NON_ABSENT, Include.NON_ABSENT);

        /**
         * Constant that indicates that only properties with null value,
         * or what is considered empty, are not to be included.
         * See {@link Include#NON_EMPTY} for further details.
         * <p>
         * This will specify the same setting for including a value both
         * on <b>Java object level</b> as well as when <b>contained</b>
         * in an object reference (see {@link JsonInclude} for further
         * details on this distinction).
         *
         * @since 2.21
         */
        public final static Value ALL_NON_EMPTY = Value
                .construct(Include.NON_EMPTY, Include.NON_EMPTY);

        /**
         * The equivalent to {@link Include#NON_DEFAULT} for specifying
         * inclusion of non-defaults for both values and content.
         * <p>
         * This will specify the same setting for including a value both
         * on <b>Java object level</b> as well as when <b>contained</b>
         * in an object reference (see {@link JsonInclude} for further
         * details on this distinction).
         *
         * @since 2.21
         */
        public final static Value ALL_NON_DEFAULT = Value
                .construct(Include.NON_DEFAULT, Include.NON_DEFAULT);

        protected final static Value EMPTY = new Value(Include.USE_DEFAULTS,
                Include.USE_DEFAULTS, null, null);

        protected final Include _valueInclusion;
        protected final Include _contentInclusion;

        /**
         * @since 2.9
         */
        protected final Class<?> _valueFilter;

        /**
         * @since 2.9
         */
        protected final Class<?> _contentFilter;

        public Value(JsonInclude src) {
            this(src.value(), src.content(),
                    src.valueFilter(), src.contentFilter());
        }

        protected Value(Include vi, Include ci,
                Class<?> valueFilter, Class<?> contentFilter) {
            _valueInclusion = (vi == null) ? Include.USE_DEFAULTS : vi;
            _contentInclusion = (ci == null) ? Include.USE_DEFAULTS : ci;
            _valueFilter = (valueFilter == Void.class) ? null : valueFilter;
            _contentFilter = (contentFilter == Void.class) ? null : contentFilter;
        }

        public static Value empty() {
            return EMPTY;
        }

        /**
         * 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.
         *
         * @since 2.8
         */
        public static Value merge(Value base, Value overrides)
        {
            return (base == null) ? overrides
                    : base.withOverrides(overrides);
        }

        /**
         * @since 2.8
         */
        public static Value mergeAll(Value... values)
        {
            Value result = null;
            for (Value curr : values) {
                if (curr != null) {
                    result = (result == null)  ? curr : result.withOverrides(curr);
                }
            }
            return result;
        }

        // for JDK serialization
        protected Object readResolve() {
            if ((_valueInclusion == Include.USE_DEFAULTS)
                    && (_contentInclusion == Include.USE_DEFAULTS)
                    && (_valueFilter == null)
                    && (_contentFilter == null)
                    ) {
                return EMPTY;
            }
            return this;
        }

        /**
         * 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;
            }
            Include vi = overrides._valueInclusion;
            Include ci = overrides._contentInclusion;
            Class<?> vf = overrides._valueFilter;
            Class<?> cf = overrides._contentFilter;

            boolean viDiff = (vi != _valueInclusion) && (vi != Include.USE_DEFAULTS);
            boolean ciDiff = (ci != _contentInclusion) && (ci != Include.USE_DEFAULTS);
            boolean filterDiff = (vf != _valueFilter) || (cf != _contentFilter);

            if (viDiff) {
                if (ciDiff) {
                    return new Value(vi, ci, vf, cf);
                }
                return new Value(vi, _contentInclusion, vf, cf);
            } else if (ciDiff) {
                return new Value(_valueInclusion, ci, vf, cf);
            } else if (filterDiff) {
                return new Value(_valueInclusion, _contentInclusion, vf, cf);
            }
            return this;
        }

        /**
         * Factory method to use for constructing an instance for components
         */
        public static Value construct(Include valueIncl, Include contentIncl) {
            if (((valueIncl == Include.USE_DEFAULTS) || (valueIncl == null))
                    && ((contentIncl == Include.USE_DEFAULTS) || (contentIncl == null))) {
                return EMPTY;
            }
            return new Value(valueIncl, contentIncl, null, null);
        }

        /**
         * Factory method to use for constructing an instance for components
         *
         * @since 2.9
         */
        public static Value construct(Include valueIncl, Include contentIncl,
                Class<?> valueFilter, Class<?> contentFilter)
        {
            if (valueFilter == Void.class) {
                valueFilter = null;
            }
            if (contentFilter == Void.class) {
                contentFilter = null;
            }
            if (((valueIncl == Include.USE_DEFAULTS) || (valueIncl == null))
                    && ((contentIncl == Include.USE_DEFAULTS) || (contentIncl == null))
                    && (valueFilter == null)
                    && (contentFilter == null)
                    ) {
                return EMPTY;
            }
            return new Value(valueIncl, contentIncl, valueFilter, contentFilter);
        }

        /**
         * Factory method to use for constructing an instance from instance of
         * {@link JsonInclude}
         */
        public static Value from(JsonInclude src) {
            if (src == null) {
                return EMPTY;
            }
            Include vi = src.value();
            Include ci = src.content();

            if ((vi == Include.USE_DEFAULTS) && (ci == Include.USE_DEFAULTS)) {
                return EMPTY;
            }
            Class<?> vf = src.valueFilter();
            if (vf == Void.class) {
                vf = null;
            }
            Class<?> cf = src.contentFilter();
            if (cf == Void.class) {
                cf = null;
            }
            return new Value(vi, ci, vf, cf);
        }

        public Value withValueInclusion(Include incl) {
            return (incl == _valueInclusion) ? this
                    : new Value(incl, _contentInclusion, _valueFilter, _contentFilter);
        }

        /**
         * Mutant factory that will either
         *<ul>
         * <li>Set <code>value</code> as <code>USE_DEFAULTS</code>
         * and <code>valueFilter</code> to <code>filter</code> (if filter not null);
         * or</li>
         * <li>Set <code>value</code> as <code>ALWAYS</code> (if filter null)
         *  </li>
         *  </ul>
         *
         * @since 2.9
         */
        public Value withValueFilter(Class<?> filter) {
            Include incl;
            if (filter == null || filter == Void.class) { // clear filter
                incl = Include.USE_DEFAULTS;
                filter = null;
            } else {
                incl = Include.CUSTOM;
            }
            return construct(incl, _contentInclusion, filter, _contentFilter);
        }

        /**
         * Mutant factory that will either
         *<ul>
         * <li>Set <code>content</code> as <code>USE_DEFAULTS</code>
         * and <code>contentFilter</code> to <code>filter</code> (if filter not null);
         * or</li>
         * <li>Set <code>content</code> as <code>ALWAYS</code> (if filter null)
         *  </li>
         *  </ul>
         *
         * @since 2.9
         */
        public Value withContentFilter(Class<?> filter) {
            Include incl;
            if (filter == null || filter == Void.class) { // clear filter
                incl = Include.USE_DEFAULTS;
                filter = null;
            } else {
                incl = Include.CUSTOM;
            }
            return construct(_valueInclusion, incl, _valueFilter, filter);
        }

        public Value withContentInclusion(Include incl) {
            return (incl == _contentInclusion) ? this
                    : new Value(_valueInclusion, incl, _valueFilter, _contentFilter);
        }

        @Override
        public Class<JsonInclude> valueFor() {
            return JsonInclude.class;
        }

        public Include getValueInclusion() {
            return _valueInclusion;
        }

        public Include getContentInclusion() {
            return _contentInclusion;
        }

        public Class<?> getValueFilter() {
            return _valueFilter;
        }

        public Class<?> getContentFilter() {
            return _contentFilter;
        }

        @Override
        public String toString() {
            StringBuilder sb = new StringBuilder(80);
            sb.append("JsonInclude.Value(value=")
                .append(_valueInclusion)
                .append(",content=")
                .append(_contentInclusion);
            if (_valueFilter != null) {
                sb.append(",valueFilter=").append(_valueFilter.getName()).append(".class");
            }
            if (_contentFilter != null) {
                sb.append(",contentFilter=").append(_contentFilter.getName()).append(".class");
            }
            return sb.append(')').toString();
        }

        @Override
        public int hashCode() {
            return (_valueInclusion.hashCode() << 2)
                    + _contentInclusion.hashCode()
                    + ((_valueFilter == null) ? 0 : _valueFilter.hashCode())
                    + ((_contentFilter == null) ? 0 : _contentFilter.hashCode());
        }

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

            return (other._valueInclusion == _valueInclusion)
                    && (other._contentInclusion == _contentInclusion)
                    && (other._valueFilter == _valueFilter)
                    && (other._contentFilter == _contentFilter)
                    ;
        }
    }
}