001 /**
002 * Copyright (C) 2009-2011 the original author or authors.
003 * See the notice.md file distributed with this work for additional
004 * information regarding copyright ownership.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package org.codehaus.jackson.annotate;
020
021 import java.lang.annotation.ElementType;
022 import java.lang.annotation.Retention;
023 import java.lang.annotation.RetentionPolicy;
024 import java.lang.annotation.Target;
025
026 /**
027 * Annotation used for configuring details of if and how type information is
028 * used with JSON serialization and deserialization, to preserve information
029 * about actual class of Object instances. This is necessarily for polymorphic
030 * types, and may also be needed to link abstract declared types and matching
031 * concrete implementation.
032 *<p>
033 * Some examples of typical annotations:
034 *<pre>
035 * // Include Java class name ("com.myempl.ImplClass") as JSON property "class"
036 * \@JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class")
037 *
038 * // Include logical type name (defined in impl classes) as wrapper; 2 annotations
039 * \@JsonTypeInfo(use=Id.NAME, include=As.WRAPPER_OBJECT)
040 * \@JsonSubTypes({com.myemp.Impl1.class, com.myempl.Impl2.class})
041 *</pre>
042 * Alternatively you can also define fully customized type handling by using
043 * {@link org.codehaus.jackson.map.annotate.JsonTypeResolver} annotation.
044 *<p>
045 * NOTE: originally this annotation was only available to use with types (classes),
046 * but starting with 1.7, it is also allowed for properties (fields, methods,
047 * constructor parameters).
048 *<p>
049 * When used for properties (fields, methods), there annotation always defines
050 * to <b>values</b>: specifically, when applied to a <code>Collection</code> or
051 * <code>Map</code> property, it will <b>not</b> apply to container type but
052 * to contained values. This is identical to how JAXB handles type information
053 * annotations; and is chosen since it is the dominant use case. There is no
054 * per-property way to force type information to be included for type of
055 * container itself.
056 *
057 * @see org.codehaus.jackson.map.annotate.JsonTypeResolver
058 * @since 1.5 (but available to fields, methods and constructor params since 1.7)
059 *
060 * @author tatu
061 */
062 @Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
063 @Retention(RetentionPolicy.RUNTIME)
064 @JacksonAnnotation
065 public @interface JsonTypeInfo
066 {
067 /*
068 /**********************************************************
069 /* Value enumerations used for properties
070 /**********************************************************
071 */
072
073 /**
074 * Definition of different type identifiers that can be included in JSON
075 * during serialization, and used for deserialization.
076 */
077 public enum Id {
078 /**
079 * This means that no explicit type metadata is included, and typing is
080 * purely done using contextual information possibly augmented with other
081 * annotations.
082 *<p>
083 * Note: no {@link org.codehaus.jackson.map.jsontype.TypeIdResolver}
084 * is constructed if this value is used.
085 */
086 NONE(null),
087
088 /**
089 * Means that fully-qualified Java class name is used as the type identifier.
090 */
091 CLASS("@class"),
092
093 /**
094 * Means that Java class name with minimal path is used as the type identifier.
095 * Minimal means that only class name, and that part of preceding Java
096 * package name is included that is needed to construct fully-qualified name
097 * given fully-qualified name of the declared supertype.
098 * For example, for supertype "com.foobar.Base", and concrete type
099 * "com.foo.Impl", only "Impl" would be included; and for "com.foo.impl.Impl2"
100 * only "impl.Impl2" would be included.
101 *<p>
102 * If all related classes are in the same Java package, this option can reduce
103 * amount of type information overhead, especially for small types.
104 * However, please note that using this alternative is inherently risky since it
105 * assumes that the
106 * supertype can be reliably detected. Given that it is based on declared type
107 * (since ultimate supertype, <code>java.lang.Object</code> would not be very
108 * useful reference point), this may not always work as expected.
109 */
110 MINIMAL_CLASS("@c"),
111
112 /**
113 * Means that logical type name is used as type information; name will then need
114 * to be separately resolved to actual concrete type (Class).
115 */
116 NAME("@type"),
117
118 /**
119 * Means that typing mechanism uses customized handling, with possibly
120 * custom configuration. This means that semantics of other properties is
121 * not defined by Jackson package, but by the custom implementation.
122 */
123 CUSTOM(null)
124 ;
125
126 private final String _defaultPropertyName;
127
128 private Id(String defProp) {
129 _defaultPropertyName = defProp;
130 }
131
132 public String getDefaultPropertyName() { return _defaultPropertyName; }
133 }
134
135 /**
136 * Definition of standard type inclusion mechanisms for type metadata.
137 * Used for standard metadata types, except for {@link Id#NONE}.
138 * May or may not be used for custom types ({@link Id#CUSTOM}).
139 */
140 public enum As {
141 /**
142 * Inclusion mechanism that uses a single configurable property, included
143 * along with actual data (POJO properties) as a separate meta-property.
144 * <p>
145 * Default choice for inclusion.
146 */
147 PROPERTY,
148
149 /**
150 * Inclusion mechanism that wraps typed JSON value (POJO
151 * serialized as JSON) in
152 * a JSON Object that has a single entry,
153 * where field name is serialized type identifier,
154 * and value is the actual JSON value.
155 *<p>
156 * Note: can only be used if type information can be serialized as
157 * String. This is true for standard type metadata types, but not
158 * necessarily for custom types.
159 */
160 WRAPPER_OBJECT,
161
162 /**
163 * Inclusion mechanism that wraps typed JSON value (POJO
164 * serialized as JSON) in
165 * a 2-element JSON array: first element is the serialized
166 * type identifier, and second element the serialized POJO
167 * as JSON Object.
168 */
169 WRAPPER_ARRAY,
170 ;
171 }
172
173 /*
174 /**********************************************************
175 /* Annotation properties
176 /**********************************************************
177 */
178
179 /**
180 * What kind of type metadata is to be used for serializing and deserializing
181 * type information for instances of annotated type (and its subtypes
182 * unless overridden)
183 */
184 public Id use();
185
186 /**
187 * What mechanism is used for including type metadata (if any; for
188 * {@link Id#NONE} nothing is included). Default
189 *<p>
190 * Note that for type metadata type of {@link Id#CUSTOM},
191 * this setting may or may not have any effect.
192 */
193 public As include() default As.PROPERTY;
194
195 /**
196 * Property names used when type inclusion method ({@link As#PROPERTY}) is used
197 * (or possibly when using type metadata of type {@link Id#CUSTOM}).
198 *<p>
199 * Default property name used if this property is not explicitly defined
200 * (or is set to empty String) is based on
201 * type metadata type ({@link #use}) used.
202 */
203 public String property() default "";
204 }