1 package com.fasterxml.jackson.databind.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 import com.fasterxml.jackson.databind.JsonDeserializer; 9 import com.fasterxml.jackson.databind.KeyDeserializer; 10 import com.fasterxml.jackson.databind.util.Converter; 11 12 /** 13 * Annotation use for configuring deserialization aspects, by attaching 14 * to "setter" methods or fields, or to value classes. 15 * When annotating value classes, configuration is used for instances 16 * of the value class but can be overridden by more specific annotations 17 * (ones that attach to methods or fields). 18 *<p> 19 * An example annotation would be: 20 *<pre> 21 * @JsonDeserialize(using=MySerializer.class, 22 * as=MyHashMap.class, 23 * keyAs=MyHashKey.class, 24 * contentAs=MyHashValue.class 25 * ) 26 *</pre> 27 *<p> 28 * Something to note on usage: 29 *<ul> 30 * <li>All other annotations regarding behavior during building should be on <b>Builder</b> 31 * class and NOT on target POJO class: for example @JsonIgnoreProperties should be on 32 * Builder to prevent "unknown property" errors. 33 * </li> 34 * <li>Similarly configuration overrides (see {@link com.fasterxml.jackson.databind.ObjectMapper#configOverride}) 35 * should be targeted at Builder class, not target POJO class. 36 * </li> 37 * </ul> 38 * 39 */ 40 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.PARAMETER}) 41 @Retention(RetentionPolicy.RUNTIME) 42 @com.fasterxml.jackson.annotation.JacksonAnnotation 43 public @interface JsonDeserialize 44 { 45 // // // Annotations for explicitly specifying deserialize/builder 46 47 /** 48 * Deserializer class to use for deserializing associated value. 49 * Depending on what is annotated, 50 * value is either an instance of annotated class (used globablly 51 * anywhere where class deserializer is needed); or only used for 52 * deserializing property access via a setter method. 53 */ 54 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties using()55 public Class<? extends JsonDeserializer> using() 56 default JsonDeserializer.None.class; 57 58 /** 59 * Deserializer class to use for deserializing contents (elements 60 * of a Collection/array, values of Maps) of annotated property. 61 * Can only be used on instances (methods, fields, constructors), 62 * and not value classes themselves. 63 */ 64 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties contentUsing()65 public Class<? extends JsonDeserializer> contentUsing() 66 default JsonDeserializer.None.class; 67 68 /** 69 * Deserializer class to use for deserializing Map keys 70 * of annotated property. 71 * Can only be used on instances (methods, fields, constructors), 72 * and not value classes themselves. 73 */ keyUsing()74 public Class<? extends KeyDeserializer> keyUsing() 75 default KeyDeserializer.None.class; 76 77 /** 78 * Annotation for specifying if an external Builder class is to 79 * be used for building up deserialized instances of annotated 80 * class. If so, an instance of referenced class is first constructed 81 * (possibly using a Creator method; or if none defined, using default 82 * constructor), and its "with-methods" are used for populating fields; 83 * and finally "build-method" is invoked to complete deserialization. 84 */ builder()85 public Class<?> builder() default Void.class; 86 87 // // // Annotations for specifying intermediate Converters (2.2+) 88 89 /** 90 * Which helper object (if any) is to be used to convert from Jackson-bound 91 * intermediate type (source type of converter) into actual property type 92 * (which must be same as result type of converter). This is often used 93 * for two-step deserialization; Jackson binds data into suitable intermediate 94 * type (like Tree representation), and converter then builds actual property 95 * type. 96 * 97 * @since 2.2 98 */ 99 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties converter()100 public Class<? extends Converter> converter() default Converter.None.class; 101 102 /** 103 * Similar to {@link #converter}, but used for values of structures types 104 * (List, arrays, Maps). 105 * 106 * @since 2.2 107 */ 108 @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties contentConverter()109 public Class<? extends Converter> contentConverter() default Converter.None.class; 110 111 112 // // // Annotations for explicitly specifying deserialization type 113 // // // (which is used for choosing deserializer, if not explicitly 114 // // // specified 115 116 /** 117 * Concrete type to deserialize values as, instead of type otherwise 118 * declared. Must be a subtype of declared type; otherwise an 119 * exception may be thrown by deserializer. 120 *<p> 121 * Bogus type {@link Void} can be used to indicate that declared 122 * type is used as is (i.e. this annotation property has no setting); 123 * this since annotation properties are not allowed to have null value. 124 *<p> 125 * Note: if {@link #using} is also used it has precedence 126 * (since it directly specified 127 * deserializer, whereas this would only be used to locate the 128 * deserializer) 129 * and value of this annotation property is ignored. 130 */ as()131 public Class<?> as() default Void.class; 132 133 /** 134 * Concrete type to deserialize keys of {@link java.util.Map} as, 135 * instead of type otherwise declared. 136 * Must be a subtype of declared type; otherwise an exception may be 137 * thrown by deserializer. 138 */ keyAs()139 public Class<?> keyAs() default Void.class; 140 141 /** 142 * Concrete type to deserialize content (elements 143 * of a Collection/array, values of Maps) values as, 144 * instead of type otherwise declared. 145 * Must be a subtype of declared type; otherwise an exception may be 146 * thrown by deserializer. 147 */ contentAs()148 public Class<?> contentAs() default Void.class; 149 } 150