com.sun.xml.bind.marshaller

Class DataWriter

java.lang.Object

org.xml.sax.helpers.XMLFilterImpl

com.sun.xml.bind.marshaller.XMLWriter

com.sun.xml.bind.marshaller.DataWriter

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler, XMLFilter, XMLReader

public class DataWriter
extends XMLWriter

Write data- or field-oriented XML.

This filter pretty-prints field-oriented XML without mixed content. all added indentation and newlines will be passed on down the filter chain (if any).

In general, all whitespace in an XML document is potentially significant, so a general-purpose XML writing tool like the XMLWriter class cannot add newlines or indentation.

There is, however, a large class of XML documents where information is strictly fielded: each element contains either character data or other elements, but not both. For this special case, it is possible for a writing tool to provide automatic indentation and newlines without requiring extra work from the user. Note that this class will likely not yield appropriate results for document-oriented XML like XHTML pages, which mix character data and elements together.

This writer will automatically place each start tag on a new line, optionally indented if an indent step is provided (by default, there is no indentation). If an element contains other elements, the end tag will also appear on a new line with leading indentation. Consider, for example, the following code:

 DataWriter w = new DataWriter();

 w.setIndentStep(2);
 w.startDocument();
 w.startElement("Person");
 w.dataElement("name", "Jane Smith");
 w.dataElement("date-of-birth", "1965-05-23");
 w.dataElement("citizenship", "US");
 w.endElement("Person");
 w.endDocument();
 

This code will produce the following document:

 <?xml version="1.0" standalone="yes"?>

 <Person>
   <name>Jane Smith</name>
   <date-of-birth>1965-05-23</date-of-birth>
   <citizenship>US</citizenship>
 </Person>
 

This class inherits from XMLWriter, and provides all of the same support for Namespaces.

Since:

1.0

Version:

0.2

Author:

David Megginson, david@megginson.com

See Also:

XMLWriter

Constructor Summary

Constructors

Constructor and Description
DataWriter(Writer writer, String encoding)
DataWriter(Writer writer, String encoding, CharacterEscapeHandler _escapeHandler) Create a new data writer for the specified output.

Method Summary

Modifier and Type	Method and Description
void	characters(char[] ch, int start, int length) Write a sequence of characters.
void	endDocument() Write a newline at the end of the document.
void	endElement(String uri, String localName, String qName) Write an end tag.
int	getIndentStep() Deprecated. Only return the length of the indent string.
void	reset() Reset the writer so that it can be reused.
void	setIndentStep(int indentStep) Deprecated. Should use the version that takes string.
void	setIndentStep(String s)
void	startElement(String uri, String localName, String qName, Attributes atts) Write a start tag.
protected void	writeXmlDecl(String decl)

Methods inherited from class com.sun.xml.bind.marshaller.XMLWriter

characters, dataElement, dataElement, dataElement, endElement, endElement, flush, ignorableWhitespace, processingInstruction, setHeader, setOutput, setXmlDecl, startDocument, startElement, startElement, startPrefixMapping, write, write

Methods inherited from class org.xml.sax.helpers.XMLFilterImpl

endPrefixMapping, error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, notationDecl, parse, parse, resolveEntity, setContentHandler, setDocumentLocator, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, setProperty, skippedEntity, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Constructor Detail

DataWriter

public DataWriter(Writer writer,
                  String encoding,
                  CharacterEscapeHandler _escapeHandler)

Create a new data writer for the specified output.

Parameters:

writer - The character stream where the XML document will be written.

encoding - If non-null string is specified, it is written as a part of the XML declaration.

DataWriter

public DataWriter(Writer writer,
                  String encoding)

Method Detail

getIndentStep

public int getIndentStep()

Deprecated. Only return the length of the indent string.

Return the current indent step.

Return the current indent step: each start tag will be indented by this number of spaces times the number of ancestors that the element has.

Returns:

The number of spaces in each indentation step, or 0 or less for no indentation.

See Also:

setIndentStep(int)

setIndentStep

public void setIndentStep(int indentStep)

Deprecated. Should use the version that takes string.

Set the current indent step.

Parameters:

indentStep - The new indent step (0 or less for no indentation).

See Also:

getIndentStep()

setIndentStep

public void setIndentStep(String s)

reset

public void reset()

Reset the writer so that it can be reused.

This method is especially useful if the writer failed with an exception the last time through.

Overrides:

reset in class XMLWriter

See Also:

XMLWriter.reset()

writeXmlDecl

protected void writeXmlDecl(String decl)
                     throws IOException

Overrides:

writeXmlDecl in class XMLWriter

Throws:

IOException

startElement

public void startElement(String uri,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException

Write a start tag.

Each tag will begin on a new line, and will be indented by the current indent step times the number of ancestors that the element has.

The newline and indentation will be passed on down the filter chain through regular characters events.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class XMLWriter

Parameters:

uri - The element's Namespace URI.

localName - The element's local name.

qName - The element's qualified (prefixed) name.

atts - The element's attribute list.

Throws:

SAXException - If there is an error writing the start tag, or if a filter further down the chain raises an exception.

See Also:

XMLWriter.startElement(String, String, String, Attributes)

endElement

public void endElement(String uri,
                       String localName,
                       String qName)
                throws SAXException

Write an end tag.

If the element has contained other elements, the tag will appear indented on a new line; otherwise, it will appear immediately following whatever came before.

The newline and indentation will be passed on down the filter chain through regular characters events.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class XMLWriter

Parameters:

uri - The element's Namespace URI.

localName - The element's local name.

qName - The element's qualified (prefixed) name.

Throws:

SAXException - If there is an error writing the end tag, or if a filter further down the chain raises an exception.

See Also:

XMLWriter.endElement(String, String, String)

endDocument

public void endDocument()
                 throws SAXException

Description copied from class: XMLWriter

Write a newline at the end of the document. Pass the event on down the filter chain for further processing.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class XMLWriter

Throws:

SAXException - If there is an error writing the newline, or if a handler further down the filter chain raises an exception.

See Also:

ContentHandler.endDocument()

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

Write a sequence of characters.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class XMLWriter

Parameters:

ch - The characters to write.

start - The starting position in the array.

length - The number of characters to use.

Throws:

SAXException - If there is an error writing the characters, or if a filter further down the chain raises an exception.

See Also:

XMLWriter.characters(char[], int, int)