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 */ value()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 */ required()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 */ index()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 */ defaultValue()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 */ access()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