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;

/**
 * General-purpose annotation used for configuring details of how
 * values of properties are to be serialized.
 * Unlike most other Jackson annotations, annotation does not
 * have specific universal interpretation: instead, effect depends on datatype
 * of property being annotated (or more specifically, deserializer
 * and serializer being used).
 *<p>
 * Common uses include choosing between alternate representations -- for example,
 * whether {@link java.util.Date} is to be serialized as number (Java timestamp)
 * or String (such as ISO-8601 compatible time value) -- as well as configuring
 * exact details with {@link #pattern} property.
 * 
 * @since 2.0
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonFormat
{

    /**
     * Datatype-specific additional piece of configuration that may be used
     * to further refine formatting aspects. This may, for example, determine
     * low-level format String used for {@link java.util.Date} serialization;
     * however, exact use is determined by specific <code>JsonSerializer</code>
     */
    public String pattern() default "";

    public Shape shape() default Shape.ANY;
    
    /*
    /**********************************************************
    /* Value enumeration(s) needed
    /**********************************************************
     */

    /**
     * Value enumeration used for indicating preferred Shape; translates
     * loosely to JSON types, with some extra values to indicate less precise
     * choices (i.e. allowing one of multiple actual shapes)
     */
    public enum Shape
    {
        /**
         * Marker enum value that indicates "default" (or "whatever") choice; needed
         * since Annotations can not have null values for enums.
         */
        ANY,

        /**
         * Value that indicates shape should not be structural (that is, not
         * {@link #ARRAY} or {@link #OBJECT}, but can be any other shape.
         */
        SCALAR,

        /**
         * Value that indicates that (JSON) Array type should be used.
         */
        ARRAY,
        
        /**
         * Value that indicates that (JSON) Object type should be used.
         */
        OBJECT,

        /**
         * Value that indicates that a numeric (JSON) type should be used
         * (but does not specify whether integer or floating-point representation
         * should be used)
         */
        NUMBER,

        /**
         * Value that indicates that floating-point numeric type should be used
         */
        NUMBER_FLOAT,

        /**
         * Value that indicates that integer number type should be used
         * (and not {@link #NUMBER_FLOAT}).
         */
        NUMBER_INT,

        /**
         * Value that indicates that (JSON) String type should be used.
         */
        STRING,
        
        /**
         * Value that indicates that (JSON) boolean type
         * (true, false) should be used.
         */
        BOOLEAN
        ;
    }
}

@@ -855,12 +855,281 @@
 ty.%0A
+ *%3Cp%3E%0A * As of Jackson 2.0, known special handling include:%0A *%3Cul%3E%0A * %3Cli%3E%7B@link java.util.Date%7D: Shape can  be %7B@link Shape#STRING%7D or %7B@link Shape#NUMBER%7D;%0A *    pattern may contain %7B@link java.text.SimpleDateFormat%7D-compatible pattern definition.%0A *   %3C/li%3E%0A *%3C/ul%3E%0A
  * %0A
-
  * @
@@ -1329,17 +1329,16 @@
 ormat%0A%7B%0A
-%0A
     /**%0A
@@ -1845,23 +1845,33 @@
 ation(s)
- needed
+, value class(es)
 %0A    /**
@@ -3575,16 +3575,16 @@
 BOOLEAN%0A
-
         
@@ -3584,16 +3584,740 @@
        ;
+%0A%0A        public boolean isNumeric() %7B%0A            return (this == NUMBER) %7C%7C (this == NUMBER_INT) %7C%7C (this == NUMBER_FLOAT);%0A        %7D%0A%0A        public boolean isStructured() %7B%0A            return (this == OBJECT) %7C%7C (this == ARRAY);%0A        %7D%0A    %7D%0A%0A    /**%0A     * Helper class used to contain information from a single %7B@link JsonFormat%7D%0A     * annotation.%0A     */%0A    public static class Value%0A    %7B%0A        public final String pattern;%0A        public final Shape shape;%0A        %0A        public Value(JsonFormat annotationInstance) %7B%0A            this(annotationInstance.pattern(), annotationInstance.shape());%0A        %7D%0A%0A        public Value(String p, Shape sh) %7B%0A            pattern = p;%0A            shape = sh;%0A        %7D
 %0A    %7D%0A%7D

Add @JsonFormat details