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  *  &#64;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 &#64;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