fix: support serialization of models w/lists of discriminated subclasses

Fixes arf/planning-sdk-squad#2011

We initially did not implement the "write()" method within the
DiscriminatorBasedTypeAdapterFactory because we should never
encounter an actual instance of a discriminated base class
(they are implemented as abstract base classes).

However, in some scenarios Gson will use a type adapter
that reflects the DECLARED type rather than the actual RUNTIME type
associated with an object.  One such scenario is when a class
contains a field which is defined as a List of some type X, where
X is a discriminated base class (oneOf parent).

For this reason, it's possible that the write() method is
called.  This commit implements the write() method so that it
simply delegates to the TypeAdapter associated with the
object's RUNTIME type.

Author: padamstx

src/main/java/com/ibm/cloud/sdk/core/util/DiscriminatorBasedTypeAdapterFactory.java

@@ -177,15 +177,39 @@ public static class Adapter<T> extends TypeAdapter<T> {
     }
 
     /**
-     * We don't actually need to support the serialization of a class that contains the discriminator metadata
-     * because we should encounter only instances of its subclasses, as opposed to instances of the base class
-     * itself.
+     * We wouldn't normally expect Gson to call our write() method because we should never actually have
+     * instances of a "oneOf" base class (they are implemented as abstract base classes).
+     * However, in some serialization scenarios, Gson will use the DECLARED type (rather than an object's
+     * actual RUNTIME type) when trying to find a suitable TypeAdapter.  One scenario where this occurs
+     * is where a class contains a field of type List of X, where X is a oneOf base class with a discriminator.
+     *
+     * So in those cases where we're asked to serialize something, we'll just delegate to a TypeAdapter
+     * that's associated with the object's specific runtime type (i.e. the subclass).
+     *
      */
+    @SuppressWarnings({ "unchecked", "rawtypes" })
     @Override
     public void write(JsonWriter out, T value) throws IOException {
-      // We should never be asked to serialize a generated class that contains
-      // the discriminator metadata, but just in case, just throw an exception.
-      throw new IOException("Serialization of discriminator base classes is not supported");
+
+      if (value == null) {
+        out.nullValue();
+        return;
+      }
+
+      // Ask Gson for a TypeAdapter for value's runtime type.
+      TypeAdapter adapter = gson.getAdapter(value.getClass());
+
+      // Check to make sure Gson didn't just hand us back "this" as the adapter.
+      // This shouldn't happen, but some bullet-proofing never hurts.
+      if (adapter == null || this.getClass().equals(adapter.getClass())) {
+        // We should never be asked to serialize a generated class that contains
+        // the discriminator metadata, but just in case, just throw an exception.
+        throw new IOException(String.format("Serialization of discriminator base class %s is not supported",
+            value.getClass().getName()));
+      }
+
+      // Delegate to the runtime type's adapter.
+      adapter.write(out, value);
     }
 
     /**

src/main/java/com/ibm/cloud/sdk/core/util/GsonSingleton.java

@@ -39,14 +39,17 @@ private GsonSingleton() {
    * @param prettyPrint if true the JSON will be pretty printed
    * @return the {@link Gson}
    */
-  private static Gson createGson(Boolean prettyPrint) {
+  private static Gson createGson(boolean prettyPrint, boolean serializeNulls) {
     GsonBuilder builder = new GsonBuilder();
 
     registerTypeAdapters(builder);
 
     if (prettyPrint) {
       builder.setPrettyPrinting();
     }
+    if (serializeNulls) {
+      builder.serializeNulls();
+    }
     builder.disableHtmlEscaping();
     return builder.create();
   }
@@ -76,7 +79,7 @@ private static void registerTypeAdapters(GsonBuilder builder) {
    */
   public static synchronized Gson getGson() {
     if (gson == null) {
-      gson = createGson(true);
+      gson = createGson(true, false);
     }
     return gson;
   }
@@ -88,8 +91,16 @@ public static synchronized Gson getGson() {
    */
   public static synchronized Gson getGsonWithoutPrettyPrinting() {
     if (gsonWithoutPrinting == null) {
-      gsonWithoutPrinting = createGson(false);
+      gsonWithoutPrinting = createGson(false, false);
     }
     return gsonWithoutPrinting;
   }
+
+  /**
+   * Returns an instance of Gson with the "serialize nulls" config option enabled.
+   * @return
+   */
+  public static Gson getGsonWithSerializeNulls() {
+    return createGson(false, true);
+  }
 }

src/test/java/com/ibm/cloud/sdk/core/test/model/DiscriminatorSerializationTest.java

@@ -17,6 +17,11 @@
 import static org.testng.Assert.assertNotNull;
 import static org.testng.Assert.assertTrue;
 
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
 import org.testng.annotations.Test;
 
 import com.google.gson.JsonSyntaxException;
@@ -41,6 +46,12 @@
 public class DiscriminatorSerializationTest {
   private boolean displayOutput = false;
 
+  private void log(String msg) {
+    if (displayOutput) {
+      System.out.println(msg);
+    }
+  }
+
   private String serialize(Object obj) {
     return GsonSingleton.getGson().toJson(obj);
   }
@@ -51,13 +62,11 @@ private <T> T deserialize(String json, Class<T> clazz) {
 
   private <T> void testSerDeser(Object model, Class<T> baseClass, Class<? extends T> subClass) {
     String jsonString = serialize(model);
-    if (displayOutput) {
-      System.out.println("serialized " + model.getClass().getSimpleName() + ": " + jsonString);
-    }
+    log("serialized " + model.getClass().getSimpleName() + ": " + jsonString);
+
     T newModel = deserialize(jsonString, baseClass);
-    if (displayOutput) {
-      System.out.println("de-serialized " + model.getClass().getSimpleName() + ": " + newModel.toString());
-    }
+    log("de-serialized " + model.getClass().getSimpleName() + ": " + newModel.toString());
+
     assertEquals(newModel.toString(), model.toString());
     assertEquals(newModel.getClass().getName(), subClass.getName());
   }
@@ -108,6 +117,131 @@ public void testTruck() {
     testSerDeser(model, Vehicle.class, Truck.class);
   }
 
+  // These classes simulate generated model classes that contain a list/map of discriminated oneOf parents.
+  public class VehicleHolder {
+    int size;
+    List<Vehicle> vehicles;
+
+    public VehicleHolder(List<Vehicle> vehicles) {
+      this.vehicles = vehicles;
+      this.size = vehicles != null ? vehicles.size() : 0;
+    }
+  }
+
+  public class AnimalHolder {
+    int size;
+    Map<String, Animal> animals;
+
+    public AnimalHolder(Map<String, Animal> animals) {
+      this.animals = animals;
+      this.size = animals != null ? animals.size() : 0;
+    }
+  }
+
+  @Test
+  public void testVehicleList() {
+
+    // Create an instance of VehicleHolder that contains a list of Vehicle instances.
+    List<Vehicle> vehicleList = new ArrayList<>();
+    vehicleList.add(createTruck("truck"));
+    vehicleList.add(createCar("Car"));
+    VehicleHolder expected = new VehicleHolder(vehicleList);
+
+    // Make sure we can serialize the model instance containing the list of oneOf parents.
+    String json = serialize(expected);
+    assertNotNull(json);
+    log("Vehicle holder (json): " + json);
+
+    VehicleHolder actual = GsonSingleton.getGson().fromJson(json, VehicleHolder.class);
+    assertNotNull(actual);
+    assertEquals(actual.size, expected.size);
+    assertEquals(actual.vehicles, expected.vehicles);
+  }
+
+  @Test
+  public void testVehiclesNullList() {
+    VehicleHolder expected = new VehicleHolder(null);
+
+    String json = serialize(expected);
+    assertNotNull(json);
+    log("Vehicle holder (json): " + json);
+
+    VehicleHolder actual = GsonSingleton.getGson().fromJson(json, VehicleHolder.class);
+    assertNotNull(actual);
+    assertEquals(actual.size, expected.size);
+    assertEquals(actual.vehicles, expected.vehicles);
+  }
+
+  @Test
+  public void testVehiclesNullElement() {
+    List<Vehicle> vehicles = new ArrayList<>();
+    vehicles.add(null);
+
+    VehicleHolder expected = new VehicleHolder(vehicles);
+
+    String json = serialize(expected);
+    assertNotNull(json);
+    log("Vehicle holder (json): " + json);
+
+    VehicleHolder actual = GsonSingleton.getGson().fromJson(json, VehicleHolder.class);
+    assertNotNull(actual);
+    assertEquals(actual.size, expected.size);
+    assertEquals(actual.vehicles, expected.vehicles);
+  }
+
+  @Test
+  public void testAnimals() {
+
+    // Create an instance of AnimalHolder that contains a map of Animal instances.
+    Map<String, Animal> animals = new HashMap<>();
+    animals.put("Fred", createCat("feline"));
+    animals.put("Elvis", createDog("dog"));
+    animals.put("Tito", createDog("canine"));
+    animals.put("Alfred", createIguana("Iguana"));
+    AnimalHolder expected = new AnimalHolder(animals);
+
+    String json = serialize(expected);
+    assertNotNull(json);
+    log("Animal holder (json): " + json);
+
+    AnimalHolder actual = GsonSingleton.getGson().fromJson(json, AnimalHolder.class);
+    assertNotNull(actual);
+    assertEquals(actual.size, expected.size);
+    assertEquals(actual.animals, expected.animals);
+  }
+
+  @Test
+  public void testAnimalsNullMap() {
+    AnimalHolder expected = new AnimalHolder(null);
+
+    String json = serialize(expected);
+    assertNotNull(json);
+    log("Animal holder (json): " + json);
+
+    AnimalHolder actual = GsonSingleton.getGson().fromJson(json, AnimalHolder.class);
+    assertNotNull(actual);
+    assertEquals(actual.size, expected.size);
+    assertEquals(actual.animals, expected.animals);
+  }
+
+  @Test
+  public void testAnimalsNullElement() {
+    Map<String, Animal> animals = new HashMap<>();
+    animals.put("missing_dog", null);
+    AnimalHolder expected = new AnimalHolder(animals);
+
+    // We have to enable "serialize nulls" because Gson's handling of maps seems to be inconsistent with their
+    // support of lists.
+    String json = GsonSingleton.getGsonWithSerializeNulls().toJson(expected);
+    assertNotNull(json);
+    log("Animal holder (json): " + json);
+
+    AnimalHolder actual = GsonSingleton.getGson().fromJson(json, AnimalHolder.class);
+    assertNotNull(actual);
+    assertEquals(actual.size, expected.size);
+    assertEquals(actual.animals, expected.animals);
+  }
+
   @Test(expectedExceptions = {JsonSyntaxException.class})
   void testTruckDiscPropMissing() {
     Truck model = createTruck(null);