Backport JsonFormat changes from now-removed 3.0

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/annotation/JsonFormat.java

@@ -4,6 +4,8 @@
 import java.util.Locale;
 import java.util.TimeZone;
 
+import com.fasterxml.jackson.annotation.JsonFormat.Shape;
+
 /**
  * General-purpose annotation used for configuring details of how
  * values of properties are to be serialized and deserialized.
@@ -17,7 +19,7 @@
  * or String (such as ISO-8601 compatible time value) -- as well as configuring
  * exact details with {@link #pattern} property.
  *<p>
- * As of Jackson 2.18, known special handling includes:
+ * As of Jackson 2.19, known special handling includes:
  *<ul>
  * <li>{@link java.util.Date} or {@link java.util.Calendar}: Shape can  be {@link Shape#STRING} or {@link Shape#NUMBER};
  *    pattern may contain {@link java.text.SimpleDateFormat}-compatible pattern definition.
@@ -152,40 +154,20 @@
      */
     public enum Shape
     {
+        // // // Concrete physical shapes, scalars
         /**
-         * Marker enum value that indicates "whatever" choice, meaning that annotation
-         * does NOT specify shape to use.
-         * Note that this is different from {@link Shape#NATURAL}, which
-         * specifically instructs use of the "natural" shape for datatype.
-         */
-        ANY,
-
-        /**
-         * Marker enum value that indicates the "default" choice for given datatype;
-         * for example, JSON String for {@link java.lang.String}, or JSON Number
-         * for Java numbers.
-         * Note that this is different from {@link Shape#ANY} in that this is actual
-         * explicit choice that overrides possible default settings.
+         * Value that indicates that Binary type (native, if format supports it;
+         * encoding using Base64 if only textual types supported) should be used.
          *
-         * @since 2.8
-         */
-        NATURAL,
-
-        /**
-         * 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.
+         * @since 2.10
          */
-        ARRAY,
+        BINARY,
 
         /**
-         * Value that indicates that (JSON) Object type should be used.
+         * Value that indicates that (JSON) boolean type
+         * (true, false) should be used.
          */
-        OBJECT,
+        BOOLEAN,
 
         /**
          * Value that indicates that a numeric (JSON) type should be used
@@ -211,26 +193,71 @@ public enum Shape
         STRING,
 
         /**
-         * Value that indicates that (JSON) boolean type
-         * (true, false) should be used.
+         * Value that indicates shape should not be structural (that is, not
+         * {@link #ARRAY} or {@link #OBJECT}), but can be any other shape.
          */
-        BOOLEAN,
+        SCALAR,
+
+        // // // Concrete physical shapes, structured
 
         /**
-         * Value that indicates that Binary type (native, if format supports it;
-         * encoding using Base64 if only textual types supported) should be used.
+         * Value that indicates that (JSON) Array type should be used.
+         */
+        ARRAY,
+
+        /**
+         * Value that indicates that (JSON) Object type should be used.
+         */
+        OBJECT,
+
+        // // // Additional logical meta-types
+
+        /**
+         * Marker enum value that indicates "whatever" choice, meaning that annotation
+         * does NOT specify shape to use.
+         * Note that this is different from {@link Shape#NATURAL}, which
+         * specifically instructs use of the "natural" shape for datatype.
+         */
+        ANY,
+
+        /**
+         * Marker enum value that indicates the "default" choice for given datatype;
+         * for example, JSON String for {@link java.lang.String}, or JSON Number
+         * for Java numbers.
+         * Note that this is different from {@link Shape#ANY} in that this is actual
+         * explicit choice that overrides possible default settings.
          *
-         * @since 2.10
+         * @since 2.8
+         */
+        NATURAL,
+
+        /**
+         * Marker enum value that indicates not only shape of {@link #OBJECT} but further
+         * handling as POJO, where applicable. Mostly makes difference at Java Object level
+         * when distinguishing handling between {@link java.util.Map} and POJO types.
+         *
+         * @since 2.20
          */
-        BINARY
+        POJO,
+
         ;
 
         public boolean isNumeric() {
             return (this == NUMBER) || (this == NUMBER_INT) || (this == NUMBER_FLOAT);
         }
 
+        /** @since 2.20 */
+        public static boolean isNumeric(Shape shapeOrNull) {
+            return (shapeOrNull != null) && shapeOrNull.isNumeric();
+        }
+
         public boolean isStructured() {
-            return (this == OBJECT) || (this == ARRAY);
+            return (this == OBJECT) || (this == ARRAY) || (this == POJO);
+        }
+
+        /** @since 2.20 */
+        public static boolean isStructured(Shape shapeOrNull) {
+            return (shapeOrNull != null) && shapeOrNull.isStructured();
         }
     }
 
@@ -541,20 +568,6 @@ public Value(String p, Shape sh, Locale l, String tzStr, TimeZone tz, Features f
             _lenient = lenient;
         }
 
-        @Deprecated // since 2.9
-        public Value(String p, Shape sh, Locale l, String tzStr, TimeZone tz, Features f) {
-            this(p, sh, l, tzStr, tz, f, null);
-        }
-
-        @Deprecated // since 2.9
-        public Value(String p, Shape sh, String localeStr, String tzStr, Features f) {
-            this(p, sh, localeStr, tzStr, f, null);
-        }
-        @Deprecated // since 2.9
-        public Value(String p, Shape sh, Locale l, TimeZone tz, Features f) {
-            this(p, sh, l, tz, f, null);
-        }
-
         /**
          * @since 2.7
          */