Scales Xml delegates as much serializing as possible to the DOML3 LSSerializer framework. There are a number of pain points, due to incompatibilities between jaxp implementations and jvm versions, that Scales smoothes out for the developer.
The main aims with Scales serialisation are:
The unified interface is one main function:
def serialize[T: SerializeableXml](pout: XmlOutput)(it: T) : Option[Throwable]
All XML types that can be serialized provide a SerializeableXml type class instance and the user supplies the XmlOutput object. The users main interaction is through the SerializerData object allowing users to supply the output java.io.Writer and override both the encoding and xml version used.
Typically one of the following functions will be used:
The first two (writeTo) are the most general and the later three useful for debugging.
No SerializeableXml type class instances are defined for XmlPaths as they can be either an XmlItem or Tree. As such itemAsString exists for those times you really want to debug just the XmlItem.
In all cases the xml is written out using the serialize function, which always writes out the xml declaration with the pout : XmlOutput parameter. The more general writeTo approach will take the documents declaration unless specifically overridden.
The writeTo function:
def writeTo[T](it: T, output: Writer,
version: Option[XmlVersion] = None, encoding: Option[Charset] = None)
(implicit serializerFI: SerializerFactory, sxml: SerializeableXml[T])
: Option[Throwable]
requires two parameters, the item to be serialized and the output Writer. When the remaining two parameters are None (or simply left as default) the encoding and xml version are taken from the items document.
To make life easier in the common case the WriteTo class (and implicits from ScalaXml._) allows a simpler:
val testXml = loadXml(...) val str = asString(testXml) val out = new java.io.StringWriter() testXml writeTo out assertEquals(str, out.toString)
The following types can be serialized:
With the itemAsString allowing simple debug output.
If an object can be meaningfully written as Xml it is suggested to wrap streamSerializeable directly, converting your object into a stream as required. See here for code examples (e.g. pullOnlySerializable).