javolution37.javolution.xml

Class ObjectWriter<T>

java.lang.Object

javolution37.javolution.xml.ObjectWriter<T>

All Implemented Interfaces:

Reusable

public class ObjectWriter<T>
extends java.lang.Object
implements Reusable

This class takes an object and formats it to XML (SAX2 events or stream).

        ObjectWriter ow = new ObjectWriter();
        ...
        ow.write(obj, contentHandler); // SAX2 Events.
     <i>or</i> ow.write(obj, writer);         // Writer encoding.
     <i>or</i> ow.write(obj, outputStream);   // UTF-8 stream.
     <i>or</i> ow.write(obj, byteBuffer);     // UTF-8 NIO ByteBuffer.
     

Namespaces are supported and may be associated to Java packages in order to reduce the size of the xml generated (and to increase readability). For example, the following code creates an ObjectWriter using the default namespace for all org.jscience.physics.quantities.* classes and the math prefix for the org.jscience.mathematics.matrices.* classes.

        ObjectWriter ow = new ObjectWriter();
        ow.setPackagePrefix("", "org.jscience.physics.quantities");
        ow.setPackagePrefix("math", "org.jscience.mathematics.matrices");
     

Here is an example of the xml data produced by such a writer:

     <math:Matrix xmlns:j="http://javolution.org" 
                  xmlns="java:org.jscience.physics.quantities"
                  xmlns:math="java:org.jscience.mathematics.matrices"
                  row="2" column="2">
        <Mass value="2.3" unit="mg"/>
        <Pressure value="0.2" unit="Pa"/>
        <Force value="20.0" unit="µN"/>
        <Length value="3.0" unit="ft"/>
     </math:Matrix>

For more control over the xml document generated (e.g. indentation, prolog, etc.), applications may use the write(Object, ContentHandler) method in conjonction with a custom WriterHandler. For example:

        OutputStream out = new FileOutputStream("C:/document.xml");
        Writer writer = new Utf8StreamWriter().setOuptutStream(out); // UTF-8 encoding.
        WriterHandler handler = new WriterHandler().setWriter(writer);
        handler.setIndent("\t"); // Indents with tabs.
        handler.setProlog("<?xml version=\"1.0\" encoding=\"UTF-8\"/>");
        ...
        ow.write(obj, handler);

Constructor Summary

Constructors

Constructor and Description
ObjectWriter() Default constructor.

Method Summary

Modifier and Type	Method and Description
void	reset() Resets all internal data maintained by this writer including any namespace associations; objects previously written will not be referred to, they will be send again.
void	setClassIdentifierEnabled(boolean enabled) Enables/disables class identifier attributes (default true).
void	setExpandReferences(boolean value) Controls whether or not references are expanced (default false).
void	setNamespace(java.lang.String prefix, java.lang.String uri) Sets the document namespaces for this writer.
void	setPackagePrefix(java.lang.String prefix, java.lang.String packageName) Maps a namespace to a Java package.
void	setReferencesEnabled(boolean enabled) Enables/disables xml elements cross references (default false).
void	setRootName(java.lang.String name) Sets the element name or the root object.
void	write(T obj, java.nio.ByteBuffer byteBuffer) Writes the specified object to the given byte buffer in XML format.
void	write(T obj, ContentHandler handler) Generates the SAX events corresponding to the serialization of the specified object.
void	write(T obj, java.io.OutputStream out) Writes the specified object to the given output stream in XML format.
void	write(T obj, java.io.Writer writer) Writes the specified object to the given writer in XML format.

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectWriter

public ObjectWriter()

Default constructor.

Method Detail

setNamespace

public void setNamespace(java.lang.String prefix,
                         java.lang.String uri)

Sets the document namespaces for this writer.

Parameters:

prefix - the namespace prefix or an empty sequence to set the default namespace.

uri - the namespace uri.

Throws:

java.lang.IllegalArgumentException - if the prefix is "j" (reserved for the "http://javolution.org" uri).

setPackagePrefix

public void setPackagePrefix(java.lang.String prefix,
                             java.lang.String packageName)

Maps a namespace to a Java package. The specified prefix is used to shorten the class name of the object being serialized.

Parameters:

prefix - the namespace prefix or empty sequence to set the default namespace.

packageName - of the package associated to the specified prefix.

Throws:

java.lang.IllegalArgumentException - if the prefix is "j" (reserved for the "http://javolution.org" uri).

write

public void write(T obj,
                  java.io.Writer writer)
           throws java.io.IOException

Writes the specified object to the given writer in XML format. The writer is closed after serialization. To serialize multiple objects over a persistent connection XmlOutputStream should be used instead.

Parameters:

obj - the object to format.

writer - the writer to write to.

Throws:

java.io.IOException - if there's any problem writing.

write

public void write(T obj,
                  java.io.OutputStream out)
           throws java.io.IOException

Writes the specified object to the given output stream in XML format. The characters are written using UTF-8 encoding. The output streamwriter is closed after serialization. To serialize multiple objects over a persistent connection XmlOutputStream should be used instead.

Parameters:

obj - the object to format.

out - the output stream to write to.

Throws:

java.io.IOException - if there's any problem writing.

write

public void write(T obj,
                  java.nio.ByteBuffer byteBuffer)
           throws java.io.IOException

Writes the specified object to the given byte buffer in XML format. The characters are written using UTF-8 encoding.

Parameters:

obj - the object to format.

byteBuffer - the byte buffer to write to.

Throws:

java.io.IOException - if there's any problem writing.

write

public void write(T obj,
                  ContentHandler handler)
           throws org.xml.sax.SAXException

Generates the SAX events corresponding to the serialization of the specified object.

Parameters:

obj - the object to format.

handler - the SAX event handler.

Throws:

org.xml.sax.SAXException

reset

public void reset()

Resets all internal data maintained by this writer including any namespace associations; objects previously written will not be referred to, they will be send again.

Specified by:

reset in interface Reusable

setReferencesEnabled

public void setReferencesEnabled(boolean enabled)

Enables/disables xml elements cross references (default false). When enabled, identifiers attributes are added during serialization; the name of these attributes is defined by XmlFormat.identifier(boolean).

Parameters:

enabled - true if an unique identifier attribute is added to objects being serialized; false otherwise.

setExpandReferences

public void setExpandReferences(boolean value)

Controls whether or not references are expanced (default false). References are not expanded if currently being expanded (to avoid infinite recursion).

Parameters:

value - true to expand references; false otherwise.

See Also:

XmlFormat.identifier(boolean)

setClassIdentifierEnabled

public void setClassIdentifierEnabled(boolean enabled)

Enables/disables class identifier attributes (default true). Disabling the class identifier should only be done if the serialized objects does not need to be deserialized (e.g. pure xml formatting).

Parameters:

enabled - true to allow for an additional "j:class" attribute; false otherwise.

See Also:

XmlElement.add(Object), XmlElement.add(Object, String)

setRootName

public void setRootName(java.lang.String name)

Sets the element name or the root object.

Parameters:

name - the name of the root element.