Top Description Inners Methods
com.fasterxml.jackson.annotation

public @Interface JsonInclude

extends Annotation
Annotations
@Target:ANNOTATION_TYPE, METHOD, FIELD, TYPE, PARAMETER
@Retention:RUNTIME
@JacksonAnnotation
Imports
java.lang.annotation.ElementType, .Retention, .RetentionPolicy, .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, 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.

Note that the main inclusion criteria (one annotated with value) is checked on Java object level, for the annotated type, and NOT on JSON output -- so even with Include#NON_NULL it is possible that JSON null values are output, if object reference in question is not `null`. An example is java.util.concurrent.atomic.AtomicReference instance constructed to reference null value: such a value would be serialized as JSON null, and not filtered out.

To base inclusion on value of contained value(s), you will typically also need to specify content() annotation; for example, specifying only value as Include#NON_EMPTY for a {link java.util.Map} would exclude Maps with no values, but would include Maps with `null` values. To exclude Map with only `null` value, you would use both annotations like so: 

public class Bean {
   @JsonInclude(value=Include.NON_EMPTY, content=Include.NON_NULL)
   public Map<String,String> entries;
}
Similarly you could exclude Maps that only contain "empty" elements, or "non-default" values (see Include#NON_EMPTY and Include#NON_DEFAULT for more details).

In addition to `Map`s, `content` concept is also supported for referential types (like java.util.concurrent.atomic.AtomicReference). Note that `content` is NOT currently (as of Jackson 2.9) supported for arrays or java.util.Collections, but supported may be added in future versions.

Since
2.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
JsonInclude.Include

Enumeration used with JsonInclude to define which properties of Java Beans are to be included in serialization.

public static class
JsonInclude.Value

Helper class used to contain information from a single JsonInclude annotation.

Method Summary

Modifier and TypeMethod and Description
public JsonInclude.Include
content()

Inclusion rule to use for entries ("content") of annotated java.util.Maps and referential types (like java.util.concurrent.atomic.AtomicReference); defaults to Include#ALWAYS.

public Class<?>
contentFilter()

Specifies type of "Filter Object" to use in case content is JsonInclude.Include#CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

public JsonInclude.Include
value()

Inclusion rule to use for instances (values) of types (Classes) or properties annotated; defaults to Include#ALWAYS.

public Class<?>
valueFilter()

Specifies type of "Filter Object" to use in case value is JsonInclude.Include#CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

Inherited from java.lang.annotation.Annotation:
annotationTypeequalshashCodetoString

Method Detail

contentback to summary
public JsonInclude.Include content()

Inclusion rule to use for entries ("content") of annotated java.util.Maps and referential types (like java.util.concurrent.atomic.AtomicReference); defaults to Include#ALWAYS.

Since
2.5
contentFilterback to summary
public Class<?> contentFilter()

Specifies type of "Filter Object" to use in case content is JsonInclude.Include#CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

Whether content value if is to be included or not is determined by calling Filter's equals(value) method: if it returns true content value is NOT included (it is "filtered out"); if false content value IS included ("not filtered out").

Since
2.9
valueback to summary
public JsonInclude.Include value()

Inclusion rule to use for instances (values) of types (Classes) or properties annotated; defaults to Include#ALWAYS.

valueFilterback to summary
public Class<?> valueFilter()

Specifies type of "Filter Object" to use in case value is JsonInclude.Include#CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

Whether value if is to be included or not is determined by calling Filter's equals(value) method: if it returns true value is NOT included (it is "filtered out"); if false value IS included ("not filtered out").

Since
2.9
com.fasterxml.jackson.annotation back to summary

public final Enum JsonInclude.Include

extends Enum<JsonInclude.Include>
Class Inheritance
Enumeration used with JsonInclude to define which properties of Java Beans are to be included in serialization.

Field Summary

Modifier and TypeField and Description
public static final JsonInclude.Include
ALWAYS

Value that indicates that property is to be always included, independent of value of the property.

public static final JsonInclude.Include
CUSTOM

Value that indicates that separate filter Object (specified by JsonInclude#valueFilter for value itself, and/or JsonInclude#contentFilter for contents of structured types) is to be used for determining inclusion criteria.

public static final JsonInclude.Include
NON_ABSENT

Value that indicates that properties are included unless their value is:

  • null
  • "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.
public static final JsonInclude.Include
NON_DEFAULT

Meaning of this setting depends on context: whether annotation is specified for POJO type (class), or not.

public static final JsonInclude.Include
NON_EMPTY

Value that indicates that only properties with null value, or what is considered empty, are not to be included.

public static final JsonInclude.Include
NON_NULL

Value that indicates that only properties with non-null values are to be included.

public static final JsonInclude.Include
USE_DEFAULTS

Pseudo-value used to indicate that the higher-level defaults make sense, to avoid overriding inclusion value.

Constructor Summary

AccessConstructor and Description
private
Include()

Method Summary

Modifier and TypeMethod and Description
public static JsonInclude.Include
valueOf(String name)

public static JsonInclude.Include[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ALWAYSback to summary
public static final JsonInclude.Include ALWAYS

Value that indicates that property is to be always included, independent of value of the property.

CUSTOMback to summary
public static final JsonInclude.Include CUSTOM

Value that indicates that separate filter Object (specified by JsonInclude#valueFilter for value itself, and/or JsonInclude#contentFilter for contents of structured types) is to be used for determining inclusion criteria. Filter object's equals(value) method is called with value to serialize; if it returns true value is excluded (that is, filtered out); if false value is included.

Note

the filter will be called for each non-null value, but handling of 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 null value too.

Since
2.9
NON_ABSENTback to summary
public static final JsonInclude.Include NON_ABSENT

Value that indicates that properties are included unless their value is:

  • null
  • "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.
This option is mostly used to work with "Optional"s (Java 8, Guava).
Since
2.6
NON_DEFAULTback to summary
public static final JsonInclude.Include NON_DEFAULT

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.

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 equals() method, except for the case where property has `null` value in which case straight null check is used.

When NOT used for a POJO (that is, as a global default, or as property override), definition is such that:

  • All values considered "empty" (as per NON_EMPTY) are excluded
  • Primitive/wrapper default values are excluded
  • Date/time values that have timestamp (`long` value of milliseconds since epoch, see java.util.Date) of `0L` are excluded
NON_EMPTYback to summary
public static final JsonInclude.Include NON_EMPTY

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.

Default emptiness for all types includes:

so that as baseline, "empty" set includes values that would be excluded by both NON_NULL and NON_ABSENT.
Beyond this base, following types have additional empty values: and for other types, null values are excluded but other exclusions (if any).

Note that this default handling can be overridden by custom JsonSerializer implementation: if method isEmpty() is overridden, it will be called to see if non-null values are considered empty (null is always considered empty).

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:

  • Default values of primitive types (like 0 for `int`/`java.lang.Integer` and `false` for `bool`/`Boolean`)
  • Timestamp 0 for date/time types
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 NON_DEFAULT.
NON_NULLback to summary
public static final JsonInclude.Include NON_NULL

Value that indicates that only properties with non-null values are to be included.

USE_DEFAULTSback to summary
public static final JsonInclude.Include USE_DEFAULTS

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

Constructor Detail

Includeback to summary
private Include()

Method Detail

valueOfback to summary
public static JsonInclude.Include valueOf(String name)
valuesback to summary
public static JsonInclude.Include[] values()
com.fasterxml.jackson.annotation back to summary

public Class JsonInclude.Value

extends Object
implements JacksonAnnotationValue<JsonInclude>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, com.fasterxml.jackson.annotation.JacksonAnnotationValue
Helper class used to contain information from a single JsonInclude annotation.
Since
2.6

Field Summary

Modifier and TypeField and Description
protected final Class<?>
_contentFilter

protected final JsonInclude.Include
_contentInclusion

protected final Class<?>
_valueFilter

protected final JsonInclude.Include
_valueInclusion

protected static final JsonInclude.Value
EMPTY

private static final long
serialVersionUID

Constructor Summary

AccessConstructor and Description
public
Value(JsonInclude src)

protected
Value(JsonInclude.Include vi, JsonInclude.Include ci, Class<?> valueFilter, Class<?> contentFilter)

Method Summary

Modifier and TypeMethod and Description
public static JsonInclude.Value
construct(JsonInclude.Include valueIncl, JsonInclude.Include contentIncl)

Factory method to use for constructing an instance for components

public static JsonInclude.Value
construct(JsonInclude.Include valueIncl, JsonInclude.Include contentIncl, Class<?> valueFilter, Class<?> contentFilter)

Factory method to use for constructing an instance for components

public static JsonInclude.Value
empty()

public boolean
equals(Object
the reference object with which to compare.
o)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.
public static JsonInclude.Value
from(JsonInclude src)

Factory method to use for constructing an instance from instance of JsonInclude

public Class<?>
getContentFilter()

public JsonInclude.Include
getContentInclusion()

public Class<?>
getValueFilter()

public JsonInclude.Include
getValueInclusion()

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for the object.
public static JsonInclude.Value
merge(JsonInclude.Value base, JsonInclude.Value overrides)

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).

public static JsonInclude.Value
mergeAll(JsonInclude.Value... values)

protected Object
readResolve()

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public Class<JsonInclude>
valueFor()

Implements com.fasterxml.jackson.annotation.JacksonAnnotationValue.valueFor.

Introspection method that may be used to find actual annotation that may be used as the source for value instance.
public JsonInclude.Value
withContentFilter(Class<?> filter)

Mutant factory that will either

  • Set content as USE_DEFAULTS and contentFilter to filter (if filter not null); or
  • Set content as ALWAYS (if filter null)
public JsonInclude.Value
withContentInclusion(JsonInclude.Include incl)

public JsonInclude.Value
withOverrides(JsonInclude.Value overrides)

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.

public JsonInclude.Value
withValueFilter(Class<?> filter)

Mutant factory that will either

  • Set value as USE_DEFAULTS and valueFilter to filter (if filter not null); or
  • Set value as ALWAYS (if filter null)
public JsonInclude.Value
withValueInclusion(JsonInclude.Include incl)

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

_contentFilterback to summary
protected final Class<?> _contentFilter
Since
2.9
_contentInclusionback to summary
protected final JsonInclude.Include _contentInclusion
_valueFilterback to summary
protected final Class<?> _valueFilter
Since
2.9
_valueInclusionback to summary
protected final JsonInclude.Include _valueInclusion
EMPTYback to summary
protected static final JsonInclude.Value EMPTY
serialVersionUIDback to summary
private static final long serialVersionUID

Constructor Detail

Valueback to summary
public Value(JsonInclude src)
Valueback to summary
protected Value(JsonInclude.Include vi, JsonInclude.Include ci, Class<?> valueFilter, Class<?> contentFilter)

Method Detail

constructback to summary
public static JsonInclude.Value construct(JsonInclude.Include valueIncl, JsonInclude.Include contentIncl)

Factory method to use for constructing an instance for components

constructback to summary
public static JsonInclude.Value construct(JsonInclude.Include valueIncl, JsonInclude.Include contentIncl, Class<?> valueFilter, Class<?> contentFilter)

Factory method to use for constructing an instance for components

Since
2.9
emptyback to summary
public static JsonInclude.Value empty()
equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
fromback to summary
public static JsonInclude.Value from(JsonInclude src)

Factory method to use for constructing an instance from instance of JsonInclude

getContentFilterback to summary
public Class<?> getContentFilter()
getContentInclusionback to summary
public JsonInclude.Include getContentInclusion()
getValueFilterback to summary
public Class<?> getValueFilter()
getValueInclusionback to summary
public JsonInclude.Include getValueInclusion()
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object.

Annotations
@Override
mergeback to summary
public static JsonInclude.Value merge(JsonInclude.Value base, JsonInclude.Value overrides)

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.

Since
2.8
mergeAllback to summary
public static JsonInclude.Value mergeAll(JsonInclude.Value... values)
Since
2.8
readResolveback to summary
protected Object readResolve()
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
valueForback to summary
public Class<JsonInclude> valueFor()

Implements com.fasterxml.jackson.annotation.JacksonAnnotationValue.valueFor.

Doc from com.fasterxml.jackson.annotation.JacksonAnnotationValue.valueFor.

Introspection method that may be used to find actual annotation that may be used as the source for value instance.

Returns:Class<JsonInclude>

Annotation class for which instances of this value class are created

Annotations
@Override
withContentFilterback to summary
public JsonInclude.Value withContentFilter(Class<?> filter)

Mutant factory that will either

  • Set content as USE_DEFAULTS and contentFilter to filter (if filter not null); or
  • Set content as ALWAYS (if filter null)
Since
2.9
withContentInclusionback to summary
public JsonInclude.Value withContentInclusion(JsonInclude.Include incl)
withOverridesback to summary
public JsonInclude.Value withOverrides(JsonInclude.Value overrides)

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.

withValueFilterback to summary
public JsonInclude.Value withValueFilter(Class<?> filter)

Mutant factory that will either

  • Set value as USE_DEFAULTS and valueFilter to filter (if filter not null); or
  • Set value as ALWAYS (if filter null)
Since
2.9
withValueInclusionback to summary
public JsonInclude.Value withValueInclusion(JsonInclude.Include incl)