XmlUtil

• Core: 
• Serialization: 
• SerialUtil: 

XmlUtil is a set of packages that supports multiplatform XML in Kotlin.

Introduction

This project is a cross-platform XML serialization (wrapping) library compatible with kotlinx.serialization. It supports all platforms although native is at beta quality.

Based upon the core xml library, the serialization module supports automatic object serialization based upon Kotlin's standard serialization library and plugin.

Help wanted: Any help with extending this project is welcome. Help is especially needed for the following aspects:

• Documentation updates
• Testing, in particular more extensive tests. Some tests already exist for both JVM and Android
• Native xml library support: Native is only supported through the cross-platform implementation that is somewhat limited in advanced features such as DTD and validation support. Ideally integration with a well-developed native library as an option would be beneficial.

Versioning scheme

This library is based upon the kotlinx.serialization library. Every effort is made to limit incompatible changes.

How to use

The library is designed as a multiplatform Kotlin module, but platform-specific versions can also be used were appropriate.

Add repository

The project's Maven access is hosted on OSS Sonatype (and available from Maven Central).

Releases can be added from maven central

Snapshots are available from the default maven central snapshot repository:

repositories {
	maven {
		url  "https://central.sonatype.com/repository/maven-snapshots/"
	}
}

Core

It should be noted that the JVM and Android packages are no longer part of the multiplatform publication (they are combined into a jvmCommon) package. The JVM and Android packages provide the native implementations and depend on (publishing) the jvmCommon package.

multiplatform (will default to multiplatform implementation for JVM/Android)

   implementation("io.github.pdvrieze.xmlutil:core:1.0.0-rc2")

Optional JVM – uses the stax API not available on Android

   implementation("io.github.pdvrieze.xmlutil:core-jdk:1.0.0-rc2")

Optional Android – Uses the android streaming library

   implementation("io.github.pdvrieze.xmlutil:core-android:1.0.0-rc2")

JS – Wraps DOM

   implementation("io.github.pdvrieze.xmlutil:core-js:1.0.0-rc2")

Native

Has platform independent implementations of xml parsing/serialization (based upon the Android implementation) and DOM (a simple implementation that mirrors the Java API)

Serialization

multiplatform (this coordinate should be used by default)

   implementation("io.github.pdvrieze.xmlutil:serialization:1.0.0-rc2")

Serialization help

Hello world

To serialize a very simple type you have the following:

@Serializable
data class HelloWorld(val user: String)

println(XML1_0.encodeToString(HelloWorld("You!")))

To deserialize you would do:

@Serializable
data class HelloWorld(val user: String)

XML1_0.decodeFromString(HelloWorld.serializer(), "<HelloWorld user='You!' />")

Please look at the examples and the documentation for further features that can influence: the tag names/namespaces used, the actual structure used (how lists and polymorphic types are handled), etc.

Examples

You should be able to find examples in the Examples module

Format

The entrypoint to the library is the XML.v1 (for 1.0) format (or XML generally). There is a default, but often a child is better. Custom formats are created through:

val format = XML.v1.recommended(mySerialModule) {  
    // configuration options
    xmlDeclMode = XmlDeclMode.None
    policy {
        typeDiscriminatorName = QName(XMLConstants.XSI_NS_URI, "type", XMLConstants.XSI_PREFIX)
    }
}

The configuration for the XML format is separated between the configuration, and embedded inside it a policy. The configuration mainly covers the xml serialization, but not how serializable types are reflected in XML. The policy is designed to allow for programmatic determination of how serialization occurs.

The following options are available when using the XML format builder. For new code you should use the XML1_0 entry point. This entry point is equivalent to the recommended configuration for version 0.92.0.

There are four functions to create a new XML format. They provide different presets for the configuration (that can then be adjusted through the configuration function).

| Entry point | Description | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | recommended {} | The recommended configuration for version 1.0. This version defaults to indented XML1.1 with unwrapped polymorphism. | | compact {} | Changes serialization to be more compact, omitting XML declarations and indentation. | | fast {} | Changes the format to focus on performance of serialization and deserialization. This omits error checking and has more aggressive caching. | | customPolicy() {} | Preset that sets the configuration as recommended, but allows for a customized policy to be provided. Unlike the other presets this policy does not need to extend DefaultXmlSerializationPolicy. |

Each presets provides access to the configuration builder with the following options (and access to both the policy property for setting the policy as well as the policy function for further configuring the policy):

| Option | Description | |----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | repairNamespaces | Should namespaces automatically be repaired. This option will be passed on to the XmlWriter | | xmlDeclMode | The mode to use for emitting XML declarations (<?xml ...?>). Replaces omitXmlDecl for more finegrained control | | indentString | The indentation to use. Must be a combination of XML whitespace or comments (this is checked). This is passed to the XmlWriter | | (val) indent | Read only access to the indentation level of the indentString (a tab is counted as 8 spaces) | | setIndent() | The indentation level (in spaces) to use. This sets the indentString value. | | nilAttribute | A pair of QName and string for the attribute to use to denote a nil value. If null elements will be omitted | | useXsiNil() | Shortcut to set nilAttribute appropriately to serialize using the XMLSchema Instance nil attribute | | isAlwaysDecodeXsiNil | When set, decoding will always handle xsi:nil values, independent of the value of nilAttribute. |
| xmlVersion | Which xml version will be written/declared (default XML 1.1). | | isCollectingNSAttributes | (Attempt to) collect all needed namespace declarations and emit them on the root tag, this does have a performance overhead | | defaultToGenericParser | Use the generic (platform independent) parser, rather than the platform specific one. | | isUnchecked | When set, various correctness checks are skipped to speed up processing (but less robust handling of incorrect inputs or serializers) | | policy | Property that gives access to the underlying policy for configuration. | | policy {} | Builder that allows configuring the default policy (all presets except customPolicy). This builder does not exist for custom policies |

The defaults are:

| Option | Recommended/custom | Compact | Fast | |----------------------------|-----------------------|---------------------