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 * Marker annotation that can be used to define a non-static
10 * method as a "setter" or "getter" for a logical property
11 * (depending on its signature),
12 * or non-static object field to be used (serialized, deserialized) as
13 * a logical property.
14 *<p>
15 * Default value ("") indicates that the field name is used
16 * as the property name without any modifications, but it
17 * can be specified to non-empty value to specify different
18 * name. Property name refers to name used externally, as
19 * the field name in JSON objects.
20 *<p>
21 * Starting with Jackson 2.6 this annotation may also be
22 * used to change serialization of <code>Enum</code> like so:
23 *<pre>
24 public enum MyEnum {
25 {@literal @JsonProperty}("theFirstValue") THE_FIRST_VALUE,
26 {@literal @JsonProperty}("another_value") ANOTHER_VALUE;
27 }
28 </pre>
29 * as an alternative to using {@link JsonValue} annotation.
30 */
31 @Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
32 @Retention(RetentionPolicy.RUNTIME)
33 @JacksonAnnotation
34 public @interface JsonProperty
35 {
36 /**
37 * Special value that indicates that handlers should use the default
38 * name (derived from method or field name) for property.
39 *
40 * @since 2.1
41 */
42 public final static String USE_DEFAULT_NAME = "";
43
44 /**
45 * Marker value used to indicate that no index has been specified.
46 * Used as the default value as annotations do not allow "missing"
47 * values.
48 *
49 * @since 2.4
50 */
51 public final static int INDEX_UNKNOWN = -1;
52
53 /**
54 * Defines name of the logical property, i.e. JSON object field
55 * name to use for the property. If value is empty String (which is the
56 * default), will try to use name of the field that is annotated.
57 * Note that there is
58 * <b>no default name available for constructor arguments</b>,
59 * meaning that
60 * <b>Empty String is not a valid value for constructor arguments</b>.
61 */
62 String value() default USE_DEFAULT_NAME;
63
64 /**
65 * Property that indicates whether a value (which may be explicit
66 * null) is expected for property during deserialization or not.
67 * If expected, <code>BeanDeserialized</code> should indicate
68 * this as a validity problem (usually by throwing an exception,
69 * but this may be sent via problem handlers that can try to
70 * rectify the problem, for example, by supplying a default
71 * value).
72 *<p>
73 * Note that as of 2.6, this property is only used for Creator
74 * Properties, to ensure existence of property value in JSON:
75 * for other properties (ones injected using a setter or mutable
76 * field), no validation is performed. Support for those cases
77 * may be added in future.
78 * State of this property is exposed via introspection, and its
79 * value is typically used by Schema generators, such as one for
80 * JSON Schema.
81 *
82 * @since 2.0
83 */
84 boolean required() default false;
85
86 /**
87 * Property that indicates numerical index of this property (relative
88 * to other properties specified for the Object). This index
89 * is typically used by binary formats, but may also be useful
90 * for schema languages and other tools.
91 *
92 * @since 2.4
93 */
94 int index() default INDEX_UNKNOWN;
95
96 /**
97 * Property that may be used to <b>document</b> expected default value
98 * for the property: most often used as source information for generating
99 * schemas (like JSON Schema or protobuf/thrift schema), or documentation.
100 * It may also be used by Jackson extension modules; core `jackson-databind`
101 * does not have any automated handling beyond simply exposing this
102 * value through bean property introspection.
103 *<p>
104 * It is possible that in future this annotation could be used for value
105 * defaulting, and especially for default values of Creator properties,
106 * since they support {@link #required()} in 2.6 and above.
107 *
108 * @since 2.5
109 */
110 String defaultValue() default "";
111
112 /**
113 * Optional property that may be used to change the way visibility of
114 * accessors (getter, field-as-getter) and mutators (constructor parameter,
115 * setter, field-as-setter) is determined, either so that otherwise
116 * non-visible accessors (like private getters) may be used; or that
117 * otherwise visible accessors are ignored.
118 *<p>
119 * Default value os {@link Access#AUTO} which means that access is determined
120 * solely based on visibility and other annotations.
121 *
122 * @since 2.6
123 */
124 Access access() default Access.AUTO;
125
126 /**
127 * Various options for {@link #access} property, specifying how property
128 * may be accessed during serialization ("read") and deserialization ("write")
129 * (note that the direction of read and write is from perspective of the property,
130 * not from external data format: this may be confusing in some contexts).
131 *<p>
132 * Note that while this annotation modifies access to annotated property,
133 * its effects may be further overridden by {@link JsonIgnore} property:
134 * if both annotations are present on an accessors, {@link JsonIgnore}
135 * has precedence over this property.
136 * This annotation property is, however, preferred over use of "split"
137 * {@link JsonIgnore}/<code>JsonProperty</code> combination.
138 *
139 * @since 2.6
140 */
141 public enum Access
142 {
143 /**
144 * Access setting which means that visibility rules are to be used
145 * to automatically determine read- and/or write-access of this property.
146 */
147 AUTO,
148
149 /**
150 * Access setting that means that the property may only be read for serialization
151 * (value accessed via "getter" Method, or read from Field)
152 * but not written (set) during deserialization.
153 * Put another way, this would reflect "read-only POJO", in which value contained
154 * may be read but not written/set.
155 */
156 READ_ONLY,
157
158 /**
159 * Access setting that means that the property may only be written (set)
160 * as part of deserialization (using "setter" method, or assigning to Field,
161 * or passed as Creator argument)
162 * but will not be read (get) for serialization, that is, the value of the property
163 * is not included in serialization.
164 */
165 WRITE_ONLY,
166
167 /**
168 * Access setting that means that the property will be accessed for both
169 * serialization (writing out values as external representation)
170 * and deserialization (reading values from external representation),
171 * regardless of visibility rules.
172 */
173 READ_WRITE
174 ;
175 }
176 }
177