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 constructors and factory
10  * methods as one to use for instantiating new instances of the associated
11  * class.
12  *<p>
13  * NOTE: when annotating creator methods (constructors, factory methods),
14  * method must either be:
15  *<ul>
16  * <li>Single-argument constructor/factory method without {@link JsonProperty}
17  *    annotation for the argument: if so, this is so-called "delegate creator",
18  *    in which case Jackson first binds JSON into type of the argument, and
19  *    then calls creator. This is often used in conjunction with {@link JsonValue}
20  *    (used for serialization).
21  *   </li>
22  * <li>Constructor/factory method where <b>every argument</b> is annotated with
23  *   either {@link JsonProperty} or {@link JacksonInject}, to indicate name
24  *   of property to bind to
25  *  </li>
26  * </ul>
27  * Also note that all {@link JsonProperty} annotations must specify actual name
28  * (NOT empty String for "default") unless you use one of extension modules
29  * that can detect parameter name; this because default JDK versions before 8
30  * have not been able to store and/or retrieve parameter names from bytecode.
31  * But with JDK 8 (or using helper libraries such as Paranamer, or other JVM
32  * languages like Scala or Kotlin), specifying name is optional.
33  *<p>
34  * One common use case is to use a delegating Creator to construct instances from
35  * scalar values (like <code>java.lang.String</code>) during deserialization,
36  * and serialize values using {@link JsonValue}.
37  *<p>
38  * NOTE: As of Jackson 2.6, use of {@link JsonProperty#required()} is supported
39  * for Creator methods (but not necessarily for regular setters or fields!).
40  * 
41  * @see JsonProperty
42  */
43 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR})
44 @Retention(RetentionPolicy.RUNTIME)
45 @JacksonAnnotation
46 public @interface JsonCreator
47 {
48     /**
49      * Property that is used to indicate how argument(s) is/are bound for creator,
50      * in cases there may be multiple alternatives. Currently the one case is that
51      * of a single-argument creator method, for which both so-called "delegating" and
52      * "property-based" bindings are possible: since
53      * delegating mode can not be used for multi-argument creators, the only choice
54      * there is "property-based" mode.
55      * Check {@link Mode} for more complete explanation of possible choices.
56      *<p>
57      * Default value of {@link Mode#DEFAULT} means that caller is to use standard
58      * heuristics for choosing mode to use.
59      * 
60      * @since 2.5
61      */
62     public Mode mode() default Mode.DEFAULT;
63
64     /**
65      * @since 2.5
66      */
67     public enum Mode {
68         /**
69          * Pseudo-mode that indicates that caller is to use default heuristics for
70          * choosing mode to use. This typically favors use of delegating mode for
71          * single-argument creators that take structured types.
72          */
73         DEFAULT,
74
75         /**
76          * Mode that indicates that if creator takes a single argument, the whole incoming
77          * data value is to be bound into declared type of that argument; this "delegate"
78          * value is then passed as the argument to creator.
79          */
80         DELEGATING,
81
82         /**
83          * Mode that indicates that the argument(s) for creator are to be bound from matching
84          * properties of incoming Object value, using creator argument names (explicit or implicit)
85          * to match incoming Object properties to arguments.
86          *<p>
87          * Note that this mode is currently (2.5) always used for multiple-argument creators;
88          * the only ambiguous case is that of a single-argument creator.
89          */
90         PROPERTIES,
91
92         /**
93          * Pseudo-mode that indicates that creator is not to be used. This can be used as a result
94          * value for explicit disabling, usually either by custom annotation introspector,
95          * or by annotation mix-ins (for example when choosing different creator).
96          */
97         DISABLED
98     }
99 }
100