org.dom4j.io
Class XMLWriter

java.lang.Object
  org.xml.sax.helpers.XMLFilterImpl
      org.dom4j.io.XMLWriter

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler, LexicalHandler, XMLFilter, XMLReader

Direct Known Subclasses:

HTMLWriter

public class XMLWriter

extends XMLFilterImpl

implements LexicalHandler

XMLWriter takes a DOM4J tree and formats it to a stream as XML. It can also take SAX events too so can be used by SAX clients as this object implements the ContentHandlerand LexicalHandler interfaces. as well. This formatter performs typical document formatting. The XML declaration and processing instructions are always on their own lines. An OutputFormatobject can be used to define how whitespace is handled when printing and allows various configuration options, such as to allow suppression of the XML declaration, the encoding declaration or whether empty documents are collapsed.

There are write(...) methods to print any of the standard DOM4J classes, including Document and Element, to either a Writer or an OutputStream. Warning: using your own Writer may cause the writer's preferred character encoding to be ignored. If you use encodings other than UTF8, we recommend using the method that takes an OutputStream instead.

Version:

$Revision: 1.83.2.2 $

Author:

James Strachan , Joseph Bowbeer

Field Summary

protected static OutputFormat	DEFAULT_FORMAT
protected int	lastOutputNodeType Stores the last type of node written so algorithms can refer to the previous node type
protected static String[]	LEXICAL_HANDLER_NAMES
protected boolean	preserve Stores the xml:space attribute value of preserve for whitespace flag
protected Writer	writer The Writer used to output to

Constructor Summary

XMLWriter()

XMLWriter(OutputFormat format)

XMLWriter(OutputStream out)

XMLWriter(OutputStream out, OutputFormat format)

XMLWriter(Writer writer)

XMLWriter(Writer writer, OutputFormat format)

Method Summary

void	characters(char[] ch, int start, int length)
void	close() Closes the underlying Writer
void	comment(char[] ch, int start, int length)
protected Writer	createWriter(OutputStream outStream, String encoding) Get an OutputStreamWriter, use preferred encoding.
protected int	defaultMaximumAllowedCharacter() Returns the maximum allowed character code that should be allowed unescaped which defaults to 127 in US-ASCII (7 bit) or 255 in ISO- (8 bit).
void	endCDATA()
void	endDocument()
void	endDTD()
void	endElement(String namespaceURI, String localName, String qName)
void	endEntity(String name)
void	endPrefixMapping(String prefix)
protected String	escapeAttributeEntities(String text) This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes.
protected String	escapeElementEntities(String text) This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes.
void	flush() Flushes the underlying Writer
LexicalHandler	getLexicalHandler()
int	getMaximumAllowedCharacter() Returns the maximum allowed character code that should be allowed unescaped which defaults to 127 in US-ASCII (7 bit) or 255 in ISO- (8 bit).
protected OutputFormat	getOutputFormat() Lets subclasses get at the current format object, so they can call setTrimText, setNewLines, etc.
Object	getProperty(String name)
protected void	handleException(IOException e)
void	ignorableWhitespace(char[] ch, int start, int length)
protected void	indent()
protected void	installLexicalHandler()
protected boolean	isElementSpacePreserved(Element element) Determines if element is a special case of XML elements where it contains an xml:space attribute of "preserve".
boolean	isEscapeText() DOCUMENT ME!
protected boolean	isExpandEmptyElements()
protected boolean	isNamespaceDeclaration(Namespace ns)
void	notationDecl(String name, String publicID, String systemID)
void	parse(InputSource source)
void	println() Writes the new line text to the underlying Writer
void	processingInstruction(String target, String data)
boolean	resolveEntityRefs()
void	setDocumentLocator(Locator locator)
void	setEscapeText(boolean escapeText) Sets whether text output should be escaped or not.
void	setIndentLevel(int indentLevel) Set the initial indentation level.
void	setLexicalHandler(LexicalHandler handler)
void	setMaximumAllowedCharacter(int maximumAllowedCharacter) Sets the maximum allowed character code that should be allowed unescaped such as 127 in US-ASCII (7 bit) or 255 in ISO- (8 bit) or -1 to not escape any characters (other than the special XML characters like < > &) If this is not explicitly set then it is defaulted from the encoding.
void	setOutputStream(OutputStream out)
void	setProperty(String name, Object value)
void	setResolveEntityRefs(boolean resolve)
void	setWriter(Writer writer)
protected boolean	shouldEncodeChar(char c) Should the given character be escaped.
void	startCDATA()
void	startDocument()
void	startDTD(String name, String publicID, String systemID)
void	startElement(String namespaceURI, String localName, String qName, Attributes attributes)
void	startEntity(String name)
void	startPrefixMapping(String prefix, String uri)
void	unparsedEntityDecl(String name, String publicID, String systemID, String notationName)
void	write(Attribute attribute) Writes the given Attribute.
void	write(CDATA cdata) Writes the given CDATA.
void	write(Comment comment) Writes the given Comment.
void	write(Document doc) This will print the Document to the current Writer.
void	write(DocumentType docType) Writes the given DocumentType.
void	write(Element element) Writes the Element, including its Attribute s, and its value, and all its content (child nodes) to the current Writer.
void	write(Entity entity) Writes the given Entity.
void	write(Namespace namespace) Writes the given Namespace.
void	write(Node node) Writes the given Node.
void	write(Object object) Writes the given object which should be a String, a Node or a List of Nodes.
void	write(ProcessingInstruction processingInstruction) Writes the given ProcessingInstruction.
void	write(String text) Print out a String, Perfoms the necessary entity escaping and whitespace stripping.
void	write(Text text) Writes the given Text.
protected void	writeAttribute(Attribute attribute)
protected void	writeAttribute(Attributes attributes, int index)
protected void	writeAttributes(Attributes attributes)
protected void	writeAttributes(Element element) Writes the attributes of the given element
protected void	writeCDATA(String text)
void	writeClose(Element element) Writes the closing tag of an Element
protected void	writeClose(String qualifiedName)
protected void	writeComment(String text)
protected void	writeDeclaration() This will write the declaration to the given Writer.
protected void	writeDocType(DocumentType docType)
protected void	writeDocType(String name, String publicID, String systemID)
protected void	writeElement(Element element)
protected void	writeElementContent(Element element) Outputs the content of the given element.
protected void	writeEmptyElementClose(String qualifiedName)
protected void	writeEntity(Entity entity)
protected void	writeEntityRef(String name)
protected void	writeEscapeAttributeEntities(String txt)
protected void	writeNamespace(Namespace namespace)
protected void	writeNamespace(String prefix, String uri) Writes the SAX namepsaces
protected void	writeNamespaces() Writes the SAX namepsaces
protected void	writeNode(Node node)
protected void	writeNodeText(Node node) This method is used to write out Nodes that contain text and still allow for xml:space to be handled properly.
void	writeOpen(Element element) Writes the opening tag of an Element, including its Attributes but without its content.
protected void	writePrintln() This will print a new line only if the newlines flag was set to true
protected void	writeProcessingInstruction(ProcessingInstruction pi)
protected void	writeString(String text)

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

error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, parse, resolveEntity, setContentHandler, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, skippedEntity, warning

Methods inherited from class java.lang.Object

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

Field Detail

LEXICAL_HANDLER_NAMES

protected static final String[] LEXICAL_HANDLER_NAMES

DEFAULT_FORMAT

protected static final OutputFormat DEFAULT_FORMAT

lastOutputNodeType

protected int lastOutputNodeType

Stores the last type of node written so algorithms can refer to the previous node type

preserve

protected boolean preserve

Stores the xml:space attribute value of preserve for whitespace flag

writer

protected Writer writer

The Writer used to output to

Constructor Detail

XMLWriter

public XMLWriter(Writer writer)

XMLWriter

public XMLWriter(Writer writer,
                 OutputFormat format)

XMLWriter

public XMLWriter()

XMLWriter

public XMLWriter(OutputStream out)
          throws UnsupportedEncodingException

XMLWriter

public XMLWriter(OutputStream out,
                 OutputFormat format)
          throws UnsupportedEncodingException

XMLWriter

public XMLWriter(OutputFormat format)
          throws UnsupportedEncodingException

Method Detail

setWriter

public void setWriter(Writer writer)

setOutputStream

public void setOutputStream(OutputStream out)
                     throws UnsupportedEncodingException

Throws:

UnsupportedEncodingException

isEscapeText

public boolean isEscapeText()

DOCUMENT ME!

Returns:

true if text thats output should be escaped. This is enabled by default. It could be disabled if the output format is textual, like in XSLT where we can have xml, html or text output.

setEscapeText

public void setEscapeText(boolean escapeText)

Sets whether text output should be escaped or not. This is enabled by default. It could be disabled if the output format is textual, like in XSLT where we can have xml, html or text output.

Parameters:

escapeText - DOCUMENT ME!

setIndentLevel

public void setIndentLevel(int indentLevel)

Set the initial indentation level. This can be used to output a document (or, more likely, an element) starting at a given indent level, so it's not always flush against the left margin. Default: 0

Parameters:

indentLevel - the number of indents to start with

getMaximumAllowedCharacter

public int getMaximumAllowedCharacter()

Returns the maximum allowed character code that should be allowed unescaped which defaults to 127 in US-ASCII (7 bit) or 255 in ISO- (8 bit).

Returns:

DOCUMENT ME!

setMaximumAllowedCharacter

public void setMaximumAllowedCharacter(int maximumAllowedCharacter)

Sets the maximum allowed character code that should be allowed unescaped such as 127 in US-ASCII (7 bit) or 255 in ISO- (8 bit) or -1 to not escape any characters (other than the special XML characters like < > &) If this is not explicitly set then it is defaulted from the encoding.

Parameters:

maximumAllowedCharacter - The maximumAllowedCharacter to set

flush

public void flush()
           throws IOException

Flushes the underlying Writer

Throws:

IOException - DOCUMENT ME!

close

public void close()
           throws IOException

Closes the underlying Writer

Throws:

IOException - DOCUMENT ME!

println

public void println()
             throws IOException

Writes the new line text to the underlying Writer

Throws:

IOException - DOCUMENT ME!

write

public void write(Attribute attribute)
           throws IOException

Writes the given Attribute.

Parameters:

attribute - Attribute to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(Document doc)
           throws IOException

This will print the Document to the current Writer.

Warning: using your own Writer may cause the writer's preferred character encoding to be ignored. If you use encodings other than UTF8, we recommend using the method that takes an OutputStream instead.

Note: as with all Writers, you may need to flush() yours after this method returns.

Parameters:

doc - Document to format.

Throws:

IOException - if there's any problem writing.

write

public void write(Element element)
           throws IOException

Writes the Element, including its Attribute s, and its value, and all its content (child nodes) to the current Writer.

Parameters:

element - Element to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(CDATA cdata)
           throws IOException

Writes the given CDATA.

Parameters:

cdata - CDATA to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(Comment comment)
           throws IOException

Writes the given Comment.

Parameters:

comment - Comment to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(DocumentType docType)
           throws IOException

Writes the given DocumentType.

Parameters:

docType - DocumentType to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(Entity entity)
           throws IOException

Writes the given Entity.

Parameters:

entity - Entity to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(Namespace namespace)
           throws IOException

Writes the given Namespace.

Parameters:

namespace - Namespace to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(ProcessingInstruction processingInstruction)
           throws IOException

Writes the given ProcessingInstruction.

Parameters:

processingInstruction - ProcessingInstruction to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(String text)
           throws IOException

Print out a String, Perfoms the necessary entity escaping and whitespace stripping.

Parameters:

text - is the text to output

Throws:

IOException - DOCUMENT ME!

write

public void write(Text text)
           throws IOException

Writes the given Text.

Parameters:

text - Text to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(Node node)
           throws IOException

Writes the given Node.

Parameters:

node - Node to output.

Throws:

IOException - DOCUMENT ME!

write

public void write(Object object)
           throws IOException

Writes the given object which should be a String, a Node or a List of Nodes.

Parameters:

object - is the object to output.

Throws:

IOException - DOCUMENT ME!

writeOpen

public void writeOpen(Element element)
               throws IOException

Writes the opening tag of an Element, including its Attributes but without its content.

Parameters:

element - Element to output.

Throws:

IOException - DOCUMENT ME!

writeClose

public void writeClose(Element element)
                throws IOException

Writes the closing tag of an Element

Parameters:

element - Element to output.

Throws:

IOException - DOCUMENT ME!

parse

public void parse(InputSource source)
           throws IOException,
                  SAXException

Specified by:

parse in interface XMLReader

Throws:

IOException

SAXException

setProperty

public void setProperty(String name,
                        Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

Specified by:

setProperty in interface XMLReader

Throws:

SAXNotRecognizedException

SAXNotSupportedException

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

Specified by:

getProperty in interface XMLReader

Throws:

SAXNotRecognizedException

SAXNotSupportedException

setLexicalHandler

public void setLexicalHandler(LexicalHandler handler)

getLexicalHandler

public LexicalHandler getLexicalHandler()

setDocumentLocator

public void setDocumentLocator(Locator locator)

Specified by:

setDocumentLocator in interface ContentHandler

startDocument

public void startDocument()
                   throws SAXException

Specified by:

startDocument in interface ContentHandler

Throws:

SAXException

endDocument

public void endDocument()
                 throws SAXException

Specified by:

endDocument in interface ContentHandler

Throws:

SAXException

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Specified by:

startPrefixMapping in interface ContentHandler

Throws:

SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Specified by:

endPrefixMapping in interface ContentHandler

Throws:

SAXException

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes attributes)
                  throws SAXException

Specified by:

startElement in interface ContentHandler

Throws:

SAXException

endElement

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

Specified by:

endElement in interface ContentHandler

Throws:

SAXException

characters

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

Specified by:

characters in interface ContentHandler

Throws:

SAXException

ignorableWhitespace

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

Specified by:

ignorableWhitespace in interface ContentHandler

Throws:

SAXException

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

Specified by:

processingInstruction in interface ContentHandler

Throws:

SAXException

notationDecl

public void notationDecl(String name,
                         String publicID,
                         String systemID)
                  throws SAXException

Specified by:

notationDecl in interface DTDHandler

Throws:

SAXException

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                               String publicID,
                               String systemID,
                               String notationName)
                        throws SAXException

Specified by:

unparsedEntityDecl in interface DTDHandler

Throws:

SAXException

startDTD

public void startDTD(String name,
                     String publicID,
                     String systemID)
              throws SAXException

Specified by:

startDTD in interface LexicalHandler

Throws:

SAXException

endDTD

public void endDTD()
            throws SAXException

Specified by:

endDTD in interface LexicalHandler

Throws:

SAXException

startCDATA

public void startCDATA()
                throws SAXException

Specified by:

startCDATA in interface LexicalHandler

Throws:

SAXException

endCDATA

public void endCDATA()
              throws SAXException

Specified by:

endCDATA in interface LexicalHandler

Throws:

SAXException

startEntity

public void startEntity(String name)
                 throws SAXException

Specified by:

startEntity in interface LexicalHandler

Throws:

SAXException

endEntity

public void endEntity(String name)
               throws SAXException

Specified by:

endEntity in interface LexicalHandler

Throws:

SAXException

comment

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

Specified by:

comment in interface LexicalHandler

Throws:

SAXException

writeElement

protected void writeElement(Element element)
                     throws IOException

Throws:

IOException

isElementSpacePreserved

protected final boolean isElementSpacePreserved(Element element)

Determines if element is a special case of XML elements where it contains an xml:space attribute of "preserve". If it does, then retain whitespace.

Parameters:

element - DOCUMENT ME!

Returns:

DOCUMENT ME!

writeElementContent

protected void writeElementContent(Element element)
                            throws IOException

Outputs the content of the given element. If whitespace trimming is enabled then all adjacent text nodes are appended together before the whitespace trimming occurs to avoid problems with multiple text nodes being created due to text content that spans parser buffers in a SAX parser.

Parameters:

element - DOCUMENT ME!

Throws:

IOException - DOCUMENT ME!

writeCDATA

protected void writeCDATA(String text)
                   throws IOException

Throws:

IOException

writeDocType

protected void writeDocType(DocumentType docType)
                     throws IOException

Throws:

IOException

writeNamespace

protected void writeNamespace(Namespace namespace)
                       throws IOException

Throws:

IOException

writeNamespaces

protected void writeNamespaces()
                        throws IOException

Writes the SAX namepsaces

Throws:

IOException - DOCUMENT ME!

writeNamespace

protected void writeNamespace(String prefix,
                              String uri)
                       throws IOException

Writes the SAX namepsaces

Parameters:

prefix - the prefix

uri - the namespace uri

Throws:

IOException

writeProcessingInstruction

protected void writeProcessingInstruction(ProcessingInstruction pi)
                                   throws IOException

Throws:

IOException

writeString

protected void writeString(String text)
                    throws IOException

Throws:

IOException

writeNodeText

protected void writeNodeText(Node node)
                      throws IOException

This method is used to write out Nodes that contain text and still allow for xml:space to be handled properly.

Parameters:

node - DOCUMENT ME!

Throws:

IOException - DOCUMENT ME!

writeNode

protected void writeNode(Node node)
                  throws IOException

Throws:

IOException

installLexicalHandler

protected void installLexicalHandler()

writeDocType

protected void writeDocType(String name,
                            String publicID,
                            String systemID)
                     throws IOException

Throws:

IOException

writeEntity

protected void writeEntity(Entity entity)
                    throws IOException

Throws:

IOException

writeEntityRef

protected void writeEntityRef(String name)
                       throws IOException

Throws:

IOException

writeComment

protected void writeComment(String text)
                     throws IOException

Throws:

IOException

writeAttributes

protected void writeAttributes(Element element)
                        throws IOException

Writes the attributes of the given element

Parameters:

element - DOCUMENT ME!

Throws:

IOException - DOCUMENT ME!

writeAttribute

protected void writeAttribute(Attribute attribute)
                       throws IOException

Throws:

IOException

writeAttributes

protected void writeAttributes(Attributes attributes)
                        throws IOException

Throws:

IOException

writeAttribute

protected void writeAttribute(Attributes attributes,
                              int index)
                       throws IOException

Throws:

IOException

indent

protected void indent()
               throws IOException

Throws:

IOException

writePrintln

protected void writePrintln()
                     throws IOException

This will print a new line only if the newlines flag was set to true

Throws:

IOException - DOCUMENT ME!

createWriter

protected Writer createWriter(OutputStream outStream,
                              String encoding)
                       throws UnsupportedEncodingException

Get an OutputStreamWriter, use preferred encoding.

Parameters:

outStream - DOCUMENT ME!

encoding - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

UnsupportedEncodingException - DOCUMENT ME!

writeDeclaration

protected void writeDeclaration()
                         throws IOException

This will write the declaration to the given Writer. Assumes XML version 1.0 since we don't directly know.

Throws:

IOException - DOCUMENT ME!

writeClose

protected void writeClose(String qualifiedName)
                   throws IOException

Throws:

IOException

writeEmptyElementClose

protected void writeEmptyElementClose(String qualifiedName)
                               throws IOException

Throws:

IOException

isExpandEmptyElements

protected boolean isExpandEmptyElements()

escapeElementEntities

protected String escapeElementEntities(String text)

This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes.

Parameters:

text - DOCUMENT ME!

Returns:

DOCUMENT ME!

writeEscapeAttributeEntities

protected void writeEscapeAttributeEntities(String txt)
                                     throws IOException

Throws:

IOException

escapeAttributeEntities

protected String escapeAttributeEntities(String text)

This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes.

Parameters:

text - DOCUMENT ME!

Returns:

DOCUMENT ME!

shouldEncodeChar

protected boolean shouldEncodeChar(char c)

Should the given character be escaped. This depends on the encoding of the document.

Parameters:

c - DOCUMENT ME!

Returns:

boolean

defaultMaximumAllowedCharacter

protected int defaultMaximumAllowedCharacter()

Returns the maximum allowed character code that should be allowed unescaped which defaults to 127 in US-ASCII (7 bit) or 255 in ISO- (8 bit).

Returns:

DOCUMENT ME!

isNamespaceDeclaration

protected boolean isNamespaceDeclaration(Namespace ns)

handleException

protected void handleException(IOException e)
                        throws SAXException

Throws:

SAXException

getOutputFormat

protected OutputFormat getOutputFormat()

Lets subclasses get at the current format object, so they can call setTrimText, setNewLines, etc. Put in to support the HTMLWriter, in the way that it pushes the current newline/trim state onto a stack and overrides the state within preformatted tags.

Returns:

DOCUMENT ME!

resolveEntityRefs

public boolean resolveEntityRefs()

setResolveEntityRefs

public void setResolveEntityRefs(boolean resolve)