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 */ mode()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