[java][jersey2] Add support for discriminator, fix nullable typo and nullable deserialization (#6495)

* Mustache template should use invokerPackage tag to generate import

* fix typo, fix script issue, add log statement for troubleshooting

* Add java jersey2 samples with OpenAPI doc that has HTTP signature security scheme

* Add sample for Java jersey2 and HTTP signature scheme

* Add unit test for oneOf schema deserialization

* Add unit test for oneOf schema deserialization

* Add log statements

* Add profile for jersey2

* Temporarily disable unit test

* Temporarily disable unit test

* support for discriminator in jersey2

* fix typo in pom.xml

* disable unit test because jersey2 deserialization is broken

* disable unit test because jersey2 deserialization is broken

* fix duplicate jersey2 samples

* fix duplicate jersey2 samples

* Add code comments

* fix duplicate artifact id

* fix duplicate jersey2 samples

* run samples scripts

* resolve merge conflicts

* Add unit tests

* fix unit tests

* continue implementation of discriminator lookup

* throw deserialization exception when value is null and schema does not allow null value

* continue implementation of compose schema

* continue implementation of compose schema

* continue implementation of compose schema

* Add more unit tests

* Add unit tests for anyOf

* Add unit tests

Co-authored-by: Vikrant Balyan (vvb) <[email protected]>

Author: sebastien-rosset

CI/samples.ci/client/petstore/java/test-manual/jersey2-java8/JSONComposedSchemaTest.java

@@ -30,29 +30,29 @@ public abstract class AbstractOpenApiSchema {
         this.isNullable = isNullable;
     }
 
-    /***
-     * Get the list of schemas allowed to be stored in this object
+    /**
+     * Get the list of oneOf/anyOf composed schemas allowed to be stored in this object
      *
      * @return an instance of the actual schema/object
      */
     public abstract Map<String, GenericType> getSchemas();
 
-    /***
+    /**
      * Get the actual instance
      *
      * @return an instance of the actual schema/object
      */
     @JsonValue
     public Object getActualInstance() {return instance;}
 
-    /***
+    /**
      * Set the actual instance
      *
      * @param instance the actual instance of the schema/object
      */
     public void setActualInstance(Object instance) {this.instance = instance;}
 
-    /***
+    /**
      * Get the schema type (e.g. anyOf, oneOf)
      *
      * @return the schema type
@@ -101,7 +101,7 @@ public abstract class AbstractOpenApiSchema {
         return Objects.hash(instance, isNullable, schemaType);
     }
 
-    /***
+    /**
      * Is nullalble
      *
      * @return true if it's nullable

modules/openapi-generator/src/main/resources/Java/libraries/jersey2/AbstractOpenApiSchema.mustache

@@ -15,9 +15,16 @@ import com.fasterxml.jackson.datatype.joda.JodaModule;
 {{#threetenbp}}
 import com.fasterxml.jackson.datatype.threetenbp.ThreeTenModule;
 {{/threetenbp}}
+{{#models.0}}
+import {{modelPackage}}.*;
+{{/models.0}}
 
 import java.text.DateFormat;
-
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import javax.ws.rs.core.GenericType;
 import javax.ws.rs.ext.ContextResolver;
 
 {{>generatedAnnotation}}
@@ -69,4 +76,180 @@ public class JSON implements ContextResolver<ObjectMapper> {
    * @return object mapper
    */
   public ObjectMapper getMapper() { return mapper; }
+
+  /**
+   * Returns the target model class that should be used to deserialize the input data.
+   * The discriminator mappings are used to determine the target model class.
+   *
+   * @param node The input data.
+   * @param modelClass The class that contains the discriminator mappings.
+   */
+  public static Class getClassForElement(JsonNode node, Class modelClass) {
+    ClassDiscriminatorMapping cdm = modelDiscriminators.get(modelClass);
+    if (cdm != null) {
+      return cdm.getClassForElement(node, new HashSet<Class>());
+    }
+    return null;
+  }
+
+  /**
+   * Helper class to register the discriminator mappings.
+   */
+  private static class ClassDiscriminatorMapping {
+    // The model class name.
+    Class modelClass;
+    // The name of the discriminator property.
+    String discriminatorName;
+    // The discriminator mappings for a model class.
+    Map<String, Class> discriminatorMappings;
+
+    // Constructs a new class discriminator.
+    ClassDiscriminatorMapping(Class cls, String name) {
+      modelClass = cls;
+      discriminatorName = name;
+      discriminatorMappings = new HashMap<String, Class>();
+    }
+
+    // Register a discriminator mapping for the specified model class.
+    void registerMapping(String mapping, Class cls) {
+      discriminatorMappings.put(mapping, cls);
+    }
+
+    // Return the name of the discriminator property for this model class.
+    String getDiscriminatorPropertyName() {
+      return discriminatorName;
+    }
+
+    // Return the discriminator value or null if the discriminator is not
+    // present in the payload.
+    String getDiscriminatorValue(JsonNode node) {
+      // Determine the value of the discriminator property in the input data.
+      if (discriminatorName != null) {
+        // Get the value of the discriminator property, if present in the input payload.
+        node = node.get(discriminatorName);
+        if (node != null && node.isValueNode()) {
+          String discrValue = node.asText();
+          if (discrValue != null) {
+            return discrValue;
+          }
+        }
+      }
+      return null;      
+    }
+
+    /**
+     * Returns the target model class that should be used to deserialize the input data.
+     * This function can be invoked for anyOf/oneOf composed models with discriminator mappings.
+     * The discriminator mappings are used to determine the target model class.
+     *
+     * @param node The input data.
+     * @param visitedClasses The set of classes that have already been visited.
+     */
+    Class getClassForElement(JsonNode node, Set<Class> visitedClasses) {
+      if (visitedClasses.contains(modelClass)) {
+        // Class has already been visited.
+        return null;
+      }
+      // Determine the value of the discriminator property in the input data.
+      String discrValue = getDiscriminatorValue(node);
+      if (discrValue == null) {
+        return null;
+      }
+      Class cls = discriminatorMappings.get(discrValue);
+      // It may not be sufficient to return this cls directly because that target class
+      // may itself be a composed schema, possibly with its own discriminator.
+      visitedClasses.add(modelClass);
+      for (Class childClass : discriminatorMappings.values()) {
+        ClassDiscriminatorMapping childCdm = modelDiscriminators.get(childClass);
+        if (childCdm == null) {
+          continue;
+        }
+        if (!discriminatorName.equals(childCdm.discriminatorName)) {
+          discrValue = getDiscriminatorValue(node);
+          if (discrValue == null) {
+            continue;
+          }
+        }
+        if (childCdm != null) {
+          // Recursively traverse the discriminator mappings.
+          Class childDiscr = childCdm.getClassForElement(node, visitedClasses);
+          if (childDiscr != null) {
+            return childDiscr;
+          }
+        }
+      }
+      return cls;
+    }
+  }
+
+  /**
+   * Returns true if inst is an instance of modelClass in the OpenAPI model hierarchy.
+   *
+   * The Java class hierarchy is not implemented the same way as the OpenAPI model hierarchy,
+   * so it's not possible to use the instanceof keyword.
+   *
+   * @param modelClass A OpenAPI model class.
+   * @param inst The instance object.
+   */
+  public static boolean isInstanceOf(Class modelClass, Object inst, Set<Class> visitedClasses) {
+    if (modelClass.isInstance(inst)) {
+      // This handles the 'allOf' use case with single parent inheritance.
+      return true;
+    }
+    if (visitedClasses.contains(modelClass)) {
+      // This is to prevent infinite recursion when the composed schemas have
+      // a circular dependency.
+      return false;
+    }
+    visitedClasses.add(modelClass);
+    
+    // Traverse the oneOf/anyOf composed schemas.
+    Map<String, GenericType> descendants = modelDescendants.get(modelClass);
+    if (descendants != null) {
+      for (GenericType childType : descendants.values()) {
+        if (isInstanceOf(childType.getRawType(), inst, visitedClasses)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  private static Map<Class, ClassDiscriminatorMapping> modelDiscriminators = new HashMap<Class, ClassDiscriminatorMapping>();
+
+  /**
+   * Register the discriminators for all composed models.
+   */
+  private static void registerDiscriminators() {
+    {{#models}}
+    {{#model}}
+    {{#discriminator}}
+    {
+      // Initialize the discriminator mappings for '{{classname}}'.
+      ClassDiscriminatorMapping m = new ClassDiscriminatorMapping({{classname}}.class, "{{propertyBaseName}}");
+      {{#mappedModels}}
+      m.registerMapping("{{mappingName}}", {{modelName}}.class);
+      {{/mappedModels}}
+      m.registerMapping("{{name}}", {{classname}}.class);
+      modelDiscriminators.put({{classname}}.class, m);
+    }
+    {{/discriminator}}
+    {{/model}}
+    {{/models}}
+  }
+
+  private static Map<Class, Map<String, GenericType>> modelDescendants = new HashMap<Class, Map<String, GenericType>>();
+
+  /**
+   * Register the oneOf/anyOf descendants.
+   * TODO: this should not be a public method.
+   */
+  public static void registerDescendants(Class modelClass, Map<String, GenericType> descendants) {
+    modelDescendants.put(modelClass, descendants);
+  }
+
+  static {
+    registerDiscriminators();
+  }
+
 }

modules/openapi-generator/src/main/resources/Java/libraries/jersey2/JSON.mustache

@@ -4,12 +4,16 @@ import java.io.IOException;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Map;
+import {{invokerPackage}}.JSON;
 
 import com.fasterxml.jackson.core.JsonParser;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonMappingException;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
@@ -33,6 +37,18 @@ public class {{classname}} extends AbstractOpenApiSchema{{#vendorExtensions.x-im
             JsonNode tree = jp.readValueAsTree();
 
             Object deserialized = null;
+            {{#discriminator}}
+            Class cls = JSON.getClassForElement(tree, {{classname}}.class);
+            if (cls != null) {
+                // When the OAS schema includes a discriminator, use the discriminator value to
+                // discriminate the anyOf schemas.
+                // Get the discriminator mapping value to get the class.
+                deserialized = tree.traverse(jp.getCodec()).readValueAs(cls);
+                {{classname}} ret = new {{classname}}();
+                ret.setActualInstance(deserialized);
+                return ret;
+            }
+            {{/discriminator}}
             {{#anyOf}}
             // deserialzie {{{.}}}
             try {
@@ -48,6 +64,19 @@ public class {{classname}} extends AbstractOpenApiSchema{{#vendorExtensions.x-im
             {{/anyOf}}
             throw new IOException(String.format("Failed deserialization for {{classname}}: no match found"));
         }
+
+        /**
+         * Handle deserialization of the 'null' value.
+         */
+        @Override
+        public {{classname}} getNullValue(DeserializationContext ctxt) throws JsonMappingException {
+        {{#isNullable}}
+            return null;
+        {{/isNullable}}
+        {{^isNullable}}
+            throw new JsonMappingException("{{classname}} cannot be null");
+        {{/isNullable}}
+        }
     }
 
     // store a list of schema names defined in anyOf
@@ -69,6 +98,7 @@ public class {{classname}} extends AbstractOpenApiSchema{{#vendorExtensions.x-im
         schemas.put("{{{.}}}", new GenericType<{{{.}}}>() {
         });
         {{/anyOf}}
+        JSON.registerDescendants({{classname}}.class, Collections.unmodifiableMap(schemas));
     }
 
     @Override
@@ -78,15 +108,15 @@ public class {{classname}} extends AbstractOpenApiSchema{{#vendorExtensions.x-im
 
     @Override
     public void setActualInstance(Object instance) {
-        {{#isNulalble}}
+        {{#isNullable}}
         if (instance == null) {
            super.setActualInstance(instance);
            return;
         }
 
-        {{/isNulalble}}
+        {{/isNullable}}
         {{#anyOf}}
-        if (instance instanceof {{{.}}}) {
+        if (JSON.isInstanceOf({{{.}}}.class, instance, new HashSet<Class>())) {
             super.setActualInstance(instance);
             return;
         }