0.86.1 – It's the little things

0.86.1

(July 5, 2023)

Features:

• Support detecting duplicate elements outside of list context #145. This
  is not default behaviour as it is somewhat up to the serializer to deal
  with duplicate values, rather than the format.
• Support wildcard (*) for XmlBefore and XmlAfter. These create a
  partition in ordering. An element/attribute with wildcard before will
  be ordered before/after elements that do not have this. Explicit order
  relationships will be maintained.
• Support checking ordering in reading.
• Update to Kotlinx.serialization 1.5.1
• Add SerializableQName as an alias that links it to the serializer.
• Add a helper function XmlSerializationPolicy.recoverNullNamespaceUse that
  can be used to support recovering in case of null namespaces (and them
  effectively functioning as wildcard)
• Handle processing instructions correctly, expose processing instructions as
  target (XmlReader.piTarget) + data (XmlReader.piData) pairs
  attributes and XmlEvent.ProcessingInstructionEvent as event. (#160)
• Allow processing instructions/whitespace as children of Native Document.

Fixes:

• Fix recording/copying of attribute prefixes in copying algorithms (#167).
• Fix reading/writing of processing instruction events (#160).
• Fix recovery of element children (#160).
• Fix decoding of nil elements in certain cases (lists) where the end of the tag
  wasn't parsed. Implemented decodeNull accordingly to actually finish the nil tag.
• Fix accidental immediate emission of xsi:nil elements (rather than deferring
  as expected #152).
• Add expected key name to the error message when it couldn't be found for a
  map. #140
• Fix attribute name for empty prefix in Attr (native DOM). This should fix #142.

0.86.0 – Go in chunks

Features:

• Preliminary (partial) support for chunked decoding/Chunked Decoder ()
• Use kotlinx.serialization 1.5.0
• The default policy now ignores all attributes in the xml namespace when
  found missing (it will not throw an exception). If explicitly declared
  they will still be handled.
• Implement a FileReader and FileWriter (and streams) for native to allow
  native writing of files.
• Update to Kotlin 1.8.21
• Deprecate the ktor module (in favour of ktor's own xml integration module).
  Note that that module still uses xmlutil, it just provides its own xml access
  code.

Fixes:

• Various high range unicode characters (and modifiers) were incorrectly seen
  as invalid values (relevant for emoji's)
• Still allow for explicit xml:space properties (while also handling them
  automatically).
• Update ChildCollector to use the correct/updated signature for
  polymorhpicDefaultDeserializer. "Fixes" #126 (the underlying issues are
  KT-55318
  and KT-56602)
• Support document fragments in DomReader
• Make the StAXReader not skip the StartDocument event initially.
• Make XmlBufferedReader.nextTagEvent process/ignore StartDocument.
• Made ignorable whitespace more consistent. #128
• Fix handling of isCollectingNSAttributes (#135). This will now properly
  handle sealed polymorphism as well as deal properly with the default
  namespace: properties without prefix will not register the null namespace.
  If the default namespace is used anywhere, this ensures that prefixes are
  used otherwise. This will avoid all occurences of xmlns="" (and
  xmlns:prefix="")
• Fix DomReader's handling of non-namespace aware elements/nodes that return
  null as localName.
• In DomReader handle the fact that JVM's xpath creates xmlns declarations for
  xmlns.
• Fix unsigned serialization of value classes.

0.85.0 – Tying things up

Features:

• Implement serialization of maps. The outer container will be eluded as with lists. If the key type can be an attribute (and doesn't overlap with an attribute in the value) it will be written on the value, otherwise an entry will be written with the key written on it (as attribute or tag). Note that as this point keys must precede values due to the implementation of map serialization. The behaviour can be customized through the policy.
• Add the possibility to specify namespace declarations that are ensured on tags (note that this does not yet participate in the namespace collating code)
• Fix polymorphic usage of value classes as children of a sealed interface.
• Add a defaultPolicy configurator to XmlConfig.Builder that allows more elegant configuration of the default policy. Some of the properties that can be specified on the XmlConfig.Builder have been deprecated in place of this new (more robust) mechanism.
• Within the default policy builder add support for configuring the unknown child handling with some defaults: ignoreUnknownChildren and ignoreUnknownNamespace. Note that these are shortcuts to setting an explicit handler.
• Now when a tag is marked to not preserve space (preserving is the default), but when the value starts or ends with whitespace this will result the xml:space="preserve" attribute to be emitted. The decoder will also honour this attribute over default behaviour for that type.
• Support custom delimiters by allowing a list of delimiters to be specified the policy.

Fixes:

• Make actual serialization of maps (that are not attributes) work
• Fix an infinite recursion bug in the namespace collection code that writes namespace declarations on the top level.
• Fix writing codepoints > 0x10000 that require surrogate pairs.
• Fix whitespace handling #120
• Remove stale logging code: #119

0.84.3 – Tidy things up

Features:

• Add the ability to have polymorphic root tags (#98). Note that for
  a non-transparent approach it is strongly advised to explicitly
  provide the tagname polymorphic types do not support annotations on
  the type.

Fixes:

• Fix reading of entity references. #88
• Fix NamedNodeMap iterator (an issue for dom based apis)
• Support Kotlin 1.7.10
• Fix namespaceholder's getPrefix to not offer overridden prefixes. This
  addresses #99.
• Dom getLocalName may return null for some implementations (where there is no
  namespace).
• Fix empty namespace handling for dom namespace attributes
• In DOMReader make sure that namespace declaration attributes are not exposed
  as double (as attribute and nsDecl) events.

0.84.2 – Keep it going

Features:

• Add @XmlIgnoreWhitespace annotation to allow not retaining whitespace with
  an @XmlValue field of type List<CompactFragment>

Fixes:

• Fix storing comment events
• Don't defer serializing inline values as that is not valid. This
  also addresses a potential similar issue when reordering.
• When deserializing element content to a List<CompactFragment> retain
  ignorable whitespace.
• Fix the StringReader implementation for native (an issue with parsing from
  strings over 8192 characters long). #86.

0.84.1 – Just a bit better

Features:

• Enable NodeSerializer and ElementSerializer on all platforms. Note that for
  JS it is not registered in the context due to technical limitations.

Fixes:

• Fix handling of whitespace text (#84)
• Fix compilation on native with 1.6.20 (#85) and a general infinite loop bug
  when retrieving doctype on a document in native.

0.84.0 – All the small features

0.84.0

(Jan 11, 2022)

Features:

• Support (de)serializing anyElement content into a list of CompactFragments if
  annotated with @XmlValue. Each element will be deserialized individually,
  text is not allowed. While order is preserved, declared children will be parsed
  out of order.
• Support DOM on all platforms. This includes a minimal implementation for native
  but delegating to the jvm/js implementations on those platforms (to allow
  consistency). Note that this doesn't independently support DOM on nodejs

Fixes:

• Fix native parser for depth>=4
• Improve handling of attribute prefixes and namepaces to be standard compliant
• Fix execution of native tests (not user visible)
• Fix module names (due to variable name clash in build script). Thanks to
  @rsinukov in pull request #79

0.84.0-RC1

(Nov 3, 2021)

Features:

• Add @XmlCData annotation to force serialization as CData for a type (#71)
• Allow compact fragments to be used transparently in conjunction with the
  @XmlValue annotation (it requires use of the CompactFragmentSerializer).
• Add XmlBufferReader as a reader of lists of events (the counterpoint to
  @XmlBufferedWriter)
• Support serializing lists of primitives (or inlines of primitives, or qnames).
  This is derived from the xml schema standard (and needed for xml schema).
• Support storing unknown attributes in a Map<QName, String>
  (Using [QNameSerializer] or contextual). The field needs to be annotated with
  @XmlOtherAttributes. (Technically other types than QName and String are
  supported, but only if all values will be able to read from that string value)
• add methods on [XmlInput] and [XmlOutput] to allow custom serializers the
  ability to ensure a prefix is registered/look it up.
• Support using the xml schema instance namespace type attribute as type
  discriminator for all reading, and an type discriminator attribute mode
  specified by the policy. This uses the QName for the type (using existing
  mechanisms), but amended to map kotlin primitive names to XMLSchema types.
  Note that this mechanism is only for polymorphic serialization, no
  substitution happens outside the polymorphic case (the same way that
  substitution) needs to be declared in XMLschema.
• Support using XMLSchema instance nil attributes (or a user configured
  alternative). The nil attribute is recognized unconditionally, but only
  written if specified.
• Explicitly expose the platform independent writer (KtXmlWriter), it has been
  moved out of the implementation package, and can also be created by the
  XmlStreaming object (using newGenericWriter). Serialization can use this
  writer to have more predictable outputs.
• Create (based upon kxml2) a platform independent parser (KtXmlReader) in line
  with the writer.
• Support generating xml in either version 1.0 or 1.1 (with the platform
  independent writer)

Fixes:

• Update to kotlinx.serialization-1.3.0-RC
• Fix/change XmlReader.namespaceDecls (make it a member, not an extension)
• Fix compact fragments that redeclare the default namespace
• Fix deserialization of empty types where decodeElementIndex is never called
  (this applies for object)
• Fix XmlBufferedReader's use of it's own namespace context and initializing
  it properly for the initial event (adding all visible namespaces).

0.84.0-rc1 – Just checking - a grab bag of goodies

Various changes. Released as release candidate as many changes (including native support) may have unforeseen issues. It should be stable though.

Features:

• Add @XmlCData annotation to force serialization as CData for a type (#71)
• Allow compact fragments to be used transparently in conjunction with the
  @XmlValue annotation (it requires use of the CompactFragmentSerializer).
• Add XmlBufferReader as a reader of lists of events (the counterpoint to
  @XmlBufferedWriter)
• Support serializing lists of primitives (or inlines of primitives, or qnames).
  This is derived from the xml schema standard (and needed for xml schema).
• Support storing unknown attributes in a Map<QName, String>
  (Using [QNameSerializer] or contextual). The field needs to be annotated with
  @XmlOtherAttributes. (Technically other types than QName and String are
  supported, but only if all values will be able to read from that string value)
• add methods on [XmlInput] and [XmlOutput] to allow custom serializers the
  ability to ensure a prefix is registered/look it up.
• Support using the xml schema instance namespace type attribute as type
  discriminator for all reading, and an type discriminator attribute mode
  specified by the policy. This uses the QName for the type (using existing
  mechanisms), but amended to map kotlin primitive names to XMLSchema types.
  Note that this mechanism is only for polymorphic serialization, no
  substitution happens outside the polymorphic case (the same way that
  substitution) needs to be declared in XMLschema.
• Support using XMLSchema instance nil attributes (or a user configured
  alternative). The nil attribute is recognized unconditionally, but only
  written if specified.
• Explicitly expose the platform independent writer (KtXmlWriter), it has been
  moved out of the implementation package, and can also be created by the
  XmlStreaming object (using newGenericWriter). Serialization can use this
  writer to have more predictable outputs.
• Create (based upon kxml2) a platform independent parser (KtXmlReader) in line
  with the writer.
• Support generating xml in either version 1.0 or 1.1 (with the platform
  independent writer)

Fixes:

• Update to kotlinx.serialization-1.3.0-RC
• Fix/change XmlReader.namespaceDecls (make it a member, not an extension)
• Fix compact fragments that redeclare the default namespace
• Fix deserialization of empty types where decodeElementIndex is never called
  (this applies for object)
• Fix XmlBufferedReader's use of it's own namespace context and initializing
  it properly for the initial event (adding all visible namespaces).

0.83.0 – Changes, here we come

Features:

• There is a ktor module available that makes xml available at server level
• Support for determine the order of items/reordering:
  • This can be configured by the policy.
  • The default policy works using: @XmlBefore and @XmlAfter to specify
    order relationships. There is an update to the policy API where an
    additional parameter determines whether the child can be an attribute.
  • Ordering is two-phase, the initial phase is done before determining the
    output kind. The second phase reorders after the output kind of a child is
    determined and can override the attributes (attributes are always before
    element children).
• The policy can now be used to determine the string used to represent an enum
  constant (by default the name of the enum element)
• Provide a serializer for QName instances. This serializer is available in
  the default context and special cased to handle prefixes correctly. There are
  many related fixes to the namespace code in the core module.
• Allow the policy to override the serializer/deserializer used for a specific
  child.
• Add an option to XmlConfig (isCollectingNSAttributes) that allows namespace
  attributes to be serialized on the root tag.
• There is now a KtXmlWriter multiplatform class that replaces then android
  default xml writer (it merges the wrapper with an adapted form of Android's
  XmlSerializer). This serializer is available on all targets.
• There is a lot of cleanup of the APIs, especially in the core module.
• Allow explicitly specifying the root tag name for serialization
• Mostly support default annotation values. Please note that at this time there
  is still some issue with the JVM IR compiler with the default values (code
  will not generate correctly). However the defaults are available and have been
  tested where relevant.

Fixes:

• Don't elide lists if the serialized content is a list (xml documents must have
  a single root tag)
• Support @XmlValue(false) correcty
• Support Kotlin 1.5 and kotlinx.serialization-1.2.2
• Allow DomSource to work on for a stax parser (by using a string intermediate)
• Fix generating namespace prefixes when missing
• Per the standard attributes without prefix are always in the default (empty)
  namespace, handle this correctly.
• Give the CharArrayAsString serializer a different name as the new library
  doesn't like overlapping names (and there already is a standard chararray
  serializer).

0.82.0 – Progress it is

This release supports kotlin 1.5.0 and kotlinx.serialization 1.2.0

Key changes are:

• Add xmlDescriptors to XML to provide access to the serialization structure (as also used for serialization). This can be used for writing schemas (but to change it you will have to implement your own policy)
• Fix bug #44
• serialNameToQname is split into two separate functions separating the policy for when the name is declared on the attribute or on the type. This in response to #50
• Mark various deprecated API elements as errors. They will be removed soon (the plan for release 0.90 is to tidy things up)
• Create a module for use in ktor that allows for xml serialization in ktor. This differs from the json/generic version in that it uses its own streamconverter and can serialize directly from/to streams without a string intermediate (this should also support xml based encoding specification).