org.apache.commons.betwixt.io
Class BeanWriter

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

Field Summary
private static java.lang.String AMPERSAND_ENTITY
          Escaped & entity
private static java.lang.String APOSTROPHE_ENTITY
          Escaped ' entity
private  boolean autoFlush
          should we flush after writing bean
private  java.lang.String endOfLine
          text used for end of lines.
private static java.lang.String EOL
          text used for end of lines.
private static java.lang.String GREATER_THAN_ENTITY
          Escaped > entity
private  java.lang.String indent
          indentation text
private static java.lang.String LESS_THAN_ENTITY
          Escaped < entity
private  org.apache.commons.logging.Log log
          Log used for logging (Doh!)
private static java.lang.String QUOTE_ENTITY
          Escaped " entity
private  java.io.Writer writer
          Where the output goes
 
Fields inherited from class org.apache.commons.betwixt.io.AbstractBeanWriter
 
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
 

Field Detail

LESS_THAN_ENTITY

private static final java.lang.String LESS_THAN_ENTITY
Escaped < entity

See Also:
Constant Field Values

GREATER_THAN_ENTITY

private static final java.lang.String GREATER_THAN_ENTITY
Escaped > entity

See Also:
Constant Field Values

AMPERSAND_ENTITY

private static final java.lang.String AMPERSAND_ENTITY
Escaped & entity

See Also:
Constant Field Values

APOSTROPHE_ENTITY

private static final java.lang.String APOSTROPHE_ENTITY
Escaped ' entity

See Also:
Constant Field Values

QUOTE_ENTITY

private static final java.lang.String QUOTE_ENTITY
Escaped " entity

See Also:
Constant Field Values

writer

private java.io.Writer writer
Where the output goes


EOL

private static final java.lang.String EOL
text used for end of lines. Defaults to \n

See Also:
Constant Field Values

endOfLine

private java.lang.String endOfLine
text used for end of lines. Defaults to \n


indent

private java.lang.String indent
indentation text


autoFlush

private boolean autoFlush
should we flush after writing bean


log

private org.apache.commons.logging.Log log
Log used for logging (Doh!)

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

Specified by:
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

Specified by:
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

Specified by:
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

Specified by:
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

Specified by:
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.

Specified by:
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