Update the example Jackson policy, make it configurable, to show

how an extension of the default policy can still be configurable.

Author: pdvrieze

examples/JACKSON.md

@@ -22,22 +22,32 @@ data class Team(val members: List<Person>, val colors: List<String> = listOf())
 ```kotlin
 /**
  * Example policy that (very crudely) mimicks the way that Jackson serializes xml. It starts by eliding defaults.
- * Note that this version doesn't handle the jackson annotations.
+ * Note that this version doesn't handle the jackson annotations, and is not configurable.
  */
-object JacksonPolicy :
-    DefaultXmlSerializationPolicy(false, encodeDefault = XmlSerializationPolicy.XmlEncodeDefault.NEVER) {
+class JacksonPolicy(formatCache: FormatCache = defaultSharedFormatCache(), config: Builder.() -> Unit = {}) :
+    DefaultXmlSerializationPolicy(formatCache, {
+        pedantic = false
+        encodeDefault = XmlSerializationPolicy.XmlEncodeDefault.NEVER
+        config()
+    }) {
+
+    constructor(config: Builder.() -> Unit): this(defaultSharedFormatCache(), config)
+
     /*
      * Rather than replacing the method wholesale, just make attributes into elements unless the [XmlElement] annotation
      * is present with a `false` value on the value attribute.
      */
-    override fun effectiveOutputKind(serializerParent: SafeParentInfo, tagParent: SafeParentInfo): OutputKind {
-        val r = super.effectiveOutputKind(serializerParent, tagParent)
+    override fun effectiveOutputKind(
+        serializerParent: SafeParentInfo,
+        tagParent: SafeParentInfo,
+        canBeAttribute: Boolean
+    ): OutputKind {
+        val r = super.effectiveOutputKind(serializerParent, tagParent, canBeAttribute)
         return when {
             // Do take into account the XmlElement annotation
             r == OutputKind.Attribute &&
-                    serializerParent.elementUseAnnotations.mapNotNull { it as? XmlElement }
-                        .firstOrNull()?.value != false
-                 -> OutputKind.Element
+                    serializerParent.useAnnIsElement != false ->
+                OutputKind.Element
 
             else -> r
         }
@@ -53,14 +63,28 @@ object JacksonPolicy :
         tagParent: SafeParentInfo,
         outputKind: OutputKind,
         useName: XmlSerializationPolicy.DeclaredNameInfo
-                              ): QName {
+    ): QName {
         return useName.annotatedName
-            ?: serializerParent.elemenTypeDescriptor.typeQname
-            ?: serialNameToQName(useName.serialName, tagParent.namespace)
+            ?: serializerParent.elementTypeDescriptor.typeQname
+            ?: serialUseNameToQName(useName, tagParent.namespace)
     }
 
 }
 ```
+For allowing elegant configuration, the below code prvoides for configuration.
+Note that this function's implementation could be adjusted to allow for
+a class (not object) policy that would also allow for further configuration.
+
+```kotlin
+fun XmlConfig.Builder.jacksonPolicy(config: Builder.() -> Unit = {}) {
+    @OptIn(ExperimentalXmlUtilApi::class)
+    policy = JacksonPolicy {
+        setDefaults_0_91_0()
+        encodeDefault = XmlSerializationPolicy.XmlEncodeDefault.NEVER
+        config()
+    }
+}
+```
 
 
 ## Example usage
@@ -69,15 +93,15 @@ object JacksonPolicy :
 fun main() {
     val t = Team(listOf(Person("Joe", 15)))
     val xml = XML {
-        policy = JacksonPolicy
+        jacksonPolicy()
     }
 
     val encodedString = xml.encodeToString(t) // both versions are available
     println("jackson output:\n${encodedString.prependIndent("    ")}\n")
 
-    // the inline reified version is is also available
+    // the inline reified version is also available
     val reparsedData = xml.decodeFromString<Team>(encodedString)
     println("jackson input: $reparsedData")
 
 }
-```
+```

examples/src/main/kotlin/net/devrieze/serialization/examples/jackson/JacksonPolicy.kt

@@ -23,19 +23,22 @@ package net.devrieze.serialization.examples.jackson
 import nl.adaptivity.xmlutil.ExperimentalXmlUtilApi
 import nl.adaptivity.xmlutil.QName
 import nl.adaptivity.xmlutil.serialization.*
+import nl.adaptivity.xmlutil.serialization.DefaultXmlSerializationPolicy.Builder
 import nl.adaptivity.xmlutil.serialization.structure.SafeParentInfo
 
 /**
  * Example policy that (very crudely) mimicks the way that Jackson serializes xml. It starts by eliding defaults.
- * Note that this version doesn't handle the jackson annotations.
+ * Note that this version doesn't handle the jackson annotations, and is not configurable.
  */
-object JacksonPolicy : DefaultXmlSerializationPolicy(
-    defaultSharedFormatCache(),
-    {
+class JacksonPolicy(formatCache: FormatCache = defaultSharedFormatCache(), config: Builder.() -> Unit = {}) :
+    DefaultXmlSerializationPolicy(formatCache, {
         pedantic = false
         encodeDefault = XmlSerializationPolicy.XmlEncodeDefault.NEVER
-    },
-) {
+        config()
+    }) {
+
+    constructor(config: Builder.() -> Unit): this(defaultSharedFormatCache(), config)
+
     /*
      * Rather than replacing the method wholesale, just make attributes into elements unless the [XmlElement] annotation
      * is present with a `false` value on the value attribute.
@@ -75,7 +78,11 @@ object JacksonPolicy : DefaultXmlSerializationPolicy(
 }
 
 /** Extension function for elegant configuration */
-fun XmlConfig.Builder.jacksonPolicy() {
+fun XmlConfig.Builder.jacksonPolicy(config: Builder.() -> Unit = {}) {
     @OptIn(ExperimentalXmlUtilApi::class)
-    policy = JacksonPolicy
+    policy = JacksonPolicy {
+        setDefaults_0_91_0()
+        encodeDefault = XmlSerializationPolicy.XmlEncodeDefault.NEVER
+        config()
+    }
 }

examples/src/main/kotlin/net/devrieze/serialization/examples/jackson/main.kt

@@ -1,29 +1,27 @@
 /*
- * Copyright (c) 2020.
+ * Copyright (c) 2020-2025.
  *
  * This file is part of xmlutil.
  *
- * This file is licenced to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License.  You should have received a copy of the license with the source distribution.
- * Alternatively, you may obtain a copy of the License at
+ * This file is licenced to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance
+ * with the License.  You should have  received a copy of the license
+ * with the source distribution. Alternatively, you may obtain a copy
+ * of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied.  See the License for the specific language governing
+ * permissions and limitations under the License.
  */
 
 package net.devrieze.serialization.examples.jackson
 
 import kotlinx.serialization.decodeFromString
 import kotlinx.serialization.encodeToString
-import kotlinx.serialization.serializer
-import nl.adaptivity.xmlutil.ExperimentalXmlUtilApi
 import nl.adaptivity.xmlutil.serialization.XML
 
 fun main() {
@@ -35,7 +33,7 @@ fun main() {
     val encodedString = xml.encodeToString(t) // both versions are available
     println("jackson output:\n${encodedString.prependIndent("    ")}\n")
 
-    // the inline reified version is is also available
+    // the inline reified version is also available
     val reparsedData = xml.decodeFromString<Team>(encodedString)
     println("jackson input: $reparsedData")