Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 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 used to indicate when value of the annotated property (when |
| 10 | * used for a field, method or constructor parameter), or all |
| 11 | * properties of the annotated class, is to be serialized. |
| 12 | * Without annotation property values are always included, but by using |
| 13 | * this annotation one can specify simple exclusion rules to reduce |
| 14 | * amount of properties to write out. |
Cowtowncoder | f251235 | 2015-03-27 10:31:16 -0700 | [diff] [blame] | 15 | *<p> |
| 16 | * Note that inclusion criteria is checked on <b>Java object level</b> |
| 17 | * and <b>NOT</b> on JSON output -- so even with {@link Include#NON_NULL} |
| 18 | * it is possible that JSON null values are output, if object reference |
Cowtowncoder | 4595936 | 2015-05-28 16:52:48 -0700 | [diff] [blame] | 19 | * in question is not `null`. An example is {@link java.util.concurrent.atomic.AtomicReference} |
Cowtowncoder | f251235 | 2015-03-27 10:31:16 -0700 | [diff] [blame] | 20 | * instance constructed to reference <code>null</code> value: such a value |
| 21 | * would be serialized as JSON null, and not filtered out. |
| 22 | * In such cases {@link Include#NON_EMPTY} should be used instead, since missing |
| 23 | * reference (that is, reference to Java null) is considered "empty" (it is also |
| 24 | * considered "default", so match {@link Include#NON_DEFAULT}). |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 25 | * |
| 26 | * @since 2.0 |
| 27 | */ |
Tatu Saloranta | 1dbeb48 | 2012-01-17 09:04:05 -0800 | [diff] [blame] | 28 | @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD, |
| 29 | ElementType.TYPE, ElementType.PARAMETER}) |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 30 | @Retention(RetentionPolicy.RUNTIME) |
| 31 | @com.fasterxml.jackson.annotation.JacksonAnnotation |
| 32 | public @interface JsonInclude |
| 33 | { |
| 34 | /** |
Tatu Saloranta | 3e08b40 | 2014-10-16 22:49:33 -0700 | [diff] [blame] | 35 | * Inclusion rule to use for instances (values) of types (Classes) or |
| 36 | * properties annotated. |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 37 | */ |
| 38 | public Include value() default Include.ALWAYS; |
Tatu Saloranta | 3e08b40 | 2014-10-16 22:49:33 -0700 | [diff] [blame] | 39 | |
| 40 | /** |
| 41 | * Inclusion rule to use for entries ("content") of annotated |
| 42 | * {@link java.util.Map}s; defaults to {@link Include#ALWAYS}. |
| 43 | * |
| 44 | * @since 2.5 |
| 45 | */ |
| 46 | public Include content() default Include.ALWAYS; |
| 47 | |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 48 | /* |
| 49 | /********************************************************** |
| 50 | /* Value enumerations needed |
| 51 | /********************************************************** |
| 52 | */ |
| 53 | |
| 54 | /** |
Tatu Saloranta | 28c0f60 | 2012-01-20 23:02:39 -0800 | [diff] [blame] | 55 | * Enumeration used with {@link JsonInclude} |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 56 | * to define which properties |
| 57 | * of Java Beans are to be included in serialization. |
| 58 | *<p> |
| 59 | * Note: Jackson 1.x had similarly named ("Inclusion") enumeration included |
Adam Koch | 73ca3ab | 2014-11-06 15:58:35 -0600 | [diff] [blame] | 60 | * in <code>JsonSerialize</code> annotation: it is now deprecated |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 61 | * and this value used instead. |
| 62 | */ |
| 63 | public enum Include |
| 64 | { |
| 65 | /** |
| 66 | * Value that indicates that property is to be always included, |
| 67 | * independent of value of the property. |
| 68 | */ |
| 69 | ALWAYS, |
| 70 | |
| 71 | /** |
| 72 | * Value that indicates that only properties with non-null |
| 73 | * values are to be included. |
| 74 | */ |
| 75 | NON_NULL, |
| 76 | |
| 77 | /** |
Cowtowncoder | 4595936 | 2015-05-28 16:52:48 -0700 | [diff] [blame] | 78 | * Value that indicates that properties are included unless their value |
| 79 | * is: |
| 80 | *<ul> |
| 81 | * <li>null</li> |
| 82 | * <li>"absent" value of a referential type (like Java 8 `Optional`, or |
| 83 | * {link java.utl.concurrent.atomic.AtomicReference}); that is, something |
| 84 | * that would not deference to a non-null value. |
| 85 | * </ul> |
| 86 | * This option is mostly used to work with "Optional"s (Java 8, Guava). |
| 87 | * |
| 88 | * @since 2.6 |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 89 | */ |
Cowtowncoder | 4595936 | 2015-05-28 16:52:48 -0700 | [diff] [blame] | 90 | NON_ABSENT, |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 91 | |
| 92 | /** |
| 93 | * Value that indicates that only properties that have values |
| 94 | * that values that are null or what is considered empty are |
| 95 | * not to be included. |
Cowtowncoder | 83b0a64 | 2014-11-10 09:24:11 -0800 | [diff] [blame] | 96 | * Definition of emptiness is data type specific; see below |
| 97 | * for details on actual handling. |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 98 | *<p> |
| 99 | * Default emptiness is defined for following type: |
| 100 | *<ul> |
| 101 | * <li>For {@link java.util.Collection}s and {@link java.util.Map}s, |
| 102 | * method <code>isEmpty()</code> is called; |
| 103 | * </li> |
| 104 | * <li>For Java arrays, empty arrays are ones with length of 0 |
| 105 | * </li> |
| 106 | * <li>For Java {@link java.lang.String}s, <code>length()</code> is called, |
| 107 | * and return value of 0 indicates empty String (note that <code>String.isEmpty()</code> |
| 108 | * was added in Java 1.6 and as such can not be used by Jackson |
| 109 | * </li> |
Cowtowncoder | 83b0a64 | 2014-11-10 09:24:11 -0800 | [diff] [blame] | 110 | * <li>For date/time types, if timestamp from Epoch is zero (January 1st, 1970, UTC), |
| 111 | * value is considered empty. |
| 112 | * </li> |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 113 | * <ul> |
Cowtowncoder | 83b0a64 | 2014-11-10 09:24:11 -0800 | [diff] [blame] | 114 | * and for other types, null values are excluded but other exclusions (if any). |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 115 | *<p> |
| 116 | * Note that this default handling can be overridden by custom |
| 117 | * <code>JsonSerializer</code> implementation: if method <code>isEmpty()</code> |
| 118 | * is overridden, it will be called to see if non-null values are |
| 119 | * considered empty (null is always considered empty). |
| 120 | */ |
Cowtowncoder | 4595936 | 2015-05-28 16:52:48 -0700 | [diff] [blame] | 121 | NON_EMPTY, |
| 122 | |
| 123 | /** |
| 124 | * Value that indicates that only properties that have values |
| 125 | * that differ from default settings (meaning values they have |
| 126 | * when Bean is constructed with its no-arguments constructor) |
| 127 | * are to be included. Value is generally not useful with |
| 128 | * {@link java.util.Map}s, since they have no default values; |
| 129 | * and if used, works same as {@link #ALWAYS}. |
| 130 | */ |
| 131 | NON_DEFAULT |
| 132 | |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 133 | ; |
| 134 | } |
Tatu Saloranta | e05f96a | 2012-01-14 22:01:40 -0800 | [diff] [blame] | 135 | } |