[jackson-annotations] 02/207: First seemingly working version
Timo Aaltonen
tjaalton at moszumanska.debian.org
Sat Sep 6 13:55:33 UTC 2014
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 <tsaloranta at gmail.com>
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.
+ */
+ at Target({ElementType.ANNOTATION_TYPE})
+ at 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
+ */
+ at Target(ElementType.METHOD)
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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).
+ */
+ at Target(ElementType.METHOD)
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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).
+ */
+ at Target(ElementType.TYPE)
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.FIELD, ElementType.METHOD})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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.
+ */
+ at Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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)
+ */
+ at Target(ElementType.METHOD)
+ at Retention(RetentionPolicy.RUNTIME)
+ at JacksonAnnotation
+ at 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}
+ */
+ at Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.TYPE})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.TYPE})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.FIELD, ElementType.METHOD})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.TYPE})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target( { ElementType.METHOD, ElementType.FIELD })
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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.
+ */
+ at Target(ElementType.METHOD)
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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)
+ */
+ at Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.TYPE})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
+ */
+ at Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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.
+ */
+ at Target({ElementType.METHOD})
+ at Retention(RetentionPolicy.RUNTIME)
+ at 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
More information about the pkg-java-commits
mailing list