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  * Annotation used for indicating that values of annotated type
10  * or property should be serializing so that instances either
11  * contain additional object identifier (in addition actual object
12  * properties), or as a reference that consists of an object id
13  * that refers to a full serialization. In practice this is done
14  * by serializing the first instance as full object and object
15  * identity, and other references to the object as reference values.
16  *<p>
17  * There are two main approaches to generating object identifier:
18  * either using a generator (either one of standard ones, or a custom
19  * generator), or using a value of a property. The latter case is
20  * indicated by using a placeholder generator marker
21  * {@link ObjectIdGenerators.PropertyGenerator}; former by using explicit generator.
22  * Object id has to be serialized as a property in case of POJOs;
23  * object identity is currently NOT support for JSON Array types
24  * (Java arrays or Lists) or Java Map types.
25  *<p>
26  * Finally, note that generator type of {@link ObjectIdGenerators.None}
27  * indicates that no Object Id should be included or used: it is included
28  * to allow suppressing Object Ids using mix-in annotations.
29  *
30  * @since 2.0
31  */
32 @Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE,
33     ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
34 @Retention(RetentionPolicy.RUNTIME)
35 @JacksonAnnotation
36 public @interface JsonIdentityInfo
37 {
38     /**
39      * Name of JSON property in which Object Id will reside: also,
40      * if "from property" marker generator is used, identifies
41      * property that will be accessed to get type id.
42      * If a property is used, name must match its external
43      * name (one defined by annotation, or derived from accessor
44      * name as per Java Bean Introspection rules).
45      *<p>
46      * Default value is <code>@id</code>.
47      */
property()48     public String property() default "@id";
49 
50     /**
51      * Generator to use for producing Object Identifier for objects:
52      * either one of pre-defined generators from
53      * {@link ObjectIdGenerator}, or a custom generator.
54      * Defined as class to instantiate.
55      *<p>
56      * Note that special type
57      * {@link ObjectIdGenerators.None}
58      * can be used to disable inclusion of Object Ids.
59      */
generator()60     public Class<? extends ObjectIdGenerator<?>> generator();
61 
62     /**
63      * Resolver to use for producing POJO from Object Identifier.
64      * <p>
65      * Default value is {@link SimpleObjectIdResolver}
66      *
67      * @since 2.4
68      */
resolver()69     public Class<? extends ObjectIdResolver> resolver() default SimpleObjectIdResolver.class;
70 
71     /**
72      * Scope is used to define applicability of an Object Id: all ids
73      * must be unique within their scope; where scope is defined
74      * as combination of this value and generator type.
75      * Comparison is simple equivalence, meaning that both type
76      * generator type and scope class must be the same.
77      *<p>
78      * Scope is used for determining how many generators are needed;
79      * more than one scope is typically only needed if external Object Ids
80      * have overlapping value domains (i.e. are only unique within some
81      * limited scope)
82      */
scope()83     public Class<?> scope() default Object.class;
84 }
85