org.apache.commons.betwixt.io
Class BeanWriter

java.lang.Object
  extended by org.apache.commons.betwixt.io.AbstractBeanWriter
      extended by 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


Copyright 2002-2008 The Apache Software Foundation. All Rights Reserved.