Top Description Fields Constructors Methods
org.dom4j.io

public Class XMLWriter

extends XMLFilterImpl
implements LexicalHandler
Class Inheritance
All Implemented Interfaces
org.xml.sax.ext.LexicalHandler
Known Direct Subclasses
org.dom4j.io.HTMLWriter
Imports
java.io.BufferedWriter, .IOException, .OutputStream, .OutputStreamWriter, .UnsupportedEncodingException, .Writer, java.util.HashMap, .Iterator, .List, .Map, .StringTokenizer, org.dom4j.Attribute, .CDATA, .Comment, .Document, .DocumentType, .Element, .Entity, .Namespace, .Node, .ProcessingInstruction, .Text, org.dom4j.tree.NamespaceStack, org.xml.sax.Attributes, .InputSource, .Locator, .SAXException, .SAXNotRecognizedException, .SAXNotSupportedException, .XMLReader, org.xml.sax.ext.LexicalHandler, org.xml.sax.helpers.XMLFilterImpl

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 org.xml.sax.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.

Authors
James Strachan , Joseph Bowbeer
Version
$Revision: 1.83 $

Field Summary

Modifier and TypeField and Description
private boolean
autoFlush

Whether a flush should occur after writing a document

private StringBuffer
buffer

buffer used when escaping strings

private boolean
charsAdded

whether we have added characters before from the same chunk of characters

protected static final OutputFormat
DEFAULT_FORMAT

private boolean
escapeText

whether we should escape text

private OutputFormat
format

The format used by this writer

private int
indentLevel

The initial number of indentations (so you can print a whole document indented, if you like)

private boolean
inDTD

Is the writer curerntly inside a DTD definition?

private char
lastChar

private boolean
lastElementClosed

Stores if the last written element node was a closing tag or an opening tag.

protected int
lastOutputNodeType

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

protected static final String[]
LEXICAL_HANDLER_NAMES

private LexicalHandler
lexicalHandler

Lexical handler we should delegate to

private int
maximumAllowedCharacter

what is the maximum allowed character code 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 < > &)

private Map<String, String>
namespacesMap

The namespaces used for the current element when consuming SAX events

private NamespaceStack
namespaceStack

The Stack of namespaceStack written so far

private static final String
PAD_TEXT

protected boolean
preserve

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

private boolean
resolveEntityRefs

Should entityRefs by resolved when writing ?

private boolean
showCommentsInDTDs

Whether comments should appear inside DTD declarations - defaults to false

protected Writer
writer

The Writer used to output to

Constructor Summary

AccessConstructor and Description
public
XMLWriter(Writer writer)

public
XMLWriter(Writer writer, OutputFormat format)

public
XMLWriter()

public
XMLWriter(OutputStream out)

public
XMLWriter(OutputStream out, OutputFormat format)

public
XMLWriter(OutputFormat format)

Method Summary

Modifier and TypeMethod and Description
public void
characters(char[]
An array of characters.
ch, int
The starting position in the array.
start, int
The number of characters to use from the array.
length)

Overrides org.xml.sax.helpers.XMLFilterImpl.characters.

Implements org.xml.sax.ContentHandler.characters.

Filter a character data event.
public void
close()

Closes the underlying Writer

public void
comment(char[]
An array holding the characters in the comment.
ch, int
The starting position in the array.
start, int
The number of characters to use from the array.
length)

Implements org.xml.sax.ext.LexicalHandler.comment.

Report an XML comment anywhere in the document.
protected Writer

Returns:

DOCUMENT ME!
createWriter(OutputStream
DOCUMENT ME!
outStream, String
DOCUMENT ME!
encoding)

Get an OutputStreamWriter, use preferred encoding.

protected int

Returns:

DOCUMENT ME!
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).

public void
endCDATA()

Implements org.xml.sax.ext.LexicalHandler.endCDATA.

Report the end of a CDATA section.
public void
endDocument()

Overrides org.xml.sax.helpers.XMLFilterImpl.endDocument.

Implements org.xml.sax.ContentHandler.endDocument.

Filter an end document event.
public void
endDTD()

Implements org.xml.sax.ext.LexicalHandler.endDTD.

Report the end of DTD declarations.
public void
endElement(String
The element's Namespace URI, or the empty string.
namespaceURI, String
The element's local name, or the empty string.
localName, String
The element's qualified (prefixed) name, or the empty string.
qName)

Overrides org.xml.sax.helpers.XMLFilterImpl.endElement.

Implements org.xml.sax.ContentHandler.endElement.

Filter an end element event.
public void
endEntity(String
The name of the entity that is ending.
name)

Implements org.xml.sax.ext.LexicalHandler.endEntity.

Report the end of an entity.
public void
endPrefixMapping(String
The Namespace prefix.
prefix)

Overrides org.xml.sax.helpers.XMLFilterImpl.endPrefixMapping.

Implements org.xml.sax.ContentHandler.endPrefixMapping.

Filter an end Namespace prefix mapping event.
protected String

Returns:

DOCUMENT ME!
escapeAttributeEntities(String
DOCUMENT ME!
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

Returns:

DOCUMENT ME!
escapeElementEntities(String
DOCUMENT ME!
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.

public void
flush()

Flushes the underlying Writer

public LexicalHandler
getLexicalHandler()

public int

Returns:

DOCUMENT ME!
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

Returns:

DOCUMENT ME!
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.

public Object
getProperty(String
The property name.
name)

Overrides org.xml.sax.helpers.XMLFilterImpl.getProperty.

Implements org.xml.sax.XMLReader.getProperty.

Look up the value of a property.
protected void
handleException(IOException e)

public void
ignorableWhitespace(char[]
An array of characters.
ch, int
The starting position in the array.
start, int
The number of characters to use from the array.
length)

Overrides org.xml.sax.helpers.XMLFilterImpl.ignorableWhitespace.

Implements org.xml.sax.ContentHandler.ignorableWhitespace.

Filter an ignorable whitespace event.
protected void
indent()

protected void
installLexicalHandler()

protected final boolean

Returns:

DOCUMENT ME!
isElementSpacePreserved(Element
DOCUMENT ME!
element)

Determines if element is a special case of XML elements where it contains an xml:space attribute of "preserve".

public boolean

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

DOCUMENT ME!

protected boolean
isExpandEmptyElements()

protected boolean
isNamespaceDeclaration(Namespace ns)

public void
notationDecl(String
The notation name.
name, String
The notation's public identifier, or null.
publicID, String
The notation's system identifier, or null.
systemID)

Overrides org.xml.sax.helpers.XMLFilterImpl.notationDecl.

Implements org.xml.sax.DTDHandler.notationDecl.

Filter a notation declaration event.
public void
parse(InputSource
The input source for the document entity.
source)

Overrides org.xml.sax.helpers.XMLFilterImpl.parse.

Implements org.xml.sax.XMLReader.parse.

Parse a document.
public void
println()

Writes the new line text to the underlying Writer

public void
processingInstruction(String
The processing instruction target.
target, String
The text following the target.
data)

Overrides org.xml.sax.helpers.XMLFilterImpl.processingInstruction.

Implements org.xml.sax.ContentHandler.processingInstruction.

Filter a processing instruction event.
public boolean
resolveEntityRefs()

public void
setDocumentLocator(Locator
The document locator.
locator)

Overrides org.xml.sax.helpers.XMLFilterImpl.setDocumentLocator.

Implements org.xml.sax.ContentHandler.setDocumentLocator.

Filter a new document locator event.
public void
setEscapeText(boolean
DOCUMENT ME!
escapeText)

Sets whether text output should be escaped or not.

public void
setIndentLevel(int
the number of indents to start with
indentLevel)

Set the initial indentation level.

public void
setLexicalHandler(LexicalHandler handler)

public void
setMaximumAllowedCharacter(int
The maximumAllowedCharacter to set
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.

public void
setOutputStream(OutputStream out)

public void
setProperty(String
The property name.
name, Object
The requested property value.
value)

Overrides org.xml.sax.helpers.XMLFilterImpl.setProperty.

Implements org.xml.sax.XMLReader.setProperty.

Set the value of a property.
public void
setResolveEntityRefs(boolean resolve)

public void
setWriter(Writer writer)

protected boolean

Returns:

boolean
shouldEncodeChar(int
Unicode codepoint. DOCUMENT ME!
codepoint)

Should the given character be escaped.

public void
startCDATA()

Implements org.xml.sax.ext.LexicalHandler.startCDATA.

Report the start of a CDATA section.
public void
startDocument()

Overrides org.xml.sax.helpers.XMLFilterImpl.startDocument.

Implements org.xml.sax.ContentHandler.startDocument.

Filter a start document event.
public void
startDTD(String
The document type name.
name, String
The declared public identifier for the external DTD subset, or null if none was declared.
publicID, String
The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)
systemID)

Implements org.xml.sax.ext.LexicalHandler.startDTD.

Report the start of DTD declarations, if any.
public void
startElement(String
The element's Namespace URI, or the empty string.
namespaceURI, String
The element's local name, or the empty string.
localName, String
The element's qualified (prefixed) name, or the empty string.
qName, Attributes
The element's attributes.
attributes)

Overrides org.xml.sax.helpers.XMLFilterImpl.startElement.

Implements org.xml.sax.ContentHandler.startElement.

Filter a start element event.
public void
startEntity(String
The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
name)

Implements org.xml.sax.ext.LexicalHandler.startEntity.

Report the beginning of some internal and external XML entities.
public void
startPrefixMapping(String
The Namespace prefix.
prefix, String
The Namespace URI.
uri)

Overrides org.xml.sax.helpers.XMLFilterImpl.startPrefixMapping.

Implements org.xml.sax.ContentHandler.startPrefixMapping.

Filter a start Namespace prefix mapping event.
public void
unparsedEntityDecl(String
The entity name.
name, String
The entity's public identifier, or null.
publicID, String
The entity's system identifier, or null.
systemID, String
The name of the associated notation.
notationName)

Overrides org.xml.sax.helpers.XMLFilterImpl.unparsedEntityDecl.

Implements org.xml.sax.DTDHandler.unparsedEntityDecl.

Filter an unparsed entity declaration event.
public void
write(Attribute
Attribute to output.
attribute)

Writes the given Attribute.

public void
write(Document
Document to format.
doc)

This will print the Document to the current Writer.

public void
write(Element
Element to output.
element)

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

public void
write(CDATA
CDATA to output.
cdata)

Writes the given CDATA.

public void
write(Comment
Comment to output.
comment)

Writes the given Comment.

public void
write(DocumentType
DocumentType to output.
docType)

Writes the given DocumentType.

public void
write(Entity
Entity to output.
entity)

Writes the given Entity.

public void
write(Namespace
Namespace to output.
namespace)

Writes the given Namespace.

public void
write(ProcessingInstruction
ProcessingInstruction to output.
processingInstruction)

Writes the given ProcessingInstruction.

public void
write(String
is the text to output
text)

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

public void
write(Text
Text to output.
text)

Writes the given Text.

public void
write(Node
Node to output.
node)

Writes the given Node.

public void
write(Object
is the object to output.
object)

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

protected void
writeAttribute(Attribute attribute)

protected void
writeAttribute(String qualifiedName, String value)

protected void
writeAttribute(Attributes attributes, int index)

protected void
writeAttributes(Element
DOCUMENT ME!
element)

Writes the attributes of the given element

protected void
writeAttributes(Attributes attributes)

protected void
writeCDATA(String text)

public void
writeClose(Element
Element to output.
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
DOCUMENT ME!
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
the prefix
prefix, String
the namespace uri
uri)

Writes the SAX namepsaces

protected void
writeNamespaces()

Writes the SAX namepsaces

protected void
writeNamespaces(Element element)

Writes all namespaces declared directly on element.

protected void
writeNode(Node node)

protected void
writeNodeText(Node
DOCUMENT ME!
node)

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

public void
writeOpen(Element
Element to output.
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)

Inherited from org.xml.sax.helpers.XMLFilterImpl:
errorfatalErrorgetContentHandlergetDTDHandlergetEntityResolvergetErrorHandlergetFeaturegetParentparseresolveEntitysetContentHandlersetDTDHandlersetEntityResolversetErrorHandlersetFeaturesetParentskippedEntitywarning