Improve PolymorphicFallbackDeserializer

- Generalize test case
- add @SInCE and @beta annotation on custom deserializer (public)

Author: rpanackal

orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationClient.java

@@ -56,7 +56,7 @@ public class OrchestrationClient {
         new SimpleModule()
             .addDeserializer(
                 ChatMessagesInner.class,
-                new PolymorphicFallbackDeserializer<>(ChatMessagesInner.class))
+                PolymorphicFallbackDeserializer.fromJsonSubTypes(ChatMessagesInner.class))
             .setMixInAnnotation(ChatMessagesInner.class, JacksonMixins.NoneTypeInfoMixin.class);
     JACKSON.registerModule(module);
   }

orchestration/src/main/java/com/sap/ai/sdk/orchestration/PolymorphicFallbackDeserializer.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.JsonDeserializer;
 import com.fasterxml.jackson.databind.JsonMappingException;
+import com.google.common.annotations.Beta;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
@@ -18,43 +19,53 @@
  * explicitly. If deserialization fails for all candidates, a {@link JsonMappingException} is thrown
  * with suppressed exceptions.
  *
+ * @since 1.2.0
  * @param <T> The base type for deserialization.
  */
+@Beta
 public class PolymorphicFallbackDeserializer<T> extends JsonDeserializer<T> {
 
   @Nonnull private final List<Class<? extends T>> candidates;
-  Class<T> baseClass;
+  @Nonnull private final Class<T> baseClass;
+
+  private PolymorphicFallbackDeserializer(
+      @Nonnull final Class<T> baseClass, @Nonnull final List<Class<? extends T>> candidates) {
+    this.baseClass = baseClass;
+    this.candidates = candidates;
+  }
 
   /**
-   * Constructs the deserializer using the {@link JsonSubTypes} annotation.
+   * Constructs the deserializer using candidates inferred from the {@link JsonSubTypes} annotation.
    *
    * @param baseClass The base class or interface to be resolved.
    * @throws IllegalStateException If no subtypes are found.
    */
-  protected PolymorphicFallbackDeserializer(@Nonnull final Class<T> baseClass) {
-    this.baseClass = baseClass;
-
+  @Nonnull
+  protected static <T> PolymorphicFallbackDeserializer<T> fromJsonSubTypes(
+      @Nonnull final Class<T> baseClass) {
     final var subTypes = baseClass.getAnnotation(JsonSubTypes.class);
     if (subTypes == null || subTypes.value().length == 0) {
       throw new IllegalStateException("No subtypes found for " + baseClass.getName());
     }
 
-    candidates = new ArrayList<>();
+    final var candidates = new ArrayList<Class<? extends T>>();
     for (final var subType : subTypes.value()) {
       candidates.add((Class<? extends T>) subType.value());
     }
+
+    return new PolymorphicFallbackDeserializer<>(baseClass, candidates);
   }
 
   /**
-   * Constructs the deserializer with an explicit list of candidate types.
+   * Constructs the deserializer with an explicit given list of candidate types.
    *
    * @param baseClass The base class or interface to be resolved.
    * @param candidates A list of candidate classes to try deserialization.
    */
-  protected PolymorphicFallbackDeserializer(
+  @Nonnull
+  protected static <T> PolymorphicFallbackDeserializer<T> fromCandidates(
       @Nonnull final Class<T> baseClass, @Nonnull final List<Class<? extends T>> candidates) {
-    this.baseClass = baseClass;
-    this.candidates = candidates;
+    return new PolymorphicFallbackDeserializer<>(baseClass, candidates);
   }
 
   /**
@@ -74,19 +85,25 @@ public T deserialize(
       throws IOException {
 
     final var root = jsonParser.readValueAsTree();
-    final var throwable =
-        JsonMappingException.from(
-            jsonParser,
-            "PolymorphicFallbackDeserializer failed to deserialize " + this.baseClass.getName());
+    final var suppressed = new ArrayList<JsonMappingException>();
 
     for (final var candidate : candidates) {
       try {
         return jsonParser.getCodec().treeToValue(root, candidate);
       } catch (JsonMappingException e) {
-        throwable.addSuppressed(e);
+        suppressed.add(e);
       }
     }
 
-    throw throwable;
+    final var aggregateException =
+        JsonMappingException.from(
+            jsonParser,
+            "PolymorphicFallbackDeserializer failed to deserialize "
+                + this.baseClass.getName()
+                + ". Attempted candidates: "
+                + candidates.stream().map(Class::getName).toList());
+
+    suppressed.forEach(aggregateException::addSuppressed);
+    throw aggregateException;
   }
 }

orchestration/src/test/java/com/sap/ai/sdk/orchestration/OrchestrationUnitTest.java

@@ -753,10 +753,12 @@ void testOrchestrationChatResponseWithMultiChatMessage() {
     var module = new SimpleModule();
     module.setMixInAnnotation(LLMModuleResult.class, JacksonMixins.NoneTypeInfoMixin.class);
     module.addDeserializer(
-        LLMModuleResult.class, new PolymorphicFallbackDeserializer<>(LLMModuleResult.class));
+        LLMModuleResult.class,
+        PolymorphicFallbackDeserializer.fromJsonSubTypes(LLMModuleResult.class));
     module.setMixInAnnotation(ChatMessagesInner.class, JacksonMixins.NoneTypeInfoMixin.class);
     module.addDeserializer(
-        ChatMessagesInner.class, new PolymorphicFallbackDeserializer<>(ChatMessagesInner.class));
+        ChatMessagesInner.class,
+        PolymorphicFallbackDeserializer.fromJsonSubTypes(ChatMessagesInner.class));
 
     var orchestrationChatResponse =
         new OrchestrationChatResponse(

orchestration/src/test/java/com/sap/ai/sdk/orchestration/PolymorphicFallbackDeserializerTest.java

@@ -5,8 +5,6 @@
 import com.fasterxml.jackson.databind.JsonMappingException;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import com.fasterxml.jackson.databind.module.SimpleModule;
-import com.sap.ai.sdk.orchestration.model.ChatMessage;
-import com.sap.ai.sdk.orchestration.model.ChatMessagesInner;
 import java.util.List;
 import lombok.SneakyThrows;
 import org.junit.jupiter.api.Test;
@@ -17,48 +15,54 @@ class PolymorphicFallbackDeserializerTest {
   @Test
   void testValueTypeResolutionFailure() {
 
-    final String multiChatMessageJson =
+    interface AbstractParent {}
+
+    class KnownCandidate implements AbstractParent {
+      String content;
+    }
+
+    class UnknownCandidate implements AbstractParent {
+      List<String> content;
+    }
+
+    final String unknownCandidateJson =
         """
         {
-          "role": "user",
           "content": [
-            {
-              "type": "text",
-              "text": "What’s in this image?"
-            },
-            {
-              "type": "image_url",
-              "image_url": {
-                "url": "https://sample.page.org/an-image.jpg"
-              }
-            }
+            "Sentence one",
+            "Sentence two"
           ]
         }
         """;
 
     final var module =
         new SimpleModule()
             .addDeserializer(
-                ChatMessagesInner.class,
-                new PolymorphicFallbackDeserializer<>(
-                    ChatMessagesInner.class, List.of(ChatMessage.class)))
-            .setMixInAnnotation(ChatMessagesInner.class, JacksonMixins.NoneTypeInfoMixin.class);
+                AbstractParent.class,
+                PolymorphicFallbackDeserializer.fromCandidates(
+                    AbstractParent.class, List.of(KnownCandidate.class)));
 
     final var mapper = new JsonMapper().registerModule(module);
 
-    assertThatThrownBy(() -> mapper.readValue(multiChatMessageJson, ChatMessagesInner.class))
+    assertThatThrownBy(() -> mapper.readValue(unknownCandidateJson, AbstractParent.class))
         .isInstanceOf(JsonMappingException.class)
         .hasMessageContaining(
             "PolymorphicFallbackDeserializer failed to deserialize "
-                + ChatMessagesInner.class.getName());
+                + AbstractParent.class.getName()
+                + ". Attempted candidates: "
+                + List.of(KnownCandidate.class.getName()));
   }
 
   @Test
   void testMissingSubtypeAnnotation() {
-    interface NoSubTypesInterface {}
+    interface NoJsonSubTypeAnnotationInterface {}
 
-    assertThatThrownBy(() -> new PolymorphicFallbackDeserializer<>(NoSubTypesInterface.class))
+    assertThatThrownBy(
+            () ->
+                PolymorphicFallbackDeserializer.fromJsonSubTypes(
+                    NoJsonSubTypeAnnotationInterface.class))
         .isInstanceOf(IllegalStateException.class)
-        .hasMessageContaining("No subtypes found for " + NoSubTypesInterface.class.getName());
+        .hasMessageContaining(
+            "No subtypes found for " + NoJsonSubTypeAnnotationInterface.class.getName());
   }
 }