public class

BeanWriter

extends AbstractBeanWriter
java.lang.Object
   ↳ org.apache.commons.betwixt.io.AbstractBeanWriter
     ↳ org.apache.commons.betwixt.io.BeanWriter

Class Overview

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(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(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.

Summary

Public Constructors
BeanWriter()

Constructor uses System.out for output.

BeanWriter(OutputStream out)

Constuctor uses given OutputStream for output.

BeanWriter(OutputStream out, String enc)

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

BeanWriter(Writer writer)

Constructor sets writer used for output.

Public Methods
void close()
Closes the underlying output stream
void enablePrettyPrint()

Switch on formatted output.

void flush()
Allows output to be flushed on the underlying output stream
String getEndOfLine()
Gets the string used to mark end of lines.
String getIndent()
Gets the indent string
int getInitialIndentLevel()
Gets the initial indent level
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?

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

void setEndOfLine(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(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(Log log)

Set the log implementation used.

void setMixedContentEncodingStrategy(MixedContentEncodingStrategy strategy)
Sets the encoding strategy for mixed content.
void write(Object bean)
Write the given object to the stream (and then flush).
void writeXmlDeclaration(String xmlDeclaration)
A helper method that allows you to write the XML Declaration.
Protected Methods
void bodyText(WriteContext context, String text)
Write element body text
void endElement(WriteContext context, String uri, String localName, String qualifiedName)
Writes the end tag for an element
String escapeAttributeValue(Object value)
This method is deprecated. 0.5 moved into utility class escapeAttributeValue(Object)
String escapeBodyValue(Object value)
This method is deprecated. 0.5 moved into utility class escapeBodyValue(Object)
void expressAttribute(String qualifiedName, String value)
This method is deprecated. 0.5 replaced by new SAX inspired API
void expressBodyText(String text)
This method is deprecated. 0.5 replaced by new SAX inspired API
void expressElementEnd()
This method is deprecated. 0.5 replaced by new SAX inspired API
void expressElementEnd(String qualifiedName)
This method is deprecated. 0.5 replaced by new SAX inspired API
void expressElementStart(String qualifiedName)
This method is deprecated. 0.5 replaced by new SAX inspired API
void expressTagClose()
This method is deprecated. 0.5 replaced by new SAX inspired API
void startElement(WriteContext context, String uri, String localName, String qualifiedName, Attributes attr)
Writes the start tag for an element.
void writeIndent()
This method is deprecated. 0.5 replaced by new SAX inspired API
void writePrintln()
This method is deprecated. 0.5 replaced by new SAX inspired API
[Expand]
Inherited Methods
From class org.apache.commons.betwixt.io.AbstractBeanWriter
From class java.lang.Object

Public Constructors

public BeanWriter ()

Constructor uses System.out for output.

public BeanWriter (OutputStream out)

Constuctor uses given OutputStream for output.

Parameters
out write out representations to this stream

public BeanWriter (OutputStream out, String enc)

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
UnsupportedEncodingException if the given encoding is not supported

public BeanWriter (Writer writer)

Constructor sets writer used for output.

Parameters
writer write out representations to this writer

Public Methods

public void close ()

Closes the underlying output stream

Throws
IOException when writer cannot be closed

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

public void flush ()

Allows output to be flushed on the underlying output stream

Throws
IOException when the flush cannot be completed

public String getEndOfLine ()

Gets the string used to mark end of lines.

Returns
  • the string used for end of lines

public String getIndent ()

Gets the indent string

Returns
  • the string used for indentation

public int getInitialIndentLevel ()

Gets the initial indent level

Returns
  • the initial level for indentation

public Log getLog ()

Set the log implementation used.

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

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

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

public void setEndOfLine (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

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

public void setIndent (String indent)

Sets the string used for pretty print indents

Parameters
indent use this string for indents

public void setInitialIndentLevel (int initialIndentLevel)

Sets the initial indent level used for pretty print indents

Parameters
initialIndentLevel use this int to start with

public void setLog (Log log)

Set the log implementation used.

Parameters
log Log implementation to use

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

public void write (Object bean)

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

Parameters
bean write this Object to the stream
Throws
IOException if an IO problem causes failure
SAXException if a SAX problem causes failure
IntrospectionException if bean cannot be introspected

public void writeXmlDeclaration (String xmlDeclaration)

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
IOException when declaration cannot be written

Protected Methods

protected void bodyText (WriteContext context, String text)

Write element body text

Parameters
text write out this body text
Throws
IOException when the stream write fails

protected void endElement (WriteContext context, String uri, String localName, String qualifiedName)

Writes the end tag for an element

Parameters
uri the element's namespace uri
localName the element's local name
qualifiedName the element's qualified name
Throws
IOException if an IO problem occurs during writing
SAXException if an SAX problem occurs during writing

protected String escapeAttributeValue (Object value)

This method is deprecated.
0.5 moved into utility class escapeAttributeValue(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

protected String escapeBodyValue (Object value)

This method is deprecated.
0.5 moved into utility class escapeBodyValue(Object)

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

Parameters
value escape value.toString()
Returns
  • text with escaped delimiters

protected void expressAttribute (String qualifiedName, String value)

This method is deprecated.
0.5 replaced by new SAX inspired API

Writes an attribute to the stream.

Parameters
qualifiedName fully qualified attribute name
value attribute value
Throws
IOException when the stream write fails

protected void expressBodyText (String text)

This method is deprecated.
0.5 replaced by new SAX inspired API

Write element body text

Parameters
text write out this body text
Throws
IOException when the stream write fails

protected void expressElementEnd ()

This method is deprecated.
0.5 replaced by new SAX inspired API

Write an empty element end to the stream

Throws
IOException when stream write fails

protected void expressElementEnd (String qualifiedName)

This method is deprecated.
0.5 replaced by new SAX inspired API

Write an element end tag to the stream

Parameters
qualifiedName the name of the element
Throws
IOException when stream write fails

protected void expressElementStart (String qualifiedName)

This method is deprecated.
0.5 replaced by new SAX inspired API

Express an element tag start using given qualified name

Parameters
qualifiedName the fully qualified name of the element to write
Throws
IOException when stream write fails

protected void expressTagClose ()

This method is deprecated.
0.5 replaced by new SAX inspired API

Write a tag close to the stream

Throws
IOException when stream write fails

protected void startElement (WriteContext context, String uri, String localName, String qualifiedName, Attributes attr)

Writes the start tag for an element.

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
IOException if an IO problem occurs during writing
SAXException if an SAX problem occurs during writing

protected void writeIndent ()

This method is deprecated.
0.5 replaced by new SAX inspired API

Writes out indent's to the current indentLevel

Throws
IOException when stream write fails

protected void writePrintln ()

This method is deprecated.
0.5 replaced by new SAX inspired API

Writes out an empty line. Uses current endOfLine.

Throws
IOException when stream write fails