Implemented #438

Author: cowtowncoder

release-notes/VERSION

@@ -28,6 +28,7 @@ Version: 2.4.0 (xx-xxx-2014)
  (contributed by Francis G)
 #435: Performance bottleneck in TypeFactory._fromClass
  (reported by sdonovanuk@github)
+#438: Add support for accessing `@JsonProperty(index=N)` annotations
 
 ------------------------------------------------------------------------
 === History: ===

src/main/java/com/fasterxml/jackson/databind/AnnotationIntrospector.java

@@ -231,9 +231,7 @@ public String[] findPropertiesToIgnore(Annotated ac) {
     /**
      * Method for checking whether an annotation indicates that all unknown properties
      */
-    public Boolean findIgnoreUnknownProperties(AnnotatedClass ac) {
-        return null;
-    }
+    public Boolean findIgnoreUnknownProperties(AnnotatedClass ac) { return null; }
 
     /**
      * Method for checking whether properties that have specified type
@@ -246,17 +244,13 @@ public Boolean findIgnoreUnknownProperties(AnnotatedClass ac) {
      *   Boolean.FALSE if they are not to be ignored, null for default
      *   handling (which is 'do not ignore')
      */
-    public Boolean isIgnorableType(AnnotatedClass ac) {
-        return null;
-    }
+    public Boolean isIgnorableType(AnnotatedClass ac) { return null; }
 
     /**
      * @deprecated Since 2.3: use the one that takes generic {@link Annotated}
      */
     @Deprecated
-    public Object findFilterId(AnnotatedClass ac) {
-        return findFilterId((Annotated) ac);
-    }
+    public Object findFilterId(AnnotatedClass ac) { return findFilterId((Annotated) ac); }
 
     /**
      * Method for finding if annotated class has associated filter; and if so,
@@ -265,9 +259,7 @@ public Object findFilterId(AnnotatedClass ac) {
      * @return Id of the filter to use for filtering properties of annotated
      *    class, if any; or null if none found.
      */
-    public Object findFilterId(Annotated ann) {
-        return null;
-    }
+    public Object findFilterId(Annotated ann) { return null; }
 
     /**
      * Method for finding {@link PropertyNamingStrategy} for given
@@ -280,9 +272,7 @@ public Object findFilterId(Annotated ann) {
      * 
      * @since 2.1
      */
-    public Object findNamingStrategy(AnnotatedClass ac) {
-        return null;
-    }    
+    public Object findNamingStrategy(AnnotatedClass ac) { return null; }
 
     /*
     /**********************************************************
@@ -297,8 +287,7 @@ public Object findNamingStrategy(AnnotatedClass ac) {
      * (if no annotations are found), or build and return a derived instance (using
      * checker's build methods).
      */
-    public VisibilityChecker<?> findAutoDetectVisibility(AnnotatedClass ac,
-            VisibilityChecker<?> checker) {
+    public VisibilityChecker<?> findAutoDetectVisibility(AnnotatedClass ac, VisibilityChecker<?> checker) {
         return checker;
     }
 
@@ -378,18 +367,14 @@ public TypeResolverBuilder<?> findPropertyContentTypeResolver(MapperConfig<?> co
      * 
      * @param a Annotated entity (class, field/method) to check for annotations
      */
-    public List<NamedType> findSubtypes(Annotated a) {
-        return null;
-    }
+    public List<NamedType> findSubtypes(Annotated a) { return null; }
 
     /**
      * Method for checking if specified type has explicit name.
      * 
      * @param ac Class to check for type name annotations
      */
-    public String findTypeName(AnnotatedClass ac) {
-        return null;
-    }
+    public String findTypeName(AnnotatedClass ac) { return null; }
 
     /*
     /**********************************************************
@@ -401,9 +386,7 @@ public String findTypeName(AnnotatedClass ac) {
      * Method for checking if given member indicates that it is part
      * of a reference (parent/child).
      */
-    public ReferenceProperty findReferenceType(AnnotatedMember member) {
-        return null;
-    }
+    public ReferenceProperty findReferenceType(AnnotatedMember member) { return null; }
 
     /**
      * Method called to check whether given property is marked to be "unwrapped"
@@ -413,9 +396,7 @@ public ReferenceProperty findReferenceType(AnnotatedMember member) {
      * should  be done, or null if not -- note that transformation may simply
      * be identity transformation (no changes).
      */
-    public NameTransformer findUnwrappingNameTransformer(AnnotatedMember member) {
-        return null;
-    }
+    public NameTransformer findUnwrappingNameTransformer(AnnotatedMember member) { return null; }
 
     /**
      * Method called to check whether given property is marked to
@@ -424,9 +405,7 @@ public NameTransformer findUnwrappingNameTransformer(AnnotatedMember member) {
      * annotations from multiple accessors (getters, setters, fields,
      * constructor parameters).
      */
-    public boolean hasIgnoreMarker(AnnotatedMember m) {
-        return false;
-    }
+    public boolean hasIgnoreMarker(AnnotatedMember m) { return false; }
 
     /**
      * Method called to find out whether given member expectes a value
@@ -441,9 +420,7 @@ public boolean hasIgnoreMarker(AnnotatedMember m) {
      * @return Identifier of value to inject, if any; null if no injection
      *   indicator is found
      */
-    public Object findInjectableValueId(AnnotatedMember m) {
-        return null;
-    }
+    public Object findInjectableValueId(AnnotatedMember m) { return null; }
 
     /**
      * Method that can be called to check whether this member has
@@ -452,9 +429,7 @@ public Object findInjectableValueId(AnnotatedMember m) {
      * 
      * @since 2.0
      */
-    public Boolean hasRequiredMarker(AnnotatedMember m) {
-        return null;
-    }
+    public Boolean hasRequiredMarker(AnnotatedMember m) { return null; }
 
     /**
      * Method for checking if annotated property (represented by a field or
@@ -469,9 +444,7 @@ public Boolean hasRequiredMarker(AnnotatedMember m) {
      * @return Array of views (represented by classes) that the property is included in;
      *    if null, always included (same as returning array containing <code>Object.class</code>)
      */
-    public Class<?>[] findViews(Annotated a) {
-        return null;
-    }
+    public Class<?>[] findViews(Annotated a) { return null; }
 
     /**
      * Method for finding format annotations for property or class.
@@ -481,21 +454,14 @@ public Class<?>[] findViews(Annotated a) {
      * 
      * @since 2.1
      */
-    public JsonFormat.Value findFormat(Annotated memberOrClass) {
-        return null;
-    }
+    public JsonFormat.Value findFormat(Annotated memberOrClass) { return null; }
 
     /**
      * Method for checking whether given accessor claims to represent
      * type id: if so, its value may be used as an override,
      * instead of generated type id.
-     * 
-     * @since 2.0
      */
-    public Boolean isTypeId(AnnotatedMember member) {
-        return null;
-    }
-
+    public Boolean isTypeId(AnnotatedMember member) { return null; }
 
     /**
      * Method used to check if specified property has annotation that indicates
@@ -508,9 +474,7 @@ public Boolean isTypeId(AnnotatedMember member) {
      * 
      * @since 2.1
      */
-    public PropertyName findWrapperName(Annotated ann) {
-        return null;
-    }
+    public PropertyName findWrapperName(Annotated ann) { return null; }
 
     /**
      * Method used to check whether specified property member (accessor
@@ -522,10 +486,21 @@ public PropertyName findWrapperName(Annotated ann) {
      * 
      * @since 2.3
      */
-    public String findPropertyDescription(Annotated ann) {
-        return null;
-    }
-    
+    public String findPropertyDescription(Annotated ann) { return null; }
+
+    /**
+     * Method used to check whether specified property member (accessor
+     * or mutator) defines numeric index, and if so, what is the index value.
+     * Possible use cases for index values included use by underlying data format
+     * (some binary formats mandate use of index instead of name) and ordering
+     * of properties (for documentation, or during serialization).
+     * 
+     * @since 2.4
+     * 
+     * @return Explicitly specified index for the property, if any
+     */
+    public Integer findPropertyIndex(Annotated ann) { return null; }
+
     /*
     /**********************************************************
     /* Serialization: general annotations

src/main/java/com/fasterxml/jackson/databind/BeanDescription.java

@@ -39,8 +39,7 @@ public abstract class BeanDescription
     /**********************************************************
      */
 
-    protected BeanDescription(JavaType type)
-    {
+    protected BeanDescription(JavaType type) {
         _type = type;
     }
 

src/main/java/com/fasterxml/jackson/databind/BeanProperty.java

@@ -60,6 +60,8 @@ public interface BeanProperty extends Named
      * Accessor for additional optional information about property.
      * 
      * @since 2.3
+     * 
+     * @return Metadata about property; never null.
      */
     public PropertyMetadata getMetadata();
 

src/main/java/com/fasterxml/jackson/databind/PropertyMetadata.java

@@ -4,7 +4,7 @@
  * Simple container class used for storing "additional" metadata about
  * properties. Carved out to reduce number of distinct properties that
  * actual property implementations and placeholders need to store;
- * since this instances are immutable, they can be freely shared.
+ * since instances are immutable, they can be freely shared.
  * 
  * @since 2.3
  */
@@ -13,11 +13,11 @@ public class PropertyMetadata
 {
     private static final long serialVersionUID = -1;
 
-    public final static PropertyMetadata STD_REQUIRED = new PropertyMetadata(Boolean.TRUE, null);
+    public final static PropertyMetadata STD_REQUIRED = new PropertyMetadata(Boolean.TRUE, null, null);
 
-    public final static PropertyMetadata STD_OPTIONAL = new PropertyMetadata(Boolean.FALSE, null);
+    public final static PropertyMetadata STD_OPTIONAL = new PropertyMetadata(Boolean.FALSE, null, null);
 
-    public final static PropertyMetadata STD_REQUIRED_OR_OPTIONAL = new PropertyMetadata(null, null);
+    public final static PropertyMetadata STD_REQUIRED_OR_OPTIONAL = new PropertyMetadata(null, null, null);
 
     /**
      * Three states: required, not required and unknown; unknown represented
@@ -30,22 +30,44 @@ public class PropertyMetadata
      */
     protected final String _description;
 
+    /**
+     * Optional index of the property within containing Object.
+     * 
+     * @since 2.4
+     */
+    protected final Integer _index;
+    
     /*
     /**********************************************************
     /* Construction, configuration
     /**********************************************************
      */
 
-    protected PropertyMetadata(Boolean req, String desc)
+    @Deprecated // since 2.4
+    protected PropertyMetadata(Boolean req, String desc) { this(req, desc, null); }
+
+    protected PropertyMetadata(Boolean req, String desc, Integer index)
     {
         _required = req;
         _description = desc;
+        _index = index;
     }
 
+    /**
+     * @since 2.4 Use variant that takes three arguments.
+     */
+    @Deprecated
     public static PropertyMetadata construct(boolean req, String desc) {
+    	return construct(req, desc, null);
+    }
+    
+    public static PropertyMetadata construct(boolean req, String desc, Integer index) {
         PropertyMetadata md = req ? STD_REQUIRED : STD_OPTIONAL;
         if (desc != null) {
-            return md.withDescription(desc);
+            md = md.withDescription(desc);
+        }
+        if (index != null) {
+        	md = md.withIndex(index);
         }
         return md;
     }
@@ -56,7 +78,7 @@ public static PropertyMetadata construct(boolean req, String desc) {
      */
     protected Object readResolve()
     {
-        if (_description == null) {
+        if (_description == null && _index == null) {
             if (_required == null) {
                 return STD_REQUIRED_OR_OPTIONAL;
             }
@@ -66,9 +88,13 @@ protected Object readResolve()
     }
 
     public PropertyMetadata withDescription(String desc) {
-        return new PropertyMetadata(_required, desc);
+        return new PropertyMetadata(_required, desc, _index);
     }
 
+    public PropertyMetadata withIndex(Integer index) {
+        return new PropertyMetadata(_required, _description, index);
+    }
+    
     public PropertyMetadata withRequired(Boolean b) {
         if (b == null) {
             if (_required == null) {
@@ -79,7 +105,7 @@ public PropertyMetadata withRequired(Boolean b) {
                 return this;
             }
         }
-        return new PropertyMetadata(b, _description);
+        return new PropertyMetadata(b, _description, _index);
     }
 
     /*
@@ -93,4 +119,14 @@ public PropertyMetadata withRequired(Boolean b) {
     public boolean isRequired() { return (_required != null) && _required.booleanValue(); }
 
     public Boolean getRequired() { return _required; }
+
+    /**
+     * @since 2.4
+     */
+    public Integer getIndex() { return _index; }
+
+    /**
+     * @since 2.4
+     */
+    public boolean hasIndex() { return _index != null; }
 }

src/main/java/com/fasterxml/jackson/databind/deser/BasicDeserializerFactory.java

@@ -673,7 +673,8 @@ protected CreatorProperty constructCreatorProperty(DeserializationContext ctxt,
             Boolean b = (intr == null) ? null : intr.hasRequiredMarker(param);
             boolean req = (b != null && b.booleanValue());
             String desc = (intr == null) ? null : intr.findPropertyDescription(param);
-            metadata = PropertyMetadata.construct(req, desc);
+            Integer idx = (intr == null) ? null : intr.findPropertyIndex(param);
+            metadata = PropertyMetadata.construct(req, desc, idx);
         }
 
         JavaType t0 = config.getTypeFactory().constructType(param.getParameterType(), beanDesc.bindingsForBeanType());