Merge remote-tracking branch 'FasterXML/2.x' into 3.x

Author: k163377

release-notes/CREDITS-2.x

@@ -18,6 +18,7 @@ Contributors:
 # 2.20.0 (not yet released)
 
 WrongWrong (@k163377)
+* #1025: Deprecate MissingKotlinParameterException and replace with new exception
 * #1020: Fixed old StrictNullChecks to throw exceptions similar to those thrown by new StrictNullChecks
 * #1018: Use MethodHandle in processing related to value class
 * #969: Cleanup of deprecated contents

release-notes/VERSION-2.x

@@ -17,6 +17,11 @@ Co-maintainers:
 ------------------------------------------------------------------------
 
 2.20.0 (not yet released)
+#1025: When a null is entered for a non-null parameter, the KotlinInvalidNullException is now thrown instead of the
+  deprecated MissingKotlinParameterException.
+  The new exception is a subclass of InvalidNullException.
+  See the comment below for information contained in this exception.
+  https://github.com/FasterXML/jackson-module-kotlin/issues/617#issuecomment-3124423585
 #1020: Exceptions thrown by the old StrictNullChecks are now the similar to the new StrictNullChecks.
   This means that the old StrictNullChecks will no longer throw MissingKotlinParameterException.
   See PR for what is thrown and how error messages change.

src/main/java/tools/jackson/module/kotlin/KotlinInvalidNullException.java

@@ -0,0 +1,65 @@
+package tools.jackson.module.kotlin;
+
+import tools.jackson.core.JsonParser;
+import tools.jackson.databind.DatabindException;
+import tools.jackson.databind.PropertyName;
+import tools.jackson.databind.exc.InvalidNullException;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+// Due to a limitation in KT-6653, there is no user-friendly way to override Java getters in Kotlin.
+// The reason for not having detailed information(e.g. KParameter) is to keep the class Serializable.
+/**
+ * Specialized {@link DatabindException} sub-class used to indicate that a mandatory Kotlin creator parameter was
+ * missing or null.
+ */
+public final class KotlinInvalidNullException extends InvalidNullException {
+    @NotNull
+    private final String kotlinPropertyName;
+
+    KotlinInvalidNullException(
+            @Nullable
+            String kotlinParameterName,
+            @NotNull
+            Class<?> valueClass,
+            @NotNull
+            JsonParser p,
+            @NotNull
+            String msg,
+            @NotNull
+            PropertyName pname
+    ) {
+        super(p, msg, pname);
+        // Basically, this will never be null, but it is handled here to avoid errors in unusual cases.
+        this.kotlinPropertyName = kotlinParameterName == null ? "UNKNOWN" : kotlinParameterName;
+        this._targetType = valueClass;
+    }
+
+    /**
+     * @return Parameter name in Kotlin.
+     */
+    @NotNull
+    public String getKotlinPropertyName() {
+        return kotlinPropertyName;
+    }
+
+    // region: Override getters to make nullability explicit and to explain its role in this class.
+    /**
+     * @return Parameter name in Jackson.
+     */
+    @NotNull
+    @Override
+    public PropertyName getPropertyName() {
+        return super.getPropertyName();
+    }
+
+    /**
+     * @return The {@link Class} object representing the class that declares the creator.
+     */
+    @NotNull
+    @Override
+    public Class<?> getTargetType() {
+        return super.getTargetType();
+    }
+    // endregion
+}

src/main/kotlin/tools/jackson/module/kotlin/Exceptions.kt

@@ -10,14 +10,10 @@ import kotlin.reflect.KParameter
  * parameter was missing or null.
  */
 @Deprecated(
-    "It is recommended that InvalidNullException be referenced when possible," +
-            " as the change is discussed for 2.20 and later." +
-            " See #617 for details.",
-    ReplaceWith(
-        "InvalidNullException",
-        "com.fasterxml.jackson.databind.exc.InvalidNullException"
-    ),
-    DeprecationLevel.WARNING
+    "Since 2.20, this exception is no longer thrown and has been replaced by KotlinInvalidNullException. " +
+            "See #617 for details.",
+    ReplaceWith("KotlinInvalidNullException"),
+    DeprecationLevel.ERROR
 )
 // When deserialized by the JDK, the parameter property will be null, ignoring nullability.
 // This is a temporary workaround for #572 and we will eventually remove this class.

src/main/kotlin/tools/jackson/module/kotlin/KotlinValueInstantiator.kt

@@ -90,15 +90,18 @@ internal class KotlinValueInstantiator(
                 if (propType.requireEmptyValue()) {
                     paramVal = valueDeserializer!!.getEmptyValue(ctxt)
                 } else {
+                    val pname = jsonProp.name
                     val isMissingAndRequired = isMissing && jsonProp.isRequired
 
                     // Since #310 reported that the calculation cost is high, isGenericTypeVar is determined last.
                     if (isMissingAndRequired || (!paramType.isMarkedNullable && !paramType.isGenericTypeVar())) {
-                        throw MissingKotlinParameterException(
-                            parameter = paramDef,
-                            processor = ctxt.parser,
-                            msg = "Instantiation of ${this.valueTypeDesc} value failed for JSON property ${jsonProp.name} due to missing (therefore NULL) value for creator parameter ${paramDef.name} which is a non-nullable type"
-                        ).wrapWithPath(this.valueClass, jsonProp.name)
+                        throw KotlinInvalidNullException(
+                            paramDef.name,
+                            this.valueClass,
+                            ctxt.parser,
+                            "Instantiation of ${this.valueTypeDesc} value failed for JSON property $pname due to missing (therefore NULL) value for creator parameter ${paramDef.name} which is a non-nullable type",
+                            jsonProp.fullName,
+                        ).wrapWithPath(this.valueClass, pname)
                     }
                 }
             } else if (strictNullChecks) {

src/test/kotlin/tools/jackson/module/kotlin/KotlinInvalidNullExceptionTest.kt

@@ -0,0 +1,34 @@
+package tools.jackson.module.kotlin
+
+import com.fasterxml.jackson.annotation.JsonProperty
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import kotlin.test.assertEquals
+
+private data class Dto(
+    val foo: String,
+    @JsonProperty("bar")
+    val _bar: String
+)
+
+class KotlinInvalidNullExceptionTest {
+    @Test
+    fun fooTest() {
+        val json = """{"bar":"bar"}"""
+        val ex = assertThrows<KotlinInvalidNullException> { defaultMapper.readValue<Dto>(json) }
+
+        assertEquals("foo", ex.kotlinPropertyName)
+        assertEquals("foo", ex.propertyName.simpleName)
+        assertEquals(Dto::class, ex.targetType.kotlin)
+    }
+
+    @Test
+    fun barTest() {
+        val json = """{"foo":"foo","bar":null}"""
+        val ex = assertThrows<KotlinInvalidNullException> { defaultMapper.readValue<Dto>(json) }
+
+        assertEquals("_bar", ex.kotlinPropertyName)
+        assertEquals("bar", ex.propertyName.simpleName)
+        assertEquals(Dto::class, ex.targetType.kotlin)
+    }
+}

src/test/kotlin/tools/jackson/module/kotlin/MissingKotlinParameterExceptionTest.kt

@@ -5,6 +5,7 @@ import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 
 class MissingKotlinParameterExceptionTest {
+    @Suppress("DEPRECATION_ERROR")
     @Test
     fun jdkSerializabilityTest() {
         val param = ::MissingKotlinParameterException.parameters.first()

src/test/kotlin/tools/jackson/module/kotlin/test/NullToDefaultTests.kt

@@ -7,7 +7,7 @@ import org.junit.jupiter.api.assertThrows
 import tools.jackson.databind.DeserializationFeature
 import tools.jackson.databind.json.JsonMapper
 import tools.jackson.module.kotlin.KotlinFeature.NullIsSameAsDefault
-import tools.jackson.module.kotlin.MissingKotlinParameterException
+import tools.jackson.module.kotlin.KotlinInvalidNullException
 import tools.jackson.module.kotlin.kotlinModule
 import tools.jackson.module.kotlin.readValue
 
@@ -153,7 +153,7 @@ class TestNullToDefault {
 
     @Test
     fun shouldThrowExceptionWhenProvidedNullForNotNullFieldWithoutDefault() {
-        assertThrows<MissingKotlinParameterException> {
+        assertThrows<KotlinInvalidNullException> {
             createMapper(true).readValue<TestClass>(
                 """{
 						"text": null

src/test/kotlin/tools/jackson/module/kotlin/test/github/Github168.kt

@@ -4,7 +4,7 @@ import com.fasterxml.jackson.annotation.JsonProperty
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
 import tools.jackson.databind.ObjectMapper
-import tools.jackson.module.kotlin.MissingKotlinParameterException
+import tools.jackson.module.kotlin.KotlinInvalidNullException
 import tools.jackson.module.kotlin.defaultMapper
 import tools.jackson.module.kotlin.jacksonObjectMapper
 import tools.jackson.module.kotlin.readValue
@@ -24,7 +24,7 @@ class TestGithub168 {
 
     @Test
     fun testIfRequiredIsReallyRequiredWhenAbsent() {
-        assertThrows<MissingKotlinParameterException> {
+        assertThrows<KotlinInvalidNullException> {
             val obj = defaultMapper.readValue<TestClass>("""{"baz":"whatever"}""")
             assertEquals("whatever", obj.baz)
         }

src/test/kotlin/tools/jackson/module/kotlin/test/github/Github32.kt

@@ -4,7 +4,7 @@ import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
 import tools.jackson.databind.DatabindException
-import tools.jackson.databind.exc.MismatchedInputException
+import tools.jackson.module.kotlin.KotlinInvalidNullException
 import tools.jackson.module.kotlin.defaultMapper
 import tools.jackson.module.kotlin.readValue
 
@@ -19,8 +19,8 @@ private class TestGithub32 {
     }
 
     @Test fun `missing mandatory data class constructor param`() {
-        val thrown = assertThrows<MismatchedInputException>(
-            "MissingKotlinParameterException with missing `firstName` parameter"
+        val thrown = assertThrows<KotlinInvalidNullException>(
+            "KotlinInvalidNullException with missing `firstName` parameter"
         ) {
             defaultMapper.readValue<Person>("""
             {
@@ -35,7 +35,7 @@ private class TestGithub32 {
     }
 
     @Test fun `null mandatory data class constructor param`() {
-        val thrown = assertThrows<MismatchedInputException> {
+        val thrown = assertThrows<KotlinInvalidNullException> {
             defaultMapper.readValue<Person>("""
             {
                 "firstName": null,
@@ -50,7 +50,7 @@ private class TestGithub32 {
     }
 
     @Test fun `missing mandatory constructor param - nested in class with default constructor`() {
-        val thrown = assertThrows<MismatchedInputException> {
+        val thrown = assertThrows<KotlinInvalidNullException> {
             defaultMapper.readValue<WrapperWithDefaultContructor>("""
             {
                 "person": {
@@ -66,7 +66,7 @@ private class TestGithub32 {
     }
 
     @Test fun `missing mandatory constructor param - nested in class with single arg constructor`() {
-        val thrown = assertThrows<MismatchedInputException> {
+        val thrown = assertThrows<KotlinInvalidNullException> {
             defaultMapper.readValue<WrapperWithArgsContructor>("""
             {
                 "person": {
@@ -82,7 +82,7 @@ private class TestGithub32 {
     }
 
     @Test fun `missing mandatory constructor param - nested in class with List arg constructor`() {
-        val thrown = assertThrows<MismatchedInputException> {
+        val thrown = assertThrows<KotlinInvalidNullException> {
             defaultMapper.readValue<Crowd>("""
             {
                 "people": [