Fixes #4584: add AnnotationIntrospector method for primary Creator di…

…scovery (#4615)

release-notes/VERSION-2.x

@@ -50,6 +50,8 @@ Project: jackson-databind
 #4570: Deprecate `ObjectMapper.canDeserialize()`/`ObjectMapper.canSerialize()`
 #4580: Add `MapperFeature.SORT_CREATOR_PROPERTIES_BY_DECLARATION_ORDER` to use
   Creator properties' declaration order for sorting
+#4584: Provide extension point for detecting "primary" Constructor for Kotlin
+  (and similar) data classes
 #4602: Possible wrong use of _arrayDelegateDeserializer in
   BeanDeserializerBase::deserializeFromObjectUsingNonDefault()
  (reported by Eduard G)

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

@@ -1397,6 +1397,39 @@ public JsonCreator.Mode findCreatorAnnotation(MapperConfig<?> config, Annotated
         return null;
     }
 
+    /**
+     * Method called to check if introspector is able to detect so-called Primary
+     * Creator: Creator to select for use when no explicit annotation is found
+     * (via {@link #findCreatorAnnotation}).
+     * This is the case for example for Java Record types which have so-called
+     * canonical constructor; but it is also true for various "Data" classes by frameworks
+     * like Lombok and JVM languages like Kotlin and Scala (case classes).
+     * If introspector can determine that one of given {@link PotentialCreator}s should
+     * be considered Primary, it should return it; if not, should return {@code null}.
+     *<p>
+     * NOTE: when returning chosen Creator, it may be necessary to mark its "mode"
+     * with {@link PotentialCreator#overrideMode} (especially for "delegating" creators).
+     *<p>
+     * NOTE: method is NOT called for Java Record types; selection of the canonical constructor
+     * as the Primary creator is handled directly by {@link POJOPropertiesCollector}
+     *
+     * @param config Configuration settings in effect (for deserialization)
+     * @param valueClass Class being instantiated and defines Creators passed
+     * @param declaredConstructors Constructors value class declares
+     * @param declaredFactories Factory methods value class declares
+     *
+     * @return The one Canonical Creator to use for {@code valueClass}, if it can be
+     *    determined; {@code null} if not.
+     *
+     * @since 2.18
+     */
+    public PotentialCreator findPrimaryCreator(MapperConfig<?> config,
+            AnnotatedClass valueClass,
+            List<PotentialCreator> declaredConstructors,
+            List<PotentialCreator> declaredFactories) {
+        return null;
+    }
+
     /**
      * Method for checking whether given annotated item (method, constructor)
      * has an annotation

src/main/java/com/fasterxml/jackson/databind/introspect/AnnotationIntrospectorPair.java

@@ -735,9 +735,23 @@ public JsonCreator.Mode findCreatorAnnotation(MapperConfig<?> config, Annotated
         return (mode == null) ? _secondary.findCreatorAnnotation(config, a) : mode;
     }
 
+    @Override
+    public PotentialCreator findPrimaryCreator(MapperConfig<?> config,
+            AnnotatedClass valueClass,
+            List<PotentialCreator> declaredConstructors,
+            List<PotentialCreator> declaredFactories) {
+        PotentialCreator primary = _primary.findPrimaryCreator(config,
+                valueClass, declaredConstructors, declaredFactories);
+        if (primary == null) {
+            primary = _secondary.findPrimaryCreator(config,
+                    valueClass, declaredConstructors, declaredFactories);
+        }
+        return primary;
+    }
+
     /*
     /**********************************************************************
-    /* Deserialization: other method annotations
+    /* Deserialization: other property annotations
     /**********************************************************************
      */
 

src/main/java/com/fasterxml/jackson/databind/introspect/POJOPropertiesCollector.java

@@ -648,22 +648,22 @@ protected void _addCreators(Map<String, POJOPropertyBuilder> props)
         List<PotentialCreator> constructors = _collectCreators(_classDef.getConstructors());
         List<PotentialCreator> factories = _collectCreators(_classDef.getFactoryMethods());
 
-        final PotentialCreator canonical;
-
-        // Find and mark "canonical" constructor for Records.
+        // Then find what is the Primary Constructor (if one exists for type):
+        // for Java Records and potentially other types too ("data classes"):
         // Needs to be done early to get implicit names populated
+        final PotentialCreator primary;
         if (_isRecordType) {
-            canonical = JDK14Util.findCanonicalRecordConstructor(_config, _classDef, constructors);
+            primary = JDK14Util.findCanonicalRecordConstructor(_config, _classDef, constructors);
         } else {
-            // !!! TODO: fetch Canonical for Kotlin, Scala, via AnnotationIntrospector?
-            canonical = null;
+            primary = _annotationIntrospector.findPrimaryCreator(_config, _classDef,
+                    constructors, factories);
         }
-
         // Next: remove creators marked as explicitly disabled
         _removeDisabledCreators(constructors);
         _removeDisabledCreators(factories);
+
         // And then remove non-annotated static methods that do not look like factories
-        _removeNonFactoryStaticMethods(factories);
+        _removeNonFactoryStaticMethods(factories, primary);
 
         // and use annotations to find explicitly chosen Creators
         if (_useAnnotations) { // can't have explicit ones without Annotation introspection
@@ -681,18 +681,18 @@ protected void _addCreators(Map<String, POJOPropertyBuilder> props)
             _addCreatorsWithAnnotatedNames(creators, constructors);
         }
 
-        // But if no annotation-based Creators found, find/use canonical Creator
-        // (JDK 17 Record/Scala/Kotlin)
-        if (!creators.hasPropertiesBased()) {
-            // for Records:
-            if (canonical != null) {
+        // But if no annotation-based Creators found, find/use Primary Creator
+        // detected earlier, if any
+        if (primary != null) {
+            if (!creators.hasPropertiesBased()) {
                 // ... but only process if still included as a candidate
-                if (constructors.remove(canonical)) {
+                if (constructors.remove(primary)
+                        || factories.remove(primary)) {
                     // But wait! Could be delegating
-                    if (_isDelegatingConstructor(canonical)) {
-                        creators.addExplicitDelegating(canonical);
+                    if (_isDelegatingConstructor(primary)) {
+                        creators.addExplicitDelegating(primary);
                     } else {
-                        creators.setPropertiesBased(_config, canonical, "canonical");
+                        creators.setPropertiesBased(_config, primary, "Primary");
                     }
                 }
             }
@@ -720,19 +720,29 @@ protected void _addCreators(Map<String, POJOPropertyBuilder> props)
 
         // And finally add logical properties for the One Properties-based
         // creator selected (if any):
-        PotentialCreator primary = creators.propertiesBased;
-        if (primary == null) {
+        PotentialCreator propsCtor = creators.propertiesBased;
+        if (propsCtor == null) {
             _creatorProperties = Collections.emptyList();
         } else {
             _creatorProperties = new ArrayList<>();
-            _addCreatorParams(props, primary, _creatorProperties);
+            _addCreatorParams(props, propsCtor, _creatorProperties);
         }
     }
 
     // Method to determine if given non-explictly-annotated constructor
     // looks like delegating one
     private boolean _isDelegatingConstructor(PotentialCreator ctor)
     {
+        // First things first: could be 
+        switch (ctor.creatorModeOrDefault()) {
+        case DELEGATING:
+            return true;
+        case DISABLED:
+        case PROPERTIES:
+            return false;
+        default: // case DEFAULT:
+        }
+
         // Only consider single-arg case, for now
         if (ctor.paramCount() == 1) {
             // Main thing: @JsonValue makes it delegating:
@@ -752,6 +762,7 @@ private List<PotentialCreator> _collectCreators(List<? extends AnnotatedWithPara
         for (AnnotatedWithParams ctor : ctors) {
             JsonCreator.Mode creatorMode = _useAnnotations
                     ? _annotationIntrospector.findCreatorAnnotation(_config, ctor) : null;
+            // 06-Jul-2024, tatu: Can't yet drop DISABLED ones; add all (for now)
             result.add(new PotentialCreator(ctor, creatorMode));
         }
         return (result == null) ? Collections.emptyList() : result;
@@ -779,14 +790,19 @@ private void _removeNonVisibleCreators(List<PotentialCreator> ctors)
         }
     }
 
-    private void _removeNonFactoryStaticMethods(List<PotentialCreator> ctors)
+    private void _removeNonFactoryStaticMethods(List<PotentialCreator> ctors,
+            PotentialCreator canonical)
     {
         final Class<?> rawType = _type.getRawClass();
         Iterator<PotentialCreator> it = ctors.iterator();
         while (it.hasNext()) {
             // explicit mode? Retain (for now)
             PotentialCreator ctor = it.next();
-            if (ctor.creatorMode() != null) {
+            if (ctor.isAnnotated()) {
+                continue;
+            }
+            // Do not trim canonical either
+            if (canonical == ctor) {
                 continue;
             }
             // Copied from `BasicBeanDescription.isFactoryMethod()`
@@ -820,7 +836,7 @@ private void _addExplicitlyAnnotatedCreators(PotentialCreators collector,
 
             // If no explicit annotation, skip for now (may be discovered
             // at a later point)
-            if (ctor.creatorMode() == null) {
+            if (!ctor.isAnnotated()) {
                 continue;
             }