javolution.xml

Class XMLObjectWriter

java.lang.Object

javolution.xml.XMLObjectWriter

public class XMLObjectWriter
extends Object

This class takes an object and formats it to XML; the resulting XML can be deserialized using a XMLObjectReader.

When an object is formatted, the XMLFormat of the object's class as identified by the XMLBinding is used to write its XML representation.

Multiple objects can be written to the same XML output. For example:

     XMLObjectWriter writer = XMLObjectWriter.newInstance(outputStream);
     while (true)) {
         Message message = ...
         writer.write(message, "Message", Message.class);
     }
     writer.close(); // The underlying stream is closed.
     

Version:

4.0, September 4, 2006

Author:

Jean-Marie Dautelle

Constructor Summary

Constructors

Constructor and Description
XMLObjectWriter() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Ends document writting, closes this writer and its underlying output then reset this Writer for potential reuse.
void	flush() Flushes the output stream of this writer (automatically done when closing).
XMLStreamWriter	getStreamWriter() Returns the stream writer used by this object writer (it can be used to write prolog, write namespaces, etc).
static XMLObjectWriter	newInstance(OutputStream out) Returns a XML object writer (potentially recycled) having the specified output stream as output.
static XMLObjectWriter	newInstance(OutputStream out, String encoding) Returns a XML object writer (potentially recycled) having the specified output stream/encoding as output.
static XMLObjectWriter	newInstance(Writer out) Returns a XML object writer (potentially recycled) having the specified writer as output.
void	reset() Resets this object writer for reuse.
XMLObjectWriter	setBinding(XMLBinding binding) Sets the XML binding to use with this object writer.
XMLObjectWriter	setIndentation(String indentation) Sets the indentation to be used by this writer (no indentation by default).
XMLObjectWriter	setOutput(OutputStream out) Sets the output stream for this XML object writer.
XMLObjectWriter	setOutput(OutputStream out, String encoding) Sets the output stream and encoding for this XML object writer.
XMLObjectWriter	setOutput(Writer out) Sets the output writer for this XML object writer.
XMLObjectWriter	setReferenceResolver(XMLReferenceResolver referenceResolver) Sets the XML reference resolver to use with this object writer (the same reference resolver can be used accross multiple writers).
void	write(Object obj) Writes the specified object as an anonymous nested element of unknown type.
void	write(Object obj, String name) Writes the specified object as a named nested element of unknown type (null objects are ignored).
void	write(Object obj, String localName, String uri) Writes the specified object as a fully qualified nested element of unknown type (null objects are ignored).
<T> void	write(T obj, String name, Class<T> cls) Writes the specified object as a named nested element of actual type known (null objects are ignored).
<T> void	write(T obj, String localName, String uri, Class<T> cls) Writes the specified object as a fully qualified nested element of actual type known (null objects are ignored).

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLObjectWriter

public XMLObjectWriter()

Default constructor.

Method Detail

newInstance

public static XMLObjectWriter newInstance(OutputStream out)
                                   throws XMLStreamException

Returns a XML object writer (potentially recycled) having the specified output stream as output.

Parameters:

out - the output stream.

Throws:

XMLStreamException

newInstance

public static XMLObjectWriter newInstance(OutputStream out,
                          String encoding)
                                   throws XMLStreamException

Returns a XML object writer (potentially recycled) having the specified output stream/encoding as output.

Parameters:

out - the output stream.

encoding - the output stream encoding.

Throws:

XMLStreamException

newInstance

public static XMLObjectWriter newInstance(Writer out)
                                   throws XMLStreamException

Returns a XML object writer (potentially recycled) having the specified writer as output.

Parameters:

out - the writer output.

Throws:

XMLStreamException

getStreamWriter

public XMLStreamWriter getStreamWriter()

Returns the stream writer used by this object writer (it can be used to write prolog, write namespaces, etc). The stream writer is setup to automatically repair namespaces and to automatically output empty elements when a start element is immediately followed by matching end element.

Returns:

the stream writer.

setOutput

public XMLObjectWriter setOutput(OutputStream out)
                          throws XMLStreamException

Sets the output stream for this XML object writer.

Parameters:

out - the output stream destination.

Returns:

this

Throws:

XMLStreamException

See Also:

XMLStreamWriterImpl.setOutput(OutputStream)

setOutput

public XMLObjectWriter setOutput(OutputStream out,
                        String encoding)
                          throws XMLStreamException

Sets the output stream and encoding for this XML object writer.

Parameters:

out - the output stream destination.

encoding - the stream encoding.

Returns:

this

Throws:

XMLStreamException

See Also:

XMLStreamWriterImpl.setOutput(OutputStream, String)

setOutput

public XMLObjectWriter setOutput(Writer out)
                          throws XMLStreamException

Sets the output writer for this XML object writer.

Parameters:

out - the writer destination.

Returns:

this

Throws:

XMLStreamException

See Also:

XMLStreamWriterImpl.setOutput(Writer)

setBinding

public XMLObjectWriter setBinding(XMLBinding binding)

Sets the XML binding to use with this object writer.

Parameters:

binding - the XML binding to use.

Returns:

this

setIndentation

public XMLObjectWriter setIndentation(String indentation)

Sets the indentation to be used by this writer (no indentation by default).

Parameters:

indentation - the indentation string.

Returns:

this

setReferenceResolver

public XMLObjectWriter setReferenceResolver(XMLReferenceResolver referenceResolver)

Sets the XML reference resolver to use with this object writer (the same reference resolver can be used accross multiple writers).

Parameters:

referenceResolver - the XML reference resolver.

Returns:

this

write

public void write(Object obj)
           throws XMLStreamException

Writes the specified object as an anonymous nested element of unknown type. This result in the actual type of the object being identified by the element name.

Parameters:

obj - the object written as nested element or null.

Throws:

XMLStreamException

See Also:

XMLFormat.OutputElement.add(Object)

write

public void write(Object obj,
         String name)
           throws XMLStreamException

Writes the specified object as a named nested element of unknown type (null objects are ignored). The nested XML element may contain a class attribute identifying the object type.

Parameters:

obj - the object added as nested element or null.

name - the name of the nested element.

Throws:

XMLStreamException

See Also:

XMLFormat.OutputElement.add(Object, String)

write

public void write(Object obj,
         String localName,
         String uri)
           throws XMLStreamException

Writes the specified object as a fully qualified nested element of unknown type (null objects are ignored). The nested XML element may contain a class attribute identifying the object type.

Parameters:

obj - the object added as nested element or null.

localName - the local name of the nested element.

uri - the namespace URI of the nested element.

Throws:

XMLStreamException

See Also:

XMLFormat.OutputElement.add(Object, String, String)

write

public <T> void write(T obj,
             String name,
             Class<T> cls)
           throws XMLStreamException

Writes the specified object as a named nested element of actual type known (null objects are ignored).

Parameters:

obj - the object added as nested element or null.

name - the name of the nested element.

cls - the non-abstract class identifying the XML format to use.

Throws:

XMLStreamException

See Also:

XMLFormat.OutputElement.add(Object, String, Class)

write

public <T> void write(T obj,
             String localName,
             String uri,
             Class<T> cls)
           throws XMLStreamException

Writes the specified object as a fully qualified nested element of actual type known (null objects are ignored).

Parameters:

obj - the object added as nested element or null.

localName - the local name of the nested element.

uri - the namespace URI of the nested element.

cls - the class identifying the XML format to use.

Throws:

XMLStreamException

See Also:

XMLFormat.OutputElement.add(Object, String, String, Class)

flush

public void flush()
           throws XMLStreamException

Flushes the output stream of this writer (automatically done when closing).

Throws:

XMLStreamException

close

public void close()
           throws XMLStreamException

Ends document writting, closes this writer and its underlying output then reset this Writer for potential reuse.

Throws:

XMLStreamException

reset

public void reset()

Resets this object writer for reuse.