org.apache.commons.betwixt.io
Class BeanWriter

java.lang.Object
  |
  +--org.apache.commons.betwixt.io.AbstractBeanWriter
        |
        +--org.apache.commons.betwixt.io.BeanWriter

public class BeanWriter

extends AbstractBeanWriter

BeanWriter outputs beans as XML to an io stream.

The output for each bean is an xml fragment (rather than a well-formed xml-document). This allows bean representations to be appended to a document by writing each in turn to the stream. So to create a well formed xml document, you'll need to write the prolog to the stream first. If you append more than one bean to the stream, then you'll need to add a wrapping root element as well.

The line ending to be used is set by setEndOfLine(java.lang.String).

The output can be formatted (with whitespace) for easy reading by calling enablePrettyPrint(). The output will be indented. The indent string used is set by setIndent(java.lang.String).

Bean graphs can sometimes contain cycles. Care must be taken when serializing cyclic bean graphs since this can lead to infinite recursion. The approach taken by BeanWriter is to automatically assign an ID attribute value to beans. When a cycle is encountered, an element is written that has the IDREF attribute set to the id assigned earlier.

The names of the ID and IDREF attributes used can be customized by the XMLBeanInfo. The id's used can also be customized by the user via IDGenerator subclasses. The implementation used can be set by the IdGenerator property. BeanWriter defaults to using SequentialIDGenerator which supplies id values in numeric sequence.

If generated ID attribute values are not acceptable in the output, then this can be disabled by setting the WriteIDs property to false. If a cyclic reference is encountered in this case then a CyclicReferenceException will be thrown. When the WriteIDs property is set to false, it is recommended that this exception is caught by the caller.

Version:

$Revision: 1.13 $

Author:

James Strachan, Martin van den Bemt

Constructor Summary

BeanWriter()
Constructor uses System.out for output.

BeanWriter(java.io.OutputStream out)
Constuctor uses given OutputStream for output.

BeanWriter(java.io.Writer writer)
Constructor sets writer used for output.

Method Summary

void	close() Closes the underlying output stream
void	enablePrettyPrint() Switch on formatted output.
protected java.lang.String	escapeAttributeValue(java.lang.Object value) Escape the toString of the given object.
protected java.lang.String	escapeBodyValue(java.lang.Object value) Escape the toString of the given object.
protected void	expressAttribute(java.lang.String qualifiedName, java.lang.String value) Writes an attribute to the stream.
protected void	expressBodyText(java.lang.String text) Write element body text
protected void	expressElementEnd() Write an empty element end to the stream
protected void	expressElementEnd(java.lang.String qualifiedName) Write an element end tag to the stream
protected void	expressElementStart(java.lang.String qualifiedName) Express an element tag start using given qualified name
protected void	expressTagClose() Write a tag close to the stream
void	flush() Allows output to be flushed on the underlying output stream
java.lang.String	getEndOfLine() Gets the string used to mark end of lines.
java.lang.String	getIndent() Gets the indent string
org.apache.commons.logging.Log	getLog() Set the log implementation used.
void	setEndOfLine(java.lang.String endOfLine) Sets the string used for end of lines Produces a warning the specified value contains an invalid whitespace character
void	setIndent(java.lang.String indent) Sets the string used for pretty print indents
void	setLog(org.apache.commons.logging.Log log) Set the log implementation used.
void	write(java.lang.Object bean) Write the given object to the stream (and then flush).
protected void	writeIndent() Writes out indent's to the current indentLevel
protected void	writePrintln() Writes out an empty line.
void	writeXmlDeclaration(java.lang.String xmlDeclaration) A helper method that allows you to write the XML Declaration.

Methods inherited from class org.apache.commons.betwixt.io.AbstractBeanWriter

end, getAbstractBeanWriterLog, getIdGenerator, getIndentLevel, getWriteIDs, getXMLIntrospector, popBean, pushBean, setAbstractBeanWriterLog, setIdGenerator, setWriteIDs, setXMLIntrospector, start, write, write, write, writeAttribute, writeAttributes, writeContent, writeIDREFElement, writeRestOfElement

Methods inherited from class java.lang.Object

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

Constructor Detail

BeanWriter

public BeanWriter()

Constructor uses System.out for output.

BeanWriter

public BeanWriter(java.io.OutputStream out)

Constuctor uses given OutputStream for output.

Parameters:

out - write out representations to this stream

BeanWriter

public BeanWriter(java.io.Writer writer)

Constructor sets writer used for output.

Parameters:

writer - write out representations to this writer

Method Detail

writeXmlDeclaration

public void writeXmlDeclaration(java.lang.String xmlDeclaration)
                         throws java.io.IOException

A helper method that allows you to write the XML Declaration. This should only be called once before you output any beans.

Parameters:

xmlDeclaration - is the XML declaration string typically of the form "<xml version='1.0' encoding='UTF-8' ?>

Throws:

java.io.IOException - when declaration cannot be written

flush

public void flush()
           throws java.io.IOException

Allows output to be flushed on the underlying output stream

Throws:

java.io.IOException - when the flush cannot be completed

close

public void close()
           throws java.io.IOException

Closes the underlying output stream

Throws:

java.io.IOException - when writer cannot be closed

write

public void write(java.lang.Object bean)
           throws java.io.IOException,
                  org.xml.sax.SAXException,
                  java.beans.IntrospectionException

Write the given object to the stream (and then flush).

Overrides:

write in class AbstractBeanWriter

Parameters:

bean - write this Object to the stream

Throws:

java.io.IOException - if an IO problem causes failure

org.xml.sax.SAXException - if a SAX problem causes failure

java.beans.IntrospectionException - if bean cannot be introspected

enablePrettyPrint

public void enablePrettyPrint()

Switch on formatted output. This sets the end of line and the indent. The default is adding 2 spaces and a newline

getEndOfLine

public java.lang.String getEndOfLine()

Gets the string used to mark end of lines.

Returns:

the string used for end of lines

setEndOfLine

public void setEndOfLine(java.lang.String endOfLine)

Sets the string used for end of lines Produces a warning the specified value contains an invalid whitespace character

Parameters:

endOfLine - the String

getIndent

public java.lang.String getIndent()

Gets the indent string

Returns:

the string used for indentation

setIndent

public void setIndent(java.lang.String indent)

Sets the string used for pretty print indents

Parameters:

indent - use this string for indents

getLog

public org.apache.commons.logging.Log getLog()

Set the log implementation used.

Returns:

a org.apache.commons.logging.Log level constant

setLog

public void setLog(org.apache.commons.logging.Log log)

Set the log implementation used.

Parameters:

log - Log implementation to use

expressElementStart

protected void expressElementStart(java.lang.String qualifiedName)
                            throws java.io.IOException

Express an element tag start using given qualified name

Overrides:

expressElementStart in class AbstractBeanWriter

Parameters:

qualifiedName - the fully qualified name of the element to write

Throws:

java.io.IOException - when stream write fails

expressTagClose

protected void expressTagClose()
                        throws java.io.IOException

Write a tag close to the stream

Overrides:

expressTagClose in class AbstractBeanWriter

Throws:

java.io.IOException - when stream write fails

expressElementEnd

protected void expressElementEnd(java.lang.String qualifiedName)
                          throws java.io.IOException

Write an element end tag to the stream

Overrides:

expressElementEnd in class AbstractBeanWriter

Parameters:

qualifiedName - the name of the element

Throws:

java.io.IOException - when stream write fails

expressElementEnd

protected void expressElementEnd()
                          throws java.io.IOException

Write an empty element end to the stream

Overrides:

expressElementEnd in class AbstractBeanWriter

Throws:

java.io.IOException - when stream write fails

expressBodyText

protected void expressBodyText(java.lang.String text)
                        throws java.io.IOException

Write element body text

Overrides:

expressBodyText in class AbstractBeanWriter

Parameters:

text - write out this body text

Throws:

java.io.IOException - when the stream write fails

expressAttribute

protected void expressAttribute(java.lang.String qualifiedName,
                                java.lang.String value)
                         throws java.io.IOException

Writes an attribute to the stream.

Overrides:

expressAttribute in class AbstractBeanWriter

Parameters:

qualifiedName - fully qualified attribute name

value - attribute value

Throws:

java.io.IOException - when the stream write fails

writePrintln

protected void writePrintln()
                     throws java.io.IOException

Writes out an empty line. Uses current endOfLine.

Overrides:

writePrintln in class AbstractBeanWriter

Throws:

java.io.IOException - when stream write fails

writeIndent

protected void writeIndent()
                    throws java.io.IOException

Writes out indent's to the current indentLevel

Overrides:

writeIndent in class AbstractBeanWriter

Throws:

java.io.IOException - when stream write fails

escapeBodyValue

protected java.lang.String escapeBodyValue(java.lang.Object value)

Escape the toString of the given object. For use as body text.

Parameters:

value - escape value.toString()

Returns:

text with escaped delimiters

escapeAttributeValue

protected java.lang.String escapeAttributeValue(java.lang.Object value)

Escape the toString of the given object. For use in an attribute value.

Parameters:

value - escape value.toString()

Returns:

text with characters restricted (for use in attributes) escaped