nux.xom.io
Class StreamingSerializerFactory

java.lang.Object
  nux.xom.io.StreamingSerializerFactory

public class StreamingSerializerFactory
extends Object

Factory creating instances of StreamingSerializer implementations.

Currently there are three implementations. One writes a standard textual XML document via a thin layer on top of the normal XOM Serializer. Another writes a bnux binary XML document via a BinaryXMLCodec. Yet another delegates to an underlying StAX XMLStreamWriter. Future releases may include implementations that delegate to SAX and DOM.

Author:

whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Constructor Summary

StreamingSerializerFactory()
Constructs a new factory instance; The serializer instances it creates can be reused serially, but are not thread safe.

Method Summary

StreamingSerializer	createBinaryXMLSerializer(OutputStream out, int zlibCompressionLevel) Returns a new streaming serializer that writes bnux binary XML to the given underlying output stream, using the given ZLIB compression level.
StreamingSerializer	createStaxSerializer(XMLStreamWriter writer) Returns a new streaming serializer that writes standard textual XML to the given underlying StAX XMLStreamWriter.
StreamingSerializer	createXMLSerializer(OutputStream out, String encoding) Returns a new streaming serializer that writes standard textual XML to the given underlying output stream, using the given character encoding for char to byte conversions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StreamingSerializerFactory

public StreamingSerializerFactory()

Constructs a new factory instance; The serializer instances it creates can be reused serially, but are not thread safe.

Method Detail

createBinaryXMLSerializer

public StreamingSerializer createBinaryXMLSerializer(OutputStream out,
                                                     int zlibCompressionLevel)

Returns a new streaming serializer that writes bnux binary XML to the given underlying output stream, using the given ZLIB compression level.

An optional zlib compression level ranging from 0 (no ZLIB compression; best performance) to 1 (little ZLIB compression; reduced performance) to 9 (strongest ZLIB compression; worst performance) allows one to configure the CPU/memory consumption trade-off.

Unless there is a good reason to the contrary, you should always use level 0: the bnux algorithm typically already precompresses considerably.

Parameters:

out - the underlying output stream to write to

zlibCompressionLevel - a number in the range 0..9

Returns:

a streaming serializer that writes bnux binary XML

createXMLSerializer

public StreamingSerializer createXMLSerializer(OutputStream out,
                                               String encoding)

Returns a new streaming serializer that writes standard textual XML to the given underlying output stream, using the given character encoding for char to byte conversions.

The standard XOM Serializer options are used, in particular Serializer.setIndent(int) with argument zero, i.e. no extra indentation.

Parameters:

out - the underlying stream to write to

encoding - the character encoding to use (e.g. "UTF-8")

Returns:

a new streaming serializer

See Also:

Serializer.Serializer(OutputStream, String)

createStaxSerializer

public StreamingSerializer createStaxSerializer(XMLStreamWriter writer)

Returns a new streaming serializer that writes standard textual XML to the given underlying StAX XMLStreamWriter.

In theory, any StAX implementation will work, but in practise Woodstox is the only StAX implementation known to be exceptionally conformant, reliable, complete and efficient.

The returned instance auto-suppresses redundant namespace declarations irrespective of the underlying StAX implementation. Consequently, XML output will be identical irrespective of the XMLStreamWriter's namespace repairing mode and javax.xml.stream.isPrefixDefaulting mode. In other words, there's no need for a user to specify these modes, and there's no need to change the default settings of the underlying StAX implementation. The returned StreamingSerializer "does the right thing" no matter what.

Parameters:

writer - the underlying StAX XMLStreamWriter to write to

Returns:

a new streaming serializer

See Also:

XMLOutputFactory