[jackson-annotations] 09/207: Add @JsonInclude, for [JACKSON-752]

[Timo Aaltonen]

This is an automated email from the git hooks/post-receive script.

tjaalton pushed a commit to branch master
in repository jackson-annotations.

commit e05f96a93f1a1c433e34e46176715a7c8bef5d21
Author: Tatu Saloranta <tsaloranta at gmail.com>
Date:   Sat Jan 14 22:01:40 2012 -0800

    Add @JsonInclude, for [JACKSON-752]
---
 .../fasterxml/jackson/annotation/JsonInclude.java  | 95 ++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java b/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
new file mode 100644
index 0000000..d80b72b
--- /dev/null
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonInclude.java
@@ -0,0 +1,95 @@
+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 when value of the annotated property (when
+ * used for a field, method or constructor parameter), or all 
+ * properties of the annotated class, is to be serialized.
+ * Without annotation property values are always included, but by using
+ * this annotation one can specify simple exclusion rules to reduce
+ * amount of properties to write out.
+ * 
+ * @since 2.0
+ */
+ at Target({ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.PARAMETER})
+ at Retention(RetentionPolicy.RUNTIME)
+ at com.fasterxml.jackson.annotation.JacksonAnnotation
+public @interface JsonInclude
+{
+    /**
+     * Inclusion rule to use.
+     */
+    public Include value() default Include.ALWAYS;
+    
+    /*
+    /**********************************************************
+    /* Value enumerations needed
+    /**********************************************************
+     */
+
+    /**
+     * Enumeration used with {@link JsonSerialize#include} property
+     * to define which properties
+     * of Java Beans are to be included in serialization.
+     *<p>
+     * Note: Jackson 1.x had similarly named ("Inclusion") enumeration included
+     * in <code>JsonSerialize</code> annotation: it is not deprecated
+     * and this value used instead.
+     */
+    public enum Include
+    {
+        /**
+         * Value that indicates that property is to be always included,
+         * independent of value of the property.
+         */
+        ALWAYS,
+
+        /**
+         * Value that indicates that only properties with non-null
+         * values are to be included.
+         */
+        NON_NULL,
+
+        /**
+         * Value that indicates that only properties that have values
+         * that differ from default settings (meaning values they have
+         * when Bean is constructed with its no-arguments constructor)
+         * are to be included. Value is generally not useful with
+         * {@link java.util.Map}s, since they have no default values;
+         * and if used, works same as {@link #ALWAYS}.
+         */
+        NON_DEFAULT,
+
+        /**
+         * Value that indicates that only properties that have values
+         * that values that are null or what is considered empty are
+         * not to be included.
+         *<p>
+         * Default emptiness is defined for following type:
+         *<ul>
+         * <li>For {@link java.util.Collection}s and {@link java.util.Map}s,
+         *    method <code>isEmpty()</code> is called;
+         *   </li>
+         * <li>For Java arrays, empty arrays are ones with length of 0
+         *   </li>
+         * <li>For Java {@link java.lang.String}s, <code>length()</code> is called,
+         *   and return value of 0 indicates empty String (note that <code>String.isEmpty()</code>
+         *   was added in Java 1.6 and as such can not be used by Jackson
+         *   </li>
+         * <ul>
+         *  and for other types, non-null values are to be included.
+         *<p>
+         * Note that this default handling can be overridden by custom
+         * <code>JsonSerializer</code> implementation: if method <code>isEmpty()</code>
+         * is overridden, it will be called to see if non-null values are
+         * considered empty (null is always considered empty).
+         */
+        NON_EMPTY
+        ;
+    }
+
+}

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/jackson-annotations.git