This is an automated email from the git hooks/post-receive script. tjaalton pushed a commit to branch master in repository jackson-annotations.
commit 889181b402afa7aa947c75e32efd81682ddec893 Author: Tatu Saloranta <[email protected]> Date: Thu Dec 22 21:32:04 2011 -0800 First seemingly working version --- .gitignore | 21 ++ pom.xml | 6 +- .../jackson/annotation/JacksonAnnotation.java | 20 ++ .../jackson/annotation/JsonAnyGetter.java | 25 +++ .../jackson/annotation/JsonAnySetter.java | 24 +++ .../jackson/annotation/JsonAutoDetect.java | 135 ++++++++++++ .../jackson/annotation/JsonBackReference.java | 41 ++++ .../fasterxml/jackson/annotation/JsonCreator.java | 19 ++ .../fasterxml/jackson/annotation/JsonGetter.java | 35 +++ .../fasterxml/jackson/annotation/JsonIgnore.java | 57 +++++ .../jackson/annotation/JsonIgnoreProperties.java | 48 +++++ .../jackson/annotation/JsonIgnoreType.java | 33 +++ .../jackson/annotation/JsonManagedReference.java | 41 ++++ .../fasterxml/jackson/annotation/JsonProperty.java | 38 ++++ .../jackson/annotation/JsonPropertyOrder.java | 46 ++++ .../fasterxml/jackson/annotation/JsonRawValue.java | 33 +++ .../fasterxml/jackson/annotation/JsonSetter.java | 33 +++ .../fasterxml/jackson/annotation/JsonSubTypes.java | 44 ++++ .../fasterxml/jackson/annotation/JsonTypeInfo.java | 236 +++++++++++++++++++++ .../fasterxml/jackson/annotation/JsonTypeName.java | 28 +++ .../jackson/annotation/JsonUnwrapped.java | 76 +++++++ .../fasterxml/jackson/annotation/JsonValue.java | 46 ++++ .../fasterxml/jackson/annotation/package-info.java | 16 ++ 23 files changed, 1097 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..84914ec --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# use glob syntax. +syntax: glob +*.class +*~ +*.bak +*.off +*.old +.DS_Store + +# building +target + +# Eclipse +.classpath +.project +.settings + +# IDEA +*.iml +*.ipr +*.iws diff --git a/pom.xml b/pom.xml index 5bc50d2..1542ca4 100644 --- a/pom.xml +++ b/pom.xml @@ -118,20 +118,18 @@ <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> - <version>2.3.4</version> + <version>2.3.6</version> <extensions>true</extensions> <configuration> <instructions> <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName> <Bundle-Vendor>fasterml.com</Bundle-Vendor> <Import-Package> -com.fasterxml.jackson.annotation </Import-Package> <Private-Package> </Private-Package> <Export-Package> -com.fasterxml.jackson.core, -com.fasterxml.jackson.core.impl +com.fasterxml.jackson.annotation </Export-Package> </instructions> </configuration> diff --git a/src/main/java/com/fasterxml/jackson/annotation/JacksonAnnotation.java b/src/main/java/com/fasterxml/jackson/annotation/JacksonAnnotation.java new file mode 100644 index 0000000..4e80094 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JacksonAnnotation.java @@ -0,0 +1,20 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Meta-annotation (annotations used on other annotations) + * used for marking all annotations that are + * part of Jackson package. Can be used for recognizing all + * Jackson annotations generically, and in future also for + * passing other generic annotation configuration. + */ +@Target({ElementType.ANNOTATION_TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface JacksonAnnotation +{ + // for now, a pure tag annotation, no parameters +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonAnyGetter.java b/src/main/java/com/fasterxml/jackson/annotation/JsonAnyGetter.java new file mode 100644 index 0000000..faecfdb --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonAnyGetter.java @@ -0,0 +1,25 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that can be used to define a non-static, + * no-argument method or member field as something of a reverse of + * {@link JsonAnySetter} method; basically being used like a + * getter but such that contents of the returned Map (type <b>must</b> be + * {@link java.util.Map}) are serialized as if they were actual properties + * of the bean that contains method/field with this annotations. + * As with {@link JsonAnySetter}, only one property should be annotated + * with this annotation. + * + * @since 1.6 + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonAnyGetter +{ +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonAnySetter.java b/src/main/java/com/fasterxml/jackson/annotation/JsonAnySetter.java new file mode 100644 index 0000000..cd88945 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonAnySetter.java @@ -0,0 +1,24 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that can be used to define a non-static, + * single-argument method, to be used as a "fallback" handler + * for all otherwise unrecognized properties found from Json content. + * It is similar to {@link javax.xml.bind.annotation.XmlAnyElement} + * in behavior; and can only be used to denote a single property + * per type. + *<p> + * If used, all otherwise unmapped key-value pairs from Json Object + * structs are added to the property (of type Map or bean). + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonAnySetter +{ +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonAutoDetect.java b/src/main/java/com/fasterxml/jackson/annotation/JsonAutoDetect.java new file mode 100644 index 0000000..b1db30a --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonAutoDetect.java @@ -0,0 +1,135 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; +import java.lang.reflect.Member; +import java.lang.reflect.Modifier; + +/** + * Class annotation that can be used to define which kinds of Methods + * are to be detected by auto-detection. + * Auto-detection means using name conventions + * and/or signature templates to find methods to use for data binding. + * For example, so-called "getters" can be auto-detected by looking for + * public member methods that return a value, do not take argument, + * and have prefix "get" in their name. + *<p> + * Pseudo-value <code>NONE</code> means that all auto-detection is disabled + * for the <b>specific</b> class that annotation is applied to (including + * its super-types, but only when resolving that class). + * Pseudo-value <code>ALWAYS</code> means that auto-detection is enabled + * for all method types for the class in similar way. + *<p> + * The default value is <code>ALWAYS</code>: that is, by default, auto-detection + * is enabled for all classes unless instructed otherwise. + *<p> + * Starting with version 1.5, it is also possible to use more fine-grained + * definitions, to basically define minimum visibility level needed. Defaults + * are different for different types (getters need to be public; setters can + * have any access modifier, for example). + */ +@Target(ElementType.TYPE) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonAutoDetect +{ + /** + * Enumeration for possible visibility thresholds (minimum visibility) + * that can be used to limit which methods (and fields) are + * auto-detected. + */ + public enum Visibility { + /** + * Value that means that all kinds of access modifiers are acceptable, + * from private to public. + */ + ANY, + /** + * Value that means that any other access modifier other than 'private' + * is considered auto-detectable. + */ + NON_PRIVATE, + /** + * Value that means access modifiers 'protected' and 'public' are + * auto-detectable (and 'private' and "package access" == no modifiers + * are not) + */ + PROTECTED_AND_PUBLIC, + /** + * Value to indicate that only 'public' access modifier is considered + * auto-detectable. + */ + PUBLIC_ONLY, + /** + * Value that indicates that no access modifiers are auto-detectable: + * this can be used to explicitly disable auto-detection for specified + * types. + */ + NONE, + + /** + * Value that indicates that default visibility level (whatever it is, + * depends on context) is to be used. This usually means that inherited + * value (from parent visibility settings) is to be used. + */ + DEFAULT; + + public boolean isVisible(Member m) { + switch (this) { + case ANY: + return true; + case NONE: + return false; + case NON_PRIVATE: + return !Modifier.isPrivate(m.getModifiers()); + case PROTECTED_AND_PUBLIC: + if (Modifier.isProtected(m.getModifiers())) { + return true; + } + // fall through to public case: + case PUBLIC_ONLY: + return Modifier.isPublic(m.getModifiers()); + } + return false; + } + } + + /** + * Minimum visibility required for auto-detecting regular getter methods. + * + * @since 1.5 + */ + Visibility getterVisibility() default Visibility.DEFAULT; + + /** + * Minimum visibility required for auto-detecting is-getter methods. + * + * @since 1.5 + */ + Visibility isGetterVisibility() default Visibility.DEFAULT; + + /** + * Minimum visibility required for auto-detecting setter methods. + * + * @since 1.5 + */ + Visibility setterVisibility() default Visibility.DEFAULT; + + /** + * Minimum visibility required for auto-detecting Creator methods, + * except for no-argument constructors (which are always detected + * no matter what). + * + * @since 1.5 + */ + Visibility creatorVisibility() default Visibility.DEFAULT; + + /** + * Minimum visibility required for auto-detecting member fields. + * + * @since 1.5 + */ + Visibility fieldVisibility() default Visibility.DEFAULT; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonBackReference.java b/src/main/java/com/fasterxml/jackson/annotation/JsonBackReference.java new file mode 100644 index 0000000..0391d70 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonBackReference.java @@ -0,0 +1,41 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Annotation used to indicate that associated property is part of + * two-way linkage between fields; and that its role is "child" (or "back") link. + * Value type of the property must be a bean: it can not be a Collection, Map, + * Array or enumeration. + * Linkage is handled such that the property + * annotated with this annotation is not serialized; and during deserialization, + * its value is set to instance that has the "managed" (forward) link. + *<p> + * All references have logical name to allow handling multiple linkages; typical case + * would be that where nodes have both parent/child and sibling linkages. If so, + * pairs of references should be named differently. + * It is an error for a class to have multiple back references with same name, + * even if types pointed are different. + *<p> + * Note: only methods and fields can be annotated with this annotation: constructor + * arguments should NOT be annotated, as they can not be either managed or back + * references. + * + * @author tatu + */ +@Target({ElementType.FIELD, ElementType.METHOD}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonBackReference +{ + /** + * Logical have for the reference property pair; used to link managed and + * back references. Default name can be used if there is just single + * reference pair (for example, node class that just has parent/child linkage, + * consisting of one managed reference and matching back reference) + */ + public String value() default "defaultReference"; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java new file mode 100644 index 0000000..2b5cb66 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java @@ -0,0 +1,19 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that can be used to define constructors and factory + * methods as one to use for instantiating new instances of the associated + * class. + */ +@Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonCreator +{ + // no values, since there's no property +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonGetter.java b/src/main/java/com/fasterxml/jackson/annotation/JsonGetter.java new file mode 100644 index 0000000..33f4ba6 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonGetter.java @@ -0,0 +1,35 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that can be used to define a non-static, + * no-argument value-returning (non-void) method to be used as a "getter" + * for a logical property, + * as an alternative to recommended + * {@link JsonProperty} annotation (which was introduced in version 1.1). + *<p> + * Getter means that when serializing Object instance of class that has + * this method (possibly inherited from a super class), a call is made + * through the method, and return value will be serialized as value of + * the property. + * + * @deprecated Use {@link JsonProperty} instead (deprecated since version 1.5) + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +@Deprecated +public @interface JsonGetter +{ + /** + * Defines name of the logical property this + * method is used to access ("get"); empty String means that + * name should be derived from the underlying method (using + * standard Bean name detection rules) + */ + String value() default ""; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonIgnore.java b/src/main/java/com/fasterxml/jackson/annotation/JsonIgnore.java new file mode 100644 index 0000000..235680d --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonIgnore.java @@ -0,0 +1,57 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that indicates that the annotated method or field is to be + * ignored by introspection-based + * serialization and deserialization functionality. That is, it should + * not be consider a "getter", "setter" or "creator". + *<p> + * In addition, starting with Jackson 1.9, if this is the only annotation + * associated with a property, it will also cause cause the whole + * property to be ignored: that is, if setter has this annotation and + * getter has no annotations, getter is also effectively ignored. + * It is still possible for different accessors to use different + * annotations; so if only "getter" is to be ignored, other accessors + * (setter or field) would need explicit annotation to prevent + * ignoral (usually {@link JsonProperty}). + * <p> + * For example, a "getter" method that would otherwise denote + * a property (like, say, "getValue" to suggest property "value") + * to serialize, would be ignored and no such property would + * be output unless another annotation defines alternative method to use. + *<p> + * Before version 1.9, this annotation worked purely on method-by-method (or field-by-field) + * basis; annotation on one method or field does not imply ignoring other methods + * or fields. However, with version 1.9 and above, annotations associated + * with various accessors (getter, setter, field, constructor parameter) of + * a logical property are combined; meaning that annotations may be effectly + * combined. + *<p> + * Annotation is usually used just a like a marker annotation, that + * is, without explicitly defining 'value' argument (which defaults + * to <code>true</code>): but argument can be explicitly defined. + * This can be done to override an existing JsonIgnore by explictly + * defining one with 'false' argument. + *<p> + * Annotation is similar to {@link javax.xml.bind.annotation.XmlTransient} + */ +@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonIgnore +{ + /** + * Optional argument that defines whether this annotation is active + * or not. The only use for value 'false' if for overriding purposes + * (which is not needed often); most likely it is needed for use + * with "mix-in annotations" (aka "annotation overrides"). + * For most cases, however, default value of "true" is just fine + * and should be omitted. + */ + boolean value() default true; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonIgnoreProperties.java b/src/main/java/com/fasterxml/jackson/annotation/JsonIgnoreProperties.java new file mode 100644 index 0000000..d64a9f7 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonIgnoreProperties.java @@ -0,0 +1,48 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Annotation that can be used to either suppress serialization of + * properties (during serialization), or ignore processing of + * JSON properties read (during deserialization). + *<p> + * Example: + *<pre> + * // to prevent specified fields from being serialized or deserialized + * // (i.e. not include in JSON output; or being set even if they were included) + * \@JsonIgnoreProperties({ "internalId", "secretKey" }) + * // To ignore any unknown properties in JSON input without exception: + * \@JsonIgnoreProperties(ignoreUnknown=true) + *</pre> + *<p> + * Only applicable to classes, not for properties (getters, setters, fields). + * + * @since 1.4 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonIgnoreProperties +{ + /** + * Names of properties to ignore. + */ + public String[] value() default { }; + + /** + * Property that defines whether it is ok to just ignore any + * unrecognized properties during deserialization. + * If true, all properties that are unrecognized -- that is, + * there are no setters or creators that accept them -- are + * ignored without warnings (although handlers for unknown + * properties, if any, will still be called) without + * exception. + *<p> + * Does not have any effect on serialization. + */ + public boolean ignoreUnknown() default false; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonIgnoreType.java b/src/main/java/com/fasterxml/jackson/annotation/JsonIgnoreType.java new file mode 100644 index 0000000..476a722 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonIgnoreType.java @@ -0,0 +1,33 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that indicates that all properties of annotated + * type are to be ignored during serialization and deserialization. + *<p> + * Note: annotation does have boolean 'value' property (which defaults + * to 'true'), so that it is actually possible to override value + * using mix-in annotations. + * + * @since 1.7 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonIgnoreType +{ + /** + * Optional argument that defines whether this annotation is active + * or not. The only use for value 'false' if for overriding purposes + * (which is not needed often); most likely it is needed for use + * with "mix-in annotations" ("annotation overrides"). + * For most cases, however, default value of "true" is just fine + * and should be omitted. + */ + boolean value() default true; + +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonManagedReference.java b/src/main/java/com/fasterxml/jackson/annotation/JsonManagedReference.java new file mode 100644 index 0000000..745479f --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonManagedReference.java @@ -0,0 +1,41 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Annotation used to indicate that annotated property is part of + * two-way linkage between fields; and that its role is "parent" (or "forward") link. + * Value type (class) of property must have a single compatible property annotated with + * {@link JsonBackReference}. Linkage is handled such that the property + * annotated with this annotation is handled normally (serialized normally, no + * special handling for deserialization); it is the matching back reference + * that requires special handling + *<p> + * All references have logical name to allow handling multiple linkages; typical case + * would be that where nodes have both parent/child and sibling linkages. If so, + * pairs of references should be named differently. + * It is an error for a class too have multiple managed references with same name, + * even if types pointed are different. + *<p> + * Note: only methods and fields can be annotated with this annotation: constructor + * arguments should NOT be annotated, as they can not be either managed or back + * references. + * + * @author tatu + */ +@Target({ElementType.FIELD, ElementType.METHOD}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonManagedReference +{ + /** + * Logical have for the reference property pair; used to link managed and + * back references. Default name can be used if there is just single + * reference pair (for example, node class that just has parent/child linkage, + * consisting of one managed reference and matching back reference) + */ + public String value() default "defaultReference"; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java b/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java new file mode 100644 index 0000000..392ab10 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java @@ -0,0 +1,38 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that can be used to define a non-static + * method as a "setter" or "getter" for a logical property + * (depending on its signature), + * or non-static object field to be used (serialized, deserialized) as + * a logical property. + *<p> + * Default value ("") indicates that the field name is used + * as the property name without any modifications, but it + * can be specified to non-empty value to specify different + * name. Property name refers to name used externally, as + * the field name in Json objects. + *<p> + * NOTE: since version 1.1, annotation has also been applicable + * to fields (not with 1.0). + *<p> + * NOTE: since version 1.2, annotation has also been applicable + * to (constructor) parameters + */ +@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonProperty +{ + /** + * Defines name of the logical property, i.e. Json object field + * name to use for the property: if empty String (which is the + * default), will use name of the field that is annotated. + */ + String value() default ""; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonPropertyOrder.java b/src/main/java/com/fasterxml/jackson/annotation/JsonPropertyOrder.java new file mode 100644 index 0000000..989312c --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonPropertyOrder.java @@ -0,0 +1,46 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Annotation that can be used to define ordering (possibly partial) to use + * when serializing object properties. Properties included in annotation + * declaration will be serialized first (in defined order), followed by + * any properties not included in the definition. + * Annotation definition will override any implicit orderings (such as + * guarantee that Creator-properties are serialized before non-creator + * properties) + *<p> + * Examples: + *<pre> + * // ensure that "id" and "name" are output before other properties + * <div>@</div>JsonPropertyOrder({ "id", "name" }) + * // order any properties that don't have explicit setting using alphabetic order + * <div>@</div>JsonPropertyOrder(alphabetic=true) + *</pre> + *<p> + * This annotation has no effect on deserialization. + * + * @since 1.4 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonPropertyOrder +{ + /** + * Order in which properties of annotated object are to be serialized in. + */ + public String[] value() default { }; + + /** + * Property that defines what to do regarding ordering of properties + * not explicitly included in annotation instance. If set to true, + * they will be alphabetically ordered; if false, order is + * undefined (default setting) + */ + public boolean alphabetic() default false; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonRawValue.java b/src/main/java/com/fasterxml/jackson/annotation/JsonRawValue.java new file mode 100644 index 0000000..0b0b51b --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonRawValue.java @@ -0,0 +1,33 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that indicates that the annotated method + * or field should be serialized by including literal String value + * of the property as is, without quoting of characters. + * This can be useful for injecting values already serialized in JSON or + * passing javascript function definitions from server to a javascript client. + *<p> + * Warning: the resulting JSON stream may be invalid depending on your input value. + * + * @since 1.7.0 + */ +@Target( { ElementType.METHOD, ElementType.FIELD }) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonRawValue +{ + /** + * Optional argument that defines whether this annotation is active + * or not. The only use for value 'false' if for overriding purposes + * (which is not needed often); most likely it is needed for use + * with "mix-in annotations" (aka "annotation overrides"). + * For most cases, however, default value of "true" is just fine + * and should be omitted. + */ + boolean value() default true; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonSetter.java b/src/main/java/com/fasterxml/jackson/annotation/JsonSetter.java new file mode 100644 index 0000000..4fd5de2 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonSetter.java @@ -0,0 +1,33 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation that can be used to define a non-static, + * single-argument method to be used as a "setter" for a logical property + * as an alternative to recommended + * {@link JsonProperty} annotation (which was introduced in version 1.1). + *<p> + * Setter means that when a property with matching name is encountered in + * JSON content, this method will be used to set value of the property. + *<p> + * NOTE: this annotation was briefly deprecated for version 1.5; but has + * since been un-deprecated to both allow for asymmetric naming (possibly + * different name when reading and writing JSON), and more importantly to + * allow multi-argument setter method in future. + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonSetter +{ + /** + * Optional default argument that defines logical property this + * method is used to modify ("set"); this is the property + * name used in JSON content. + */ + String value() default ""; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonSubTypes.java b/src/main/java/com/fasterxml/jackson/annotation/JsonSubTypes.java new file mode 100644 index 0000000..65578c3 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonSubTypes.java @@ -0,0 +1,44 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Annotation used with {@link JsonTypeInfo} to indicate sub types of serializable + * polymorphic types, and to associate logical names used within JSON content + * (which is more portable than using physical Java class names). + * + * @since 1.5 (but available to fields, methods and constructor params only since 1.8) + */ +@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonSubTypes { + /** + * Subtypes of the annotated type (annotated class, or property value type + * associated with the annotated method). These will be checked recursively + * so that types can be defined by only including direct subtypes. + */ + public Type[] value(); + + /** + * Definition of a subtype, along with optional name. If name is missing, class + * of the type will be checked for {@link JsonTypeName} annotation; and if that + * is also missing or empty, a default + * name will be constructed by type id mechanism. + * Default name is usually based on class name. + */ + public @interface Type { + /** + * Class of the subtype + */ + public Class<?> value(); + + /** + * Logical type name used as the type identifier for the class + */ + public String name() default ""; + } +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java new file mode 100644 index 0000000..1daf07c --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeInfo.java @@ -0,0 +1,236 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.*; + +/** + * Annotation used for configuring details of if and how type information is + * used with JSON serialization and deserialization, to preserve information + * about actual class of Object instances. This is necessarily for polymorphic + * types, and may also be needed to link abstract declared types and matching + * concrete implementation. + *<p> + * Some examples of typical annotations: + *<pre> + * // Include Java class name ("com.myempl.ImplClass") as JSON property "class" + * @JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class") + * + * // Include logical type name (defined in impl classes) as wrapper; 2 annotations + * @JsonTypeInfo(use=Id.NAME, include=As.WRAPPER_OBJECT) + * @JsonSubTypes({com.myemp.Impl1.class, com.myempl.Impl2.class}) + *</pre> + * Alternatively you can also define fully customized type handling by using + * {@link org.codehaus.jackson.map.annotate.JsonTypeResolver} annotation. + *<p> + * NOTE: originally this annotation was only available to use with types (classes), + * but starting with 1.7, it is also allowed for properties (fields, methods, + * constructor parameters). + *<p> + * When used for properties (fields, methods), this annotation applies + * to <b>values</b>: so when applied to structure types + * (like {@link java.util.Collection}, {@link java.util.Map}, arrays), + * will apply to contained values, not the container; + * for non-structured types there is no difference. + * This is identical to how JAXB handles type information + * annotations; and is chosen since it is the dominant use case. + * There is no per-property way to force type information to be included + * for type of container (structured type); for container types one has + * to use annotation for type declaration. + * + * @see org.codehaus.jackson.map.annotate.JsonTypeResolver + * + * @since 1.5 (but available to fields, methods and constructor parameters since 1.7) + * + * @author tatu + */ +@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonTypeInfo +{ + /* + /********************************************************** + /* Value enumerations used for properties + /********************************************************** + */ + + /** + * Definition of different type identifiers that can be included in JSON + * during serialization, and used for deserialization. + */ + public enum Id { + /** + * This means that no explicit type metadata is included, and typing is + * purely done using contextual information possibly augmented with other + * annotations. + *<p> + * Note: no {@link org.codehaus.jackson.map.jsontype.TypeIdResolver} + * is constructed if this value is used. + */ + NONE(null), + + /** + * Means that fully-qualified Java class name is used as the type identifier. + */ + CLASS("@class"), + + /** + * Means that Java class name with minimal path is used as the type identifier. + * Minimal means that only the class name, and that part of preceding Java + * package name is included that is needed to construct fully-qualified name + * given fully-qualified name of the declared supertype; additionally a single + * leading dot ('.') must be used to indicate that partial class name is used. + * For example, for supertype "com.foobar.Base", and concrete type + * "com.foo.Impl", only ".Impl" would be included; and for "com.foo.impl.Impl2" + * only ".impl.Impl2" would be included.<br /> + * <b>NOTE</b>: leading dot ('.') MUST be used to denote partial (minimal) name; + * if it is missing, value is assumed to be fully-qualified name. Fully-qualified + * name is used in cases where subtypes are not in same package (or sub-package + * thereof) as base class. + *<p> + * If all related classes are in the same Java package, this option can reduce + * amount of type information overhead, especially for small types. + * However, please note that using this alternative is inherently risky since it + * assumes that the + * supertype can be reliably detected. Given that it is based on declared type + * (since ultimate supertype, <code>java.lang.Object</code> would not be very + * useful reference point), this may not always work as expected. + */ + MINIMAL_CLASS("@c"), + + /** + * Means that logical type name is used as type information; name will then need + * to be separately resolved to actual concrete type (Class). + */ + NAME("@type"), + + /** + * Means that typing mechanism uses customized handling, with possibly + * custom configuration. This means that semantics of other properties is + * not defined by Jackson package, but by the custom implementation. + */ + CUSTOM(null) + ; + + private final String _defaultPropertyName; + + private Id(String defProp) { + _defaultPropertyName = defProp; + } + + public String getDefaultPropertyName() { return _defaultPropertyName; } + } + + /** + * Definition of standard type inclusion mechanisms for type metadata. + * Used for standard metadata types, except for {@link Id#NONE}. + * May or may not be used for custom types ({@link Id#CUSTOM}). + */ + public enum As { + /** + * Inclusion mechanism that uses a single configurable property, included + * along with actual data (POJO properties) as a separate meta-property. + * <p> + * Default choice for inclusion. + */ + PROPERTY, + + /** + * Inclusion mechanism that wraps typed JSON value (POJO + * serialized as JSON) in + * a JSON Object that has a single entry, + * where field name is serialized type identifier, + * and value is the actual JSON value. + *<p> + * Note: can only be used if type information can be serialized as + * String. This is true for standard type metadata types, but not + * necessarily for custom types. + */ + WRAPPER_OBJECT, + + /** + * Inclusion mechanism that wraps typed JSON value (POJO + * serialized as JSON) in + * a 2-element JSON array: first element is the serialized + * type identifier, and second element the serialized POJO + * as JSON Object. + */ + WRAPPER_ARRAY, + + /** + * Inclusion mechanism similar to <code>PROPERTY</code>, except that + * property is included one-level higher in hierarchy, i.e. as sibling + * property at same level as JSON Object to type. + * Note that this choice <b>can only be used for properties</b>, not + * for types (classes). Trying to use it for classes will result in + * inclusion strategy of basic <code>PROPERTY</code> instead. + * + * @since 1.9 + */ + EXTERNAL_PROPERTY + ; + } + + /* + /********************************************************** + /* Annotation properties + /********************************************************** + */ + + /** + * What kind of type metadata is to be used for serializing and deserializing + * type information for instances of annotated type (and its subtypes + * unless overridden) + */ + public Id use(); + + /** + * What mechanism is used for including type metadata (if any; for + * {@link Id#NONE} nothing is included). Default + *<p> + * Note that for type metadata type of {@link Id#CUSTOM}, + * this setting may or may not have any effect. + */ + public As include() default As.PROPERTY; + + /** + * Property names used when type inclusion method ({@link As#PROPERTY}) is used + * (or possibly when using type metadata of type {@link Id#CUSTOM}). + *<p> + * Default property name used if this property is not explicitly defined + * (or is set to empty String) is based on + * type metadata type ({@link #use}) used. + */ + public String property() default ""; + + /** + * Optional property that can be used to specify default implementation + * class to use if type identifier is either not present, or can not + * be mapped to a registered type (which can occur for ids, but not when + * specifying explicit class to use). + *<p> + * Note that while this property allows specification of the default + * implementation to use, it does not help with structural issues that + * may arise if type information is missing. This means that most often + * this is used with type-name -based resolution, to cover cases + * where new sub-types are added, but base type is not changed to + * reference new sub-types. + * + * @since 1.9 + */ + public Class<?> defaultImpl() default None.class; + + /* + /********************************************************** + /* Helper classes + /********************************************************** + */ + + /** + * This marker class that is only to be used with <code>defaultImpl</code> + * annotation property, to indicate that there is no default implementation + * specified. + * + * @since 1.9 + */ + public abstract static class None { } +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonTypeName.java b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeName.java new file mode 100644 index 0000000..d78d18a --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonTypeName.java @@ -0,0 +1,28 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + + +/** + * Annotation used for binding logical name that the annotated class + * has. Used with {@link JsonTypeInfo} (and specifically its + * {@link JsonTypeInfo#use} property) to establish relationship + * between type names and types. + * + * @since 1.5 + * + * @author tatu + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonTypeName { + /** + * Logical type name for annotated type. If missing (or defined as Empty String), + * defaults to using non-qualified class name as the type. + */ + public String value() default ""; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonUnwrapped.java b/src/main/java/com/fasterxml/jackson/annotation/JsonUnwrapped.java new file mode 100644 index 0000000..57e983a --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonUnwrapped.java @@ -0,0 +1,76 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Annotation used to indicate that a property should be serialized + * "unwrapped"; that is, if it would be serialized as JSON Object, its + * properties are instead included as properties of its containing + * Object. For example, consider case of POJO like: + * + *<pre> + * public class Parent { + * public int age; + * public Name name; + * } + * public class Name { + * public String first, last; + * } + *</pre> + * which would normally be serialized as follows (assuming @JsonUnwrapped + * had no effect): + *<pre> + * { + * "age" : 18, + * "name" : { + * "first" : "Joey", + * "last" : "Sixpack" + * } + * } + *</pre> + * can be changed to this: + *<pre> + * { + * "age" : 18, + * "first" : "Joey", + * "last" : "Sixpack" + * } + *</pre> + * by changing Parent class to: + *<pre> + * public class Parent { + * public int age; + * \@JsonUnwrapped + * public Name name; + * } + *</pre> + * Annotation can only be added to properties, and not classes, as it is contextual. + *<p> + * Also note that annotation only applies if + *<ul> + * <li>Value is serialized as JSON Object + * </li> + * <li>Serialization is done using <code>BeanSerializer</code>, not a custom serializer + * </li> + * <li>No type information is added; if type information needs to be added, structure can + * not be altered regardless of inclusion strategy; so annotation is basically ignored. + * </li> + * </ul> + * + * @since 1.9 + */ +@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonUnwrapped +{ + /** + * Property that is usually only used when overriding (masking) annotations, + * using mix-in annotations. Otherwise default value of 'true' is fine, and + * value need not be explicitly included. + */ + boolean enabled() default true; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonValue.java b/src/main/java/com/fasterxml/jackson/annotation/JsonValue.java new file mode 100644 index 0000000..9277082 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/JsonValue.java @@ -0,0 +1,46 @@ +package com.fasterxml.jackson.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marker annotation similar to + * {@link javax.xml.bind.annotation.XmlValue} + * that indicates that results of the annotated "getter" method + * (which means signature must be that of getters; non-void return + * type, no args) is to be used as the single value to serialize + * for the instance. Usually value will be of a simple scalar type + * (String or Number), but it can be any serializable type (Collection, + * Map or Bean). + *<p> + * At most one method of a Class can be annotated with this annotation; + * if more than one is found, an exception may be thrown. + * Also, if method signature is not compatible with Getters, an exception + * may be thrown. + * Whether exception is thrown or not is an implementation detail (due + * to filtering during introspection, some annotations may be skipped) + * and applications should not rely on specific behavior. + *<p> + * A typical use case is that of annotating <code>toString()</code> + * method so that returned String value is Object's Json serialization. + *<p> + * Boolean argument is only used so that sub-classes can "disable" + * annotation if necessary. + */ +@Target({ElementType.METHOD}) +@Retention(RetentionPolicy.RUNTIME) +@JacksonAnnotation +public @interface JsonValue +{ + /** + * Optional argument that defines whether this annotation is active + * or not. The only use for value 'false' if for overriding purposes. + * Overriding may be necessary when used + * with "mix-in annotations" (aka "annotation overrides"). + * For most cases, however, default value of "true" is just fine + * and should be omitted. + */ + boolean value() default true; +} diff --git a/src/main/java/com/fasterxml/jackson/annotation/package-info.java b/src/main/java/com/fasterxml/jackson/annotation/package-info.java new file mode 100644 index 0000000..7a921e6 --- /dev/null +++ b/src/main/java/com/fasterxml/jackson/annotation/package-info.java @@ -0,0 +1,16 @@ +/** + * Public core annotations, most of which are used to configure how + * Data Mapping/Binding works. Annotations in this package can only + * have dependencies to non-annotation classes in Core package; + * annotations that have dependencies to Mapper classes are included + * in Mapper module (under <code>org.codehaus.jackson.map.annotate</code>). + * Also contains parameter types (mostly enums) needed by annotations. + *<p> + * In future (version 2.0?), this package will probably be split off + * as a separate jar/module, to allow use of annotations without + * including core module. This would be useful for third party value + * classes that themselves do not depend on Jackson, but may want to + * be annotated to be automatically and conveniently serializable by + * Jackson. + */ +package com.fasterxml.jackson.annotation; -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/jackson-annotations.git _______________________________________________ pkg-java-commits mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-java-commits
