1 package com.fasterxml.jackson.annotation; 2 3 import java.lang.annotation.*; 4 5 /** 6 * Annotation used for configuring details of if and how type information is 7 * used with JSON serialization and deserialization, to preserve information 8 * about actual class of Object instances. This is necessarily for polymorphic 9 * types, and may also be needed to link abstract declared types and matching 10 * concrete implementation. 11 *<p> 12 * Some examples of typical annotations: 13 *<pre> 14 * // Include Java class name ("com.myempl.ImplClass") as JSON property "class" 15 * @JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class") 16 * 17 * // Include logical type name (defined in impl classes) as wrapper; 2 annotations 18 * @JsonTypeInfo(use=Id.NAME, include=As.WRAPPER_OBJECT) 19 * @JsonSubTypes({com.myemp.Impl1.class, com.myempl.Impl2.class}) 20 *</pre> 21 * Alternatively you can also define fully customized type handling by using 22 * <code>@JsonTypeResolver</code> annotation (from databind package). 23 *<p> 24 * This annotation can be used both for types (classes) and properties. 25 * If both exist, annotation on property has precedence, as it is 26 * considered more specific. 27 *<p> 28 * When used for properties (fields, methods), this annotation applies 29 * to <b>values</b>: so when applied to structure types 30 * (like {@link java.util.Collection}, {@link java.util.Map}, arrays), 31 * will apply to contained values, not the container; 32 * for non-structured types there is no difference. 33 * This is identical to how JAXB handles type information 34 * annotations; and is chosen since it is the dominant use case. 35 * There is no per-property way to force type information to be included 36 * for type of container (structured type); for container types one has 37 * to use annotation for type declaration. 38 *<p> 39 * Note on visibility of type identifier: by default, deserialization 40 * (use during reading of JSON) of type identifier 41 * is completely handled by Jackson, and is <b>not passed to</b> 42 * deserializers. However, if so desired, 43 * it is possible to define property <code>visible = true</code> 44 * in which case property will be passed as-is to deserializers 45 * (and set via setter or field) on deserialization. 46 *<p> 47 * On serialization side, Jackson will generate type id by itself, 48 * except if there is a property with name that matches 49 * {@link #property()}, in which case value of that property is 50 * used instead. 51 *<p> 52 * NOTE: use of type id of "class name" with very general base type 53 * (such as {@link java.lang.Object} or {@link java.io.Serializable}) 54 * can potentially open up security holes if deserializing content 55 * generated by untrusted sources. If content can not be trusted, 56 * it is necessary to either use "type name" as type id, or to 57 * limit possible types using other means. 58 */ 59 @Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE, 60 ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) 61 @Retention(RetentionPolicy.RUNTIME) 62 @JacksonAnnotation 63 public @interface JsonTypeInfo 64 { 65 /* 66 /********************************************************** 67 /* Value enumerations used for properties 68 /********************************************************** 69 */ 70 71 /** 72 * Definition of different type identifiers that can be included in JSON 73 * during serialization, and used for deserialization. 74 */ 75 public enum Id { 76 /** 77 * This means that no explicit type metadata is included, and typing is 78 * purely done using contextual information possibly augmented with other 79 * annotations. 80 */ 81 NONE(null), 82 83 /** 84 * Means that fully-qualified Java class name is used as the type identifier. 85 */ 86 CLASS("@class"), 87 88 /** 89 * Means that Java class name with minimal path is used as the type identifier. 90 * Minimal means that only the class name, and that part of preceding Java 91 * package name is included that is needed to construct fully-qualified name 92 * given fully-qualified name of the declared supertype; additionally a single 93 * leading dot ('.') must be used to indicate that partial class name is used. 94 * For example, for supertype "com.foobar.Base", and concrete type 95 * "com.foo.Impl", only ".Impl" would be included; and for "com.foo.impl.Impl2" 96 * only ".impl.Impl2" would be included. 97 *<br> 98 * <b>NOTE</b>: leading dot ('.') MUST be used to denote partial (minimal) name; 99 * if it is missing, value is assumed to be fully-qualified name. Fully-qualified 100 * name is used in cases where subtypes are not in same package (or sub-package 101 * thereof) as base class. 102 *<p> 103 * If all related classes are in the same Java package, this option can reduce 104 * amount of type information overhead, especially for small types. 105 * However, please note that using this alternative is inherently risky since it 106 * assumes that the 107 * supertype can be reliably detected. Given that it is based on declared type 108 * (since ultimate supertype, <code>java.lang.Object</code> would not be very 109 * useful reference point), this may not always work as expected. 110 */ 111 MINIMAL_CLASS("@c"), 112 113 /** 114 * Means that logical type name is used as type information; name will then need 115 * to be separately resolved to actual concrete type (Class). 116 */ 117 NAME("@type"), 118 119 /** 120 * Means that typing mechanism uses customized handling, with possibly 121 * custom configuration. This means that semantics of other properties is 122 * not defined by Jackson package, but by the custom implementation. 123 */ 124 CUSTOM(null) 125 ; 126 127 private final String _defaultPropertyName; 128 Id(String defProp)129 private Id(String defProp) { 130 _defaultPropertyName = defProp; 131 } 132 getDefaultPropertyName()133 public String getDefaultPropertyName() { return _defaultPropertyName; } 134 } 135 136 /** 137 * Definition of standard type inclusion mechanisms for type metadata. 138 * Used for standard metadata types, except for {@link Id#NONE}. 139 * May or may not be used for custom types ({@link Id#CUSTOM}). 140 */ 141 public enum As { 142 /** 143 * Inclusion mechanism that uses a single configurable property, included 144 * along with actual data (POJO properties) as a separate meta-property. 145 * <p> 146 * Default choice for inclusion. 147 */ 148 PROPERTY, 149 150 /** 151 * Inclusion mechanism that wraps typed JSON value (POJO 152 * serialized as JSON) in 153 * a JSON Object that has a single entry, 154 * where field name is serialized type identifier, 155 * and value is the actual JSON value. 156 *<p> 157 * Note: can only be used if type information can be serialized as 158 * String. This is true for standard type metadata types, but not 159 * necessarily for custom types. 160 */ 161 WRAPPER_OBJECT, 162 163 /** 164 * Inclusion mechanism that wraps typed JSON value (POJO 165 * serialized as JSON) in 166 * a 2-element JSON array: first element is the serialized 167 * type identifier, and second element the serialized POJO 168 * as JSON Object. 169 */ 170 WRAPPER_ARRAY, 171 172 /** 173 * Inclusion mechanism similar to <code>PROPERTY</code>, except that 174 * property is included one-level higher in hierarchy, i.e. as sibling 175 * property at same level as JSON Object to type. 176 * Note that this mechanism <b>can only be used for properties</b>, not 177 * for types (classes). Trying to use it for classes will result in 178 * inclusion strategy of basic <code>PROPERTY</code> instead. 179 *<p> 180 * Note also that this mechanism <b>can not be used for container values</b> 181 * (arrays, {@link java.util.Collection}s, {@link java.util.Map}s); it only 182 * works for scalar and POJO values. 183 */ 184 EXTERNAL_PROPERTY, 185 186 /** 187 * Inclusion mechanism similar to <code>PROPERTY</code> with respect 188 * to deserialization; but one that is produced by a "regular" accessible 189 * property during serialization. This means that <code>TypeSerializer</code> 190 * will do nothing, and expects a property with defined name to be output 191 * using some other mechanism (like default POJO property serialization, or 192 * custom serializer). 193 *<p> 194 * Note that this behavior is quite similar to that of using {@link JsonTypeId} 195 * annotation; 196 * except that here <code>TypeSerializer</code> is basically suppressed; 197 * whereas with {@link JsonTypeId}, output of regular property is suppressed. 198 * This mostly matters with respect to output order; this choice is the only 199 * way to ensure specific placement of type id during serialization. 200 * 201 * @since 2.3.0 but databind <b>only since 2.5.0</b>. 202 */ 203 EXISTING_PROPERTY 204 ; 205 } 206 207 /* 208 /********************************************************** 209 /* Annotation properties 210 /********************************************************** 211 */ 212 213 /** 214 * Specifies kind of type metadata to use when serializing 215 * type information for instances of annotated type 216 * and its subtypes; as well as what is expected during 217 * deserialization. 218 */ use()219 public Id use(); 220 221 /** 222 * Specifies mechanism to use for including type metadata (if any; for 223 * {@link Id#NONE} nothing is included); used when serializing, 224 * and expected when deserializing. 225 *<p> 226 * Note that for type metadata type of {@link Id#CUSTOM}, 227 * this setting may or may not have any effect. 228 */ include()229 public As include() default As.PROPERTY; 230 231 /** 232 * Property names used when type inclusion method ({@link As#PROPERTY}) is used 233 * (or possibly when using type metadata of type {@link Id#CUSTOM}). 234 * If POJO itself has a property with same name, value of property 235 * will be set with type id metadata: if no such property exists, type id 236 * is only used for determining actual type. 237 *<p> 238 * Default property name used if this property is not explicitly defined 239 * (or is set to empty <code>String</code>) is based on 240 * type metadata type ({@link #use}) used. 241 */ property()242 public String property() default ""; 243 244 /** 245 * Optional property that can be used to specify default implementation 246 * class to use for deserialization if type identifier is either not present, 247 * or can not be mapped to a registered type (which can occur for ids, 248 * but not when specifying explicit class to use). 249 * Property has no effect on choice of type id used for serialization; 250 * it is only used in deciding what to do for otherwise unmappable cases. 251 *<p> 252 * Note that while this property allows specification of the default 253 * implementation to use, it does not help with structural issues that 254 * may arise if type information is missing. This means that most often 255 * this is used with type-name -based resolution, to cover cases 256 * where new sub-types are added, but base type is not changed to 257 * reference new sub-types. 258 *<p> 259 * There are certain special values that indicate alternate behavior: 260 *<ul> 261 * <li>{@link java.lang.Void} means that objects with unmappable (or missing) 262 * type are to be mapped to null references. 263 * For backwards compatibility (2.5 and below), value of 264 * <code>com.fasterxml.jackson.databind.annotation.NoClass</code> is also allowed 265 * for such usage. 266 * </li> 267 * <li>Placeholder value of {@link JsonTypeInfo} (that is, this annotation type 268 * itself} means "there is no default implementation" (in which 269 * case an error results from unmappable type). 270 * For backwards compatibility with earlier versions (2.5 and below), 271 * value of {@link JsonTypeInfo.None} may also be used. 272 * </li> 273 * </ul> 274 */ defaultImpl()275 public Class<?> defaultImpl() default JsonTypeInfo.class; 276 277 /** 278 * Property that defines whether type identifier value will be passed 279 * as part of JSON stream to deserializer (true), or handled and 280 * removed by <code>TypeDeserializer</code> (false). 281 * Property has no effect on serialization. 282 *<p> 283 * Default value is false, meaning that Jackson handles and removes 284 * the type identifier from JSON content that is passed to 285 * <code>JsonDeserializer</code>. 286 * 287 * @since 2.0 288 */ visible()289 public boolean visible() default false; 290 291 // 19-Dec-2014, tatu: Was hoping to implement for 2.5, but didn't quite make it. 292 // Hope for better luck with 2.8 or later 293 /** 294 * Property that defines whether type serializer is allowed to omit writing 295 * of type id, in case that value written has type same as {@link #defaultImpl()}. 296 * If true, omission is allowed (although writer may or may not be able to do that); 297 * if false, type id should always be written still. 298 * 299 * @since 2.5 300 public boolean skipWritingDefault() default false; 301 /* 302 303 /* 304 /********************************************************** 305 /* Helper classes 306 /********************************************************** 307 */ 308 309 /** 310 * This marker class that is only to be used with <code>defaultImpl</code> 311 * annotation property, to indicate that there is no default implementation 312 * specified. 313 * 314 * @deprecated Since 2.5, use any Annotation type (such as {@link JsonTypeInfo}, 315 * if such behavior is needed; this is rarely necessary. 316 */ 317 @Deprecated 318 public abstract static class None { } 319 } 320