org.dom4j.io

Class XMLWriter

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 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.

Version: $Revision: 1.83.2.2 $

Author: James Strachan Joseph Bowbeer

Field Summary
protected static OutputFormatDEFAULT_FORMAT
protected intlastOutputNodeType
Stores the last type of node written so algorithms can refer to the previous node type
protected static String[]LEXICAL_HANDLER_NAMES
protected booleanpreserve
Stores the xml:space attribute value of preserve for whitespace flag
protected Writerwriter
The Writer used to output to
Constructor Summary
XMLWriter(Writer writer)
XMLWriter(Writer writer, OutputFormat format)
XMLWriter()
XMLWriter(OutputStream out)
XMLWriter(OutputStream out, OutputFormat format)
XMLWriter(OutputFormat format)
Method Summary
voidcharacters(char[] ch, int start, int length)
voidclose()
Closes the underlying Writer
voidcomment(char[] ch, int start, int length)
protected WritercreateWriter(OutputStream outStream, String encoding)
Get an OutputStreamWriter, use preferred encoding.
protected intdefaultMaximumAllowedCharacter()
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).
voidendCDATA()
voidendDocument()
voidendDTD()
voidendElement(String namespaceURI, String localName, String qName)
voidendEntity(String name)
voidendPrefixMapping(String prefix)
protected StringescapeAttributeEntities(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 StringescapeElementEntities(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.
voidflush()
Flushes the underlying Writer
LexicalHandlergetLexicalHandler()
intgetMaximumAllowedCharacter()
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 OutputFormatgetOutputFormat()
Lets subclasses get at the current format object, so they can call setTrimText, setNewLines, etc.
ObjectgetProperty(String name)
protected voidhandleException(IOException e)
voidignorableWhitespace(char[] ch, int start, int length)
protected voidindent()
protected voidinstallLexicalHandler()
protected booleanisElementSpacePreserved(Element element)
Determines if element is a special case of XML elements where it contains an xml:space attribute of "preserve".
booleanisEscapeText()
DOCUMENT ME!
protected booleanisExpandEmptyElements()
protected booleanisNamespaceDeclaration(Namespace ns)
voidnotationDecl(String name, String publicID, String systemID)
voidparse(InputSource source)
voidprintln()
Writes the new line text to the underlying Writer
voidprocessingInstruction(String target, String data)
booleanresolveEntityRefs()
voidsetDocumentLocator(Locator locator)
voidsetEscapeText(boolean escapeText)
Sets whether text output should be escaped or not.
voidsetIndentLevel(int indentLevel)
Set the initial indentation level.
voidsetLexicalHandler(LexicalHandler handler)
voidsetMaximumAllowedCharacter(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.
voidsetOutputStream(OutputStream out)
voidsetProperty(String name, Object value)
voidsetResolveEntityRefs(boolean resolve)
voidsetWriter(Writer writer)
protected booleanshouldEncodeChar(char c)
Should the given character be escaped.
voidstartCDATA()
voidstartDocument()
voidstartDTD(String name, String publicID, String systemID)
voidstartElement(String namespaceURI, String localName, String qName, Attributes attributes)
voidstartEntity(String name)
voidstartPrefixMapping(String prefix, String uri)
voidunparsedEntityDecl(String name, String publicID, String systemID, String notationName)
voidwrite(Attribute attribute)
Writes the given Attribute.
voidwrite(Document doc)

This will print the Document to the current Writer.

voidwrite(Element element)

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

voidwrite(CDATA cdata)
Writes the given CDATA.
voidwrite(Comment comment)
Writes the given Comment.
voidwrite(DocumentType docType)
Writes the given DocumentType.
voidwrite(Entity entity)
Writes the given Entity.
voidwrite(Namespace namespace)
Writes the given Namespace.
voidwrite(ProcessingInstruction processingInstruction)
Writes the given ProcessingInstruction.
voidwrite(String text)

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

voidwrite(Text text)
Writes the given Text.
voidwrite(Node node)
Writes the given Node.
voidwrite(Object object)
Writes the given object which should be a String, a Node or a List of Nodes.
protected voidwriteAttribute(Attribute attribute)
protected voidwriteAttribute(Attributes attributes, int index)
protected voidwriteAttributes(Element element)
Writes the attributes of the given element
protected voidwriteAttributes(Attributes attributes)
protected voidwriteCDATA(String text)
voidwriteClose(Element element)

Writes the closing tag of an Element

protected voidwriteClose(String qualifiedName)
protected voidwriteComment(String text)
protected voidwriteDeclaration()

This will write the declaration to the given Writer.

protected voidwriteDocType(DocumentType docType)
protected voidwriteDocType(String name, String publicID, String systemID)
protected voidwriteElement(Element element)
protected voidwriteElementContent(Element element)
Outputs the content of the given element.
protected voidwriteEmptyElementClose(String qualifiedName)
protected voidwriteEntity(Entity entity)
protected voidwriteEntityRef(String name)
protected voidwriteEscapeAttributeEntities(String txt)
protected voidwriteNamespace(Namespace namespace)
protected voidwriteNamespace(String prefix, String uri)
Writes the SAX namepsaces
protected voidwriteNamespaces()
Writes the SAX namepsaces
protected voidwriteNode(Node node)
protected voidwriteNodeText(Node node)
This method is used to write out Nodes that contain text and still allow for xml:space to be handled properly.
voidwriteOpen(Element element)

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

protected voidwritePrintln()

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

protected voidwriteProcessingInstruction(ProcessingInstruction pi)
protected voidwriteString(String text)

Field Detail

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

LEXICAL_HANDLER_NAMES

protected static final String[] LEXICAL_HANDLER_NAMES

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)

XMLWriter

public XMLWriter(OutputStream out, OutputFormat format)

XMLWriter

public XMLWriter(OutputFormat format)

Method Detail

characters

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

close

public void close()
Closes the underlying Writer

Throws: IOException DOCUMENT ME!

comment

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

createWriter

protected Writer createWriter(OutputStream outStream, String encoding)
Get an OutputStreamWriter, use preferred encoding.

Parameters: outStream DOCUMENT ME! encoding DOCUMENT ME!

Returns: DOCUMENT ME!

Throws: UnsupportedEncodingException DOCUMENT ME!

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!

endCDATA

public void endCDATA()

endDocument

public void endDocument()

endDTD

public void endDTD()

endElement

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

endEntity

public void endEntity(String name)

endPrefixMapping

public void endPrefixMapping(String prefix)

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!

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!

flush

public void flush()
Flushes the underlying Writer

Throws: IOException DOCUMENT ME!

getLexicalHandler

public LexicalHandler getLexicalHandler()

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!

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!

getProperty

public Object getProperty(String name)

handleException

protected void handleException(IOException e)

ignorableWhitespace

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

indent

protected void indent()

installLexicalHandler

protected void installLexicalHandler()

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!

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.

isExpandEmptyElements

protected boolean isExpandEmptyElements()

isNamespaceDeclaration

protected boolean isNamespaceDeclaration(Namespace ns)

notationDecl

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

parse

public void parse(InputSource source)

println

public void println()
Writes the new line text to the underlying Writer

Throws: IOException DOCUMENT ME!

processingInstruction

public void processingInstruction(String target, String data)

resolveEntityRefs

public boolean resolveEntityRefs()

setDocumentLocator

public void setDocumentLocator(Locator locator)

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

setLexicalHandler

public void setLexicalHandler(LexicalHandler handler)

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

setOutputStream

public void setOutputStream(OutputStream out)

setProperty

public void setProperty(String name, Object value)

setResolveEntityRefs

public void setResolveEntityRefs(boolean resolve)

setWriter

public void setWriter(Writer writer)

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

startCDATA

public void startCDATA()

startDocument

public void startDocument()

startDTD

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

startElement

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

startEntity

public void startEntity(String name)

startPrefixMapping

public void startPrefixMapping(String prefix, String uri)

unparsedEntityDecl

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

write

public void write(Attribute attribute)
Writes the given Attribute.

Parameters: attribute Attribute to output.

Throws: IOException DOCUMENT ME!

write

public void write(Document doc)

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)

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)
Writes the given CDATA.

Parameters: cdata CDATA to output.

Throws: IOException DOCUMENT ME!

write

public void write(Comment comment)
Writes the given Comment.

Parameters: comment Comment to output.

Throws: IOException DOCUMENT ME!

write

public void write(DocumentType docType)
Writes the given DocumentType.

Parameters: docType DocumentType to output.

Throws: IOException DOCUMENT ME!

write

public void write(Entity entity)
Writes the given Entity.

Parameters: entity Entity to output.

Throws: IOException DOCUMENT ME!

write

public void write(Namespace namespace)
Writes the given Namespace.

Parameters: namespace Namespace to output.

Throws: IOException DOCUMENT ME!

write

public void write(ProcessingInstruction processingInstruction)
Writes the given ProcessingInstruction.

Parameters: processingInstruction ProcessingInstruction to output.

Throws: IOException DOCUMENT ME!

write

public void write(String text)

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)
Writes the given Text.

Parameters: text Text to output.

Throws: IOException DOCUMENT ME!

write

public void write(Node node)
Writes the given Node.

Parameters: node Node to output.

Throws: IOException DOCUMENT ME!

write

public void write(Object object)
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!

writeAttribute

protected void writeAttribute(Attribute attribute)

writeAttribute

protected void writeAttribute(Attributes attributes, int index)

writeAttributes

protected void writeAttributes(Element element)
Writes the attributes of the given element

Parameters: element DOCUMENT ME!

Throws: IOException DOCUMENT ME!

writeAttributes

protected void writeAttributes(Attributes attributes)

writeCDATA

protected void writeCDATA(String text)

writeClose

public void writeClose(Element element)

Writes the closing tag of an Element

Parameters: element Element to output.

Throws: IOException DOCUMENT ME!

writeClose

protected void writeClose(String qualifiedName)

writeComment

protected void writeComment(String text)

writeDeclaration

protected void writeDeclaration()

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

Throws: IOException DOCUMENT ME!

writeDocType

protected void writeDocType(DocumentType docType)

writeDocType

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

writeElement

protected void writeElement(Element element)

writeElementContent

protected void writeElementContent(Element element)
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!

writeEmptyElementClose

protected void writeEmptyElementClose(String qualifiedName)

writeEntity

protected void writeEntity(Entity entity)

writeEntityRef

protected void writeEntityRef(String name)

writeEscapeAttributeEntities

protected void writeEscapeAttributeEntities(String txt)

writeNamespace

protected void writeNamespace(Namespace namespace)

writeNamespace

protected void writeNamespace(String prefix, String uri)
Writes the SAX namepsaces

Parameters: prefix the prefix uri the namespace uri

Throws: IOException

writeNamespaces

protected void writeNamespaces()
Writes the SAX namepsaces

Throws: IOException DOCUMENT ME!

writeNode

protected void writeNode(Node node)

writeNodeText

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.

Parameters: node DOCUMENT ME!

Throws: IOException DOCUMENT ME!

writeOpen

public void writeOpen(Element element)

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

Parameters: element Element to output.

Throws: IOException DOCUMENT ME!

writePrintln

protected void writePrintln()

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

Throws: IOException DOCUMENT ME!

writeProcessingInstruction

protected void writeProcessingInstruction(ProcessingInstruction pi)

writeString

protected void writeString(String text)
Copyright B) 2005 MetaStuff Ltd. All Rights Reserved. Hosted by

SourceForge