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.

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.OutputStream out, java.lang.String enc)
Constuctor uses given OutputStream for output and allows encoding to be set.

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

Method Summary

protected void	bodyText(WriteContext context, java.lang.String text) Write element body text
void	close() Closes the underlying output stream
void	enablePrettyPrint() Switch on formatted output.
protected void	endElement(WriteContext context, java.lang.String uri, java.lang.String localName, java.lang.String qualifiedName) Writes the end tag for an element
protected java.lang.String	escapeAttributeValue(java.lang.Object value) Deprecated. 0.5 moved into utility class XMLUtils.escapeAttributeValue(java.lang.Object)
protected java.lang.String	escapeBodyValue(java.lang.Object value) Deprecated. 0.5 moved into utility class XMLUtils.escapeBodyValue(java.lang.Object)
protected void	expressAttribute(java.lang.String qualifiedName, java.lang.String value) Deprecated. 0.5 replaced by new SAX inspired API
protected void	expressBodyText(java.lang.String text) Deprecated. 0.5 replaced by new SAX inspired API
protected void	expressElementEnd() Deprecated. 0.5 replaced by new SAX inspired API
protected void	expressElementEnd(java.lang.String qualifiedName) Deprecated. 0.5 replaced by new SAX inspired API
protected void	expressElementStart(java.lang.String qualifiedName) Deprecated. 0.5 replaced by new SAX inspired API
protected void	expressTagClose() Deprecated. 0.5 replaced by new SAX inspired API
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
int	getInitialIndentLevel() Gets the initial indent level
org.apache.commons.logging.Log	getLog() Set the log implementation used.
MixedContentEncodingStrategy	getMixedContentEncodingStrategy() Gets the encoding strategy for mixed content.
boolean	isEndTagForEmptyElement() Should an end tag be added for each empty element?
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	setEndTagForEmptyElement(boolean addEndTagForEmptyElement) Sets when an an end tag be added for each empty element.
void	setIndent(java.lang.String indent) Sets the string used for pretty print indents
void	setInitialIndentLevel(int initialIndentLevel) Sets the initial indent level used for pretty print indents
void	setLog(org.apache.commons.logging.Log log) Set the log implementation used.
void	setMixedContentEncodingStrategy(MixedContentEncodingStrategy strategy) Sets the encoding strategy for mixed content.
protected void	startElement(WriteContext context, java.lang.String uri, java.lang.String localName, java.lang.String qualifiedName, org.xml.sax.Attributes attr) Writes the start tag for an element.
void	write(java.lang.Object bean) Write the given object to the stream (and then flush).
protected void	writeIndent() Deprecated. 0.5 replaced by new SAX inspired API
protected void	writePrintln() Deprecated. 0.5 replaced by new SAX inspired API
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

bodyText, end, endElement, expressAttribute, expressElementEnd, expressElementStart, getAbstractBeanWriterLog, getBindingConfiguration, getIdGenerator, getIndentLevel, getWriteEmptyElements, getWriteIDs, getXMLIntrospector, popBean, pushBean, setAbstractBeanWriterLog, setBindingConfiguration, setIdGenerator, setWriteEmptyElements, setWriteIDs, setXMLIntrospector, start, startElement, write, 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.OutputStream out,
                  java.lang.String enc)
           throws java.io.UnsupportedEncodingException

Constuctor uses given OutputStream for output and allows encoding to be set.

Parameters:

out - write out representations to this stream

enc - the name of the encoding to be used. This should be compatible with the encoding types described in java.io

Throws:

java.io.UnsupportedEncodingException - if the given encoding is not supported

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

getInitialIndentLevel

public int getInitialIndentLevel()

Gets the initial indent level

Returns:

the initial level for indentation

Since:

0.8

setInitialIndentLevel

public void setInitialIndentLevel(int initialIndentLevel)

Sets the initial indent level used for pretty print indents

Parameters:

initialIndentLevel - use this int to start with

Since:

0.8

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

getMixedContentEncodingStrategy

public MixedContentEncodingStrategy getMixedContentEncodingStrategy()

Gets the encoding strategy for mixed content. This is used to process body content before it is written to the textual output.

Returns:

the MixedContentEncodingStrategy, not null

Since:

0.5

setMixedContentEncodingStrategy

public void setMixedContentEncodingStrategy(MixedContentEncodingStrategy strategy)

Sets the encoding strategy for mixed content. This is used to process body content before it is written to the textual output.

Parameters:

strategy - the MixedContentEncodingStrategy used to process body content, not null

Since:

0.5

isEndTagForEmptyElement

public boolean isEndTagForEmptyElement()

Should an end tag be added for each empty element?

When this property is false then empty elements will be written as <element-name/gt;. When this property is true then empty elements will be written as <element-namegt; </element-namegt;.

Returns:

true if an end tag should be added

setEndTagForEmptyElement

public void setEndTagForEmptyElement(boolean addEndTagForEmptyElement)

Sets when an an end tag be added for each empty element. When this property is false then empty elements will be written as <element-name/gt;. When this property is true then empty elements will be written as <element-namegt; </element-namegt;.

Parameters:

addEndTagForEmptyElement - true if an end tag should be written for each empty element, false otherwise

startElement

protected void startElement(WriteContext context,
                            java.lang.String uri,
                            java.lang.String localName,
                            java.lang.String qualifiedName,
                            org.xml.sax.Attributes attr)
                     throws java.io.IOException,
                            org.xml.sax.SAXException

Writes the start tag for an element.

Overrides:

startElement in class AbstractBeanWriter

Parameters:

uri - the element's namespace uri

localName - the element's local name

qualifiedName - the element's qualified name

attr - the element's attributes

Throws:

java.io.IOException - if an IO problem occurs during writing

org.xml.sax.SAXException - if an SAX problem occurs during writing

Since:

0.5

endElement

protected void endElement(WriteContext context,
                          java.lang.String uri,
                          java.lang.String localName,
                          java.lang.String qualifiedName)
                   throws java.io.IOException,
                          org.xml.sax.SAXException

Writes the end tag for an element

Overrides:

endElement in class AbstractBeanWriter

Parameters:

uri - the element's namespace uri

localName - the element's local name

qualifiedName - the element's qualified name

Throws:

java.io.IOException - if an IO problem occurs during writing

org.xml.sax.SAXException - if an SAX problem occurs during writing

Since:

0.5

bodyText

protected void bodyText(WriteContext context,
                        java.lang.String text)
                 throws java.io.IOException

Write element body text

Overrides:

bodyText in class AbstractBeanWriter

Parameters:

text - write out this body text

Throws:

java.io.IOException - when the stream write fails

Since:

0.5

writePrintln

protected void writePrintln()
                     throws java.io.IOException

Deprecated. 0.5 replaced by new SAX inspired API

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

Deprecated. 0.5 replaced by new SAX inspired API

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)

Deprecated. 0.5 moved into utility class XMLUtils.escapeBodyValue(java.lang.Object)

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)

Deprecated. 0.5 moved into utility class XMLUtils.escapeAttributeValue(java.lang.Object)

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

expressElementStart

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

Deprecated. 0.5 replaced by new SAX inspired API

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

Deprecated. 0.5 replaced by new SAX inspired API

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

Deprecated. 0.5 replaced by new SAX inspired API

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

Deprecated. 0.5 replaced by new SAX inspired API

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

Deprecated. 0.5 replaced by new SAX inspired API

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

Deprecated. 0.5 replaced by new SAX inspired API

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