feat!: use kotlin nullability for null documents instead of explicit subclass (#664)

Author: lucix-aws

.changes/1a759771-971f-4354-838f-ee7b0364e379.json

@@ -0,0 +1,5 @@
+{
+    "id": "1a759771-971f-4354-838f-ee7b0364e379",
+    "type": "feature",
+    "description": "(breaking) Use kotlin nullability to represent null Documents instead of an explicit subclass."
+}

docs/design/document-type.md

@@ -38,19 +38,16 @@ sealed class Document {
     data class Number(val value: kotlin.Number) : Document()
     data class String(val value: kotlin.String) : Document()
     data class Boolean(val value: kotlin.Boolean) : Document()
-    data class List(val value: kotlin.collections.List<Document>) :
-        Document(), kotlin.collections.List<Document> by value
-    data class Map(val value: kotlin.collections.Map<kotlin.String, Document>) :
-        Document(), kotlin.collections.Map<kotlin.String, Document> by value
-    object Null : Document()
+    data class List(val value: kotlin.collections.List<Document?>) :
+        Document(), kotlin.collections.List<Document?> by value
+    data class Map(val value: kotlin.collections.Map<kotlin.String, Document?>) :
+        Document(), kotlin.collections.Map<kotlin.String, Document?> by value
 
     fun asString(): kotlin.String
     fun asStringOrNull(): kotlin.String?
     fun asInt(): Int
     fun asIntOrNull(): Int?
     // etc...
-    val isNull: kotlin.Boolean
-        get() = this == Null
 }
 ```
 
@@ -64,12 +61,14 @@ class DocumentBuilder internal constructor() {
     infix fun String.to(value: String?)
     infix fun String.to(value: Boolean?)
     infix fun String.to(value: Document?)
+    infix fun String.to(value: Nothing?)
 
     class ListBuilder internal constructor() {
         fun add(value: Number?)
         fun add(value: String?)
         fun add(value: Boolean?)
         fun add(value: Document?)
+        fun add(value: Nothing?)
 
         fun addAll(value: List<Number?>)
         fun addAll(value: List<String?>)
@@ -106,4 +105,5 @@ fun main() {
 # Revision history
 
 * 5/27/2021 - Initial upload
-* 5/22/2022 - Refine/extend structure and use of interface
+* 5/22/2022 - Refine/extend structure and use of interface
+* 6/16/2022 - Refactor nullability to use kotlin instead of explicit subclass

gradle.properties

@@ -8,7 +8,7 @@ kotlin.native.ignoreDisabledTargets=true
 kotlin.mpp.hierarchicalStructureSupport=false
 
 # SDK
-sdkVersion=0.10.3-SNAPSHOT
+sdkVersion=0.11.0-SNAPSHOT
 
 # kotlin
 kotlinVersion=1.6.21

runtime/runtime-core/common/src/aws/smithy/kotlin/runtime/smithy/Document.kt

@@ -42,16 +42,16 @@ sealed class Document {
     /**
      * Wraps a [kotlin.collections.List].
      */
-    data class List(val value: kotlin.collections.List<Document>) :
-        Document(), kotlin.collections.List<Document> by value {
+    data class List(val value: kotlin.collections.List<Document?>) :
+        Document(), kotlin.collections.List<Document?> by value {
         override fun toString() = value.joinToString(separator = ",", prefix = "[", postfix = "]")
     }
 
     /**
      * Wraps a [kotlin.collections.Map].
      */
-    data class Map(val value: kotlin.collections.Map<kotlin.String, Document>) :
-        Document(), kotlin.collections.Map<kotlin.String, Document> by value {
+    data class Map(val value: kotlin.collections.Map<kotlin.String, Document?>) :
+        Document(), kotlin.collections.Map<kotlin.String, Document?> by value {
         override fun toString() = value
             .entries
             .joinToString(
@@ -62,13 +62,6 @@ sealed class Document {
             )
     }
 
-    /**
-     * Represents a `null` value.
-     */
-    object Null : Document() {
-        override fun toString() = "null"
-    }
-
     private fun asNumber(): kotlin.Number = (this as Number).value
     private fun asNumberOrNull(): kotlin.Number? = (this as? Number)?.value
 
@@ -78,11 +71,11 @@ sealed class Document {
     fun asBoolean(): kotlin.Boolean = (this as Boolean).value
     fun asBooleanOrNull(): kotlin.Boolean? = (this as? Boolean)?.value
 
-    fun asList(): kotlin.collections.List<Document> = (this as List).value
-    fun asListOrNull(): kotlin.collections.List<Document>? = (this as? List)?.value
+    fun asList(): kotlin.collections.List<Document?> = (this as List).value
+    fun asListOrNull(): kotlin.collections.List<Document?>? = (this as? List)?.value
 
-    fun asMap(): kotlin.collections.Map<kotlin.String, Document> = (this as Map).value
-    fun asMapOrNull(): kotlin.collections.Map<kotlin.String, Document>? = (this as? Map)?.value
+    fun asMap(): kotlin.collections.Map<kotlin.String, Document?> = (this as Map).value
+    fun asMapOrNull(): kotlin.collections.Map<kotlin.String, Document?>? = (this as? Map)?.value
 
     fun asInt(): Int = asNumber().toInt()
     fun asIntOrNull(): Int? = asNumberOrNull()?.toInt()
@@ -101,9 +94,6 @@ sealed class Document {
 
     fun asDouble(): Double = asNumber().toDouble()
     fun asDoubleOrNull(): Double? = asNumberOrNull()?.toDouble()
-
-    val isNull: kotlin.Boolean
-        get() = this == Null
 }
 
 /**
@@ -124,9 +114,9 @@ fun Document(value: Boolean): Document = Document.Boolean(value)
 /**
  * Construct a [Document] from a [List].
  */
-fun Document(value: List<Document>): Document = Document.List(value)
+fun Document(value: List<Document?>): Document = Document.List(value)
 
 /**
  * Construct a [Document] from a [Map].
  */
-fun Document(value: Map<String, Document>): Document = Document.Map(value)
+fun Document(value: Map<String, Document?>): Document = Document.Map(value)

runtime/runtime-core/common/src/aws/smithy/kotlin/runtime/smithy/DocumentBuilder.kt

@@ -7,46 +7,46 @@ package aws.smithy.kotlin.runtime.smithy
 import kotlin.jvm.JvmName
 
 class DocumentBuilder internal constructor() {
-    val content: MutableMap<String, Document> = linkedMapOf()
+    val content: MutableMap<String, Document?> = linkedMapOf()
 
     infix fun String.to(value: Number?) {
-        require(content[this] == null) { "Key $this is already registered in builder" }
-        content[this] = if (value != null) Document(value) else Document.Null
+        require(this !in content) { "Key $this is already registered in builder" }
+        content[this] = if (value != null) Document(value) else null
     }
 
     infix fun String.to(value: String?) {
-        require(content[this] == null) { "Key $this is already registered in builder" }
-        content[this] = if (value != null) Document(value) else Document.Null
+        require(this !in content) { "Key $this is already registered in builder" }
+        content[this] = if (value != null) Document(value) else null
     }
 
     infix fun String.to(value: Boolean?) {
-        require(content[this] == null) { "Key $this is already registered in builder" }
-        content[this] = if (value != null) Document(value) else Document.Null
+        require(this !in content) { "Key $this is already registered in builder" }
+        content[this] = if (value != null) Document(value) else null
     }
 
     infix fun String.to(value: Document?) {
-        require(content[this] == null) { "Key $this is already registered in builder" }
-        content[this] = value ?: Document.Null
+        require(this !in content) { "Key $this is already registered in builder" }
+        content[this] = value
     }
 
     infix fun String.to(@Suppress("UNUSED_PARAMETER") value: Nothing?) {
-        require(content[this] == null) { "Key $this is already registered in builder" }
-        content[this] = Document.Null
+        require(this !in content) { "Key $this is already registered in builder" }
+        content[this] = null
     }
 
     class ListBuilder internal constructor() {
-        val content: MutableList<Document> = mutableListOf()
+        val content: MutableList<Document?> = mutableListOf()
 
         fun add(value: Number?): Boolean =
-            content.add(if (value != null) Document(value) else Document.Null)
+            content.add(if (value != null) Document(value) else null)
         fun add(value: String?): Boolean =
-            content.add(if (value != null) Document(value) else Document.Null)
+            content.add(if (value != null) Document(value) else null)
         fun add(value: Boolean?): Boolean =
-            content.add(if (value != null) Document(value) else Document.Null)
+            content.add(if (value != null) Document(value) else null)
         fun add(value: Document?): Boolean =
-            content.add(value ?: Document.Null)
+            content.add(value)
         fun add(@Suppress("UNUSED_PARAMETER") value: Nothing?): Boolean =
-            content.add(Document.Null)
+            content.add(null)
 
         @JvmName("addAllNumbers") fun addAll(value: List<Number?>) = value.forEach(::add)
         @JvmName("addAllStrings") fun addAll(value: List<String?>) = value.forEach(::add)

runtime/runtime-core/common/test/aws/smithy/kotlin/runtime/DocumentBuilderTest.kt

@@ -19,10 +19,10 @@ class DocumentBuilderTest {
                 add(12)
                 add(true)
                 add("blah")
-                add(Document.Null)
+                add(null)
                 addAll(listOf(9, 10, 12))
             }
-            "qux" to Document.Null
+            "qux" to null
         }
 
         val expected = """{"foo":1,"baz":[202,12,true,"blah",null,9,10,12],"qux":null}"""

runtime/serde/common/src/aws/smithy/kotlin/runtime/serde/Serializer.kt

@@ -137,7 +137,7 @@ interface StructSerializer : PrimitiveSerializer {
      * @param descriptor
      * @param value
      */
-    fun field(descriptor: SdkFieldDescriptor, value: Document)
+    fun field(descriptor: SdkFieldDescriptor, value: Document?)
 
     /**
      * Writes the field name given in the descriptor, and then

runtime/serde/serde-form-url/common/src/aws/smithy/kotlin/runtime/serde/formurl/FormUrlSerializer.kt

@@ -131,7 +131,7 @@ private class FormUrlStructSerializer(
         serializeInstant(value, format)
     }
 
-    override fun field(descriptor: SdkFieldDescriptor, value: Document) {
+    override fun field(descriptor: SdkFieldDescriptor, value: Document?) {
         throw SerializationException(
             "cannot serialize field ${descriptor.serialName}; Document type is not supported by form-url encoding"
         )

runtime/serde/serde-json/common/src/aws/smithy/kotlin/runtime/serde/json/JsonDeserializer.kt

@@ -64,27 +64,30 @@ class JsonDeserializer(payload: ByteArray) : Deserializer, Deserializer.ElementI
     }
 
     override fun deserializeDocument(): Document =
+        checkNotNull(deserializeDocumentImpl()) { "expected non-null document field" }
+
+    private fun deserializeDocumentImpl(): Document? =
         when (val token = reader.peek()) {
             is JsonToken.Number -> Document(deserializeNumber())
             is JsonToken.String -> Document(deserializeString())
             is JsonToken.Bool -> Document(deserializeBoolean())
             JsonToken.Null -> {
                 reader.nextToken()
-                Document.Null
+                null
             }
             JsonToken.BeginArray ->
                 deserializeList(SdkFieldDescriptor(SerialKind.Document)) {
-                    val values = mutableListOf<Document>()
+                    val values = mutableListOf<Document?>()
                     while (hasNextElement()) {
-                        values.add(deserializeDocument())
+                        values.add(deserializeDocumentImpl())
                     }
                     Document.List(values)
                 }
             JsonToken.BeginObject ->
                 deserializeMap(SdkFieldDescriptor(SerialKind.Document)) {
-                    val values = mutableMapOf<String, Document>()
+                    val values = mutableMapOf<String, Document?>()
                     while (hasNextEntry()) {
-                        values[key()] = deserializeDocument()
+                        values[key()] = deserializeDocumentImpl()
                     }
                     Document.Map(values)
                 }

runtime/serde/serde-json/common/src/aws/smithy/kotlin/runtime/serde/json/JsonSerializer.kt

@@ -102,7 +102,7 @@ class JsonSerializer : Serializer, ListSerializer, MapSerializer, StructSerializ
         serializeInstant(value, format)
     }
 
-    override fun field(descriptor: SdkFieldDescriptor, value: Document) {
+    override fun field(descriptor: SdkFieldDescriptor, value: Document?) {
         jsonWriter.writeName(descriptor.serialName)
         serializeDocument(value)
     }
@@ -259,12 +259,12 @@ class JsonSerializer : Serializer, ListSerializer, MapSerializer, StructSerializ
         }
     }
 
-    fun serializeDocument(value: Document) {
+    fun serializeDocument(value: Document?) {
         when (value) {
             is Document.Number -> jsonWriter.writeValue(value.value)
             is Document.String -> jsonWriter.writeValue(value.value)
             is Document.Boolean -> jsonWriter.writeValue(value.value)
-            is Document.Null -> jsonWriter.writeNull()
+            null -> jsonWriter.writeNull()
             is Document.List -> {
                 jsonWriter.beginArray()
                 value.value.forEach(::serializeDocument)