org.dom4j.io

Class XMLWriter

Implemented Interfaces:
LexicalHandler
Known Direct 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 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 $
Authors:
James Strachan
Joseph Bowbeer

Field Summary

protected static OutputFormat
DEFAULT_FORMAT
protected static String[]
LEXICAL_HANDLER_NAMES
protected int
lastOutputNodeType
Stores the last type of node written so algorithms can refer to the previous node type
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(OutputStream out)
XMLWriter(OutputStream out, OutputFormat format)
XMLWriter(Writer writer)
XMLWriter(Writer writer, OutputFormat format)
XMLWriter(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
endDTD()
void
endDocument()
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
startDTD(String name, String publicID, String systemID)
void
startDocument()
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(Object object)
Writes the given object which should be a String, a Node or a List of Nodes.
void
write(String text)
Print out a String, Perfoms the necessary entity escaping and whitespace stripping.
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(ProcessingInstruction processingInstruction)
Writes the given ProcessingInstruction.
void
write(Text text)
Writes the given Text.
protected void
writeAttribute(Attributes attributes, int index)
protected void
writeAttribute(Attribute attribute)
protected void
writeAttributes(Attributes attributes)
protected void
writeAttributes(Element element)
Writes the attributes of the given element
protected void
writeCDATA(String text)
protected void
writeClose(String qualifiedName)
void
writeClose(Element element)
Writes the closing tag of an Element
protected void
writeComment(String text)
protected void
writeDeclaration()
This will write the declaration to the given Writer.
protected void
writeDocType(String name, String publicID, String systemID)
protected void
writeDocType(DocumentType docType)
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(String prefix, String uri)
Writes the SAX namepsaces
protected void
writeNamespace(Namespace namespace)
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)

Field Details

DEFAULT_FORMAT

protected static final OutputFormat DEFAULT_FORMAT

LEXICAL_HANDLER_NAMES

protected static final String[] LEXICAL_HANDLER_NAMES

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 Details

XMLWriter

public XMLWriter()

XMLWriter

public XMLWriter(OutputStream out)
            throws UnsupportedEncodingException

XMLWriter

public XMLWriter(OutputStream out,
                 OutputFormat format)
            throws UnsupportedEncodingException

XMLWriter

public XMLWriter(Writer writer)

XMLWriter

public XMLWriter(Writer writer,
                 OutputFormat format)

XMLWriter

public XMLWriter(OutputFormat format)
            throws UnsupportedEncodingException

Method Details

characters

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

close

public void close()
            throws IOException
Closes the underlying Writer

comment

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

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!

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()
            throws SAXException

endDTD

public void endDTD()
            throws SAXException

endDocument

public void endDocument()
            throws SAXException

endElement

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

endEntity

public void endEntity(String name)
            throws SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
            throws SAXException

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()
            throws IOException
Flushes the underlying Writer

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)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException

handleException

protected void handleException(IOException e)
            throws SAXException

ignorableWhitespace

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

indent

protected void indent()
            throws IOException

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)
            throws SAXException

parse

public void parse(InputSource source)
            throws IOException,
                   SAXException

println

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

processingInstruction

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

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)
            throws UnsupportedEncodingException

setProperty

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

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()
            throws SAXException

startDTD

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

startDocument

public void startDocument()
            throws SAXException

startElement

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

startEntity

public void startEntity(String name)
            throws SAXException

startPrefixMapping

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

unparsedEntityDecl

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

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.

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

write

public void write(Attribute attribute)
            throws IOException
Writes the given Attribute.
Parameters:
attribute - Attribute to output.

write

public void write(CDATA cdata)
            throws IOException
Writes the given CDATA.
Parameters:
cdata - CDATA to output.

write

public void write(Comment comment)
            throws IOException
Writes the given Comment.
Parameters:
comment - Comment to output.

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.

write

public void write(DocumentType docType)
            throws IOException
Writes the given DocumentType.
Parameters:
docType - DocumentType to output.

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.

write

public void write(Entity entity)
            throws IOException
Writes the given Entity.
Parameters:
entity - Entity to output.

write

public void write(Namespace namespace)
            throws IOException
Writes the given Namespace.
Parameters:
namespace - Namespace to output.

write

public void write(Node node)
            throws IOException
Writes the given Node.
Parameters:
node - Node to output.

write

public void write(ProcessingInstruction processingInstruction)
            throws IOException
Writes the given ProcessingInstruction.
Parameters:
processingInstruction - ProcessingInstruction to output.

write

public void write(Text text)
            throws IOException
Writes the given Text.
Parameters:
text - Text to output.

writeAttribute

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

writeAttribute

protected void writeAttribute(Attribute attribute)
            throws IOException

writeAttributes

protected void writeAttributes(Attributes attributes)
            throws IOException

writeAttributes

protected void writeAttributes(Element element)
            throws IOException
Writes the attributes of the given element
Parameters:
element - DOCUMENT ME!

writeCDATA

protected void writeCDATA(String text)
            throws IOException

writeClose

protected void writeClose(String qualifiedName)
            throws IOException

writeClose

public void writeClose(Element element)
            throws IOException
Writes the closing tag of an Element
Parameters:
element - Element to output.

writeComment

protected void writeComment(String text)
            throws IOException

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.

writeDocType

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

writeDocType

protected void writeDocType(DocumentType docType)
            throws IOException

writeElement

protected void writeElement(Element element)
            throws IOException

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!

writeEmptyElementClose

protected void writeEmptyElementClose(String qualifiedName)
            throws IOException

writeEntity

protected void writeEntity(Entity entity)
            throws IOException

writeEntityRef

protected void writeEntityRef(String name)
            throws IOException

writeEscapeAttributeEntities

protected void writeEscapeAttributeEntities(String txt)
            throws IOException

writeNamespace

protected void writeNamespace(String prefix,
                              String uri)
            throws IOException
Writes the SAX namepsaces
Parameters:
prefix - the prefix
uri - the namespace uri

writeNamespace

protected void writeNamespace(Namespace namespace)
            throws IOException

writeNamespaces

protected void writeNamespaces()
            throws IOException
Writes the SAX namepsaces

writeNode

protected void writeNode(Node node)
            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!

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.

writePrintln

protected void writePrintln()
            throws IOException
This will print a new line only if the newlines flag was set to true

writeProcessingInstruction

protected void writeProcessingInstruction(ProcessingInstruction pi)
            throws IOException

writeString

protected void writeString(String text)
            throws IOException

Copyright B) 2005 MetaStuff Ltd. All Rights Reserved. Hosted by

SourceForge Logo