public class XMLWriter
extends org.xml.sax.helpers.XMLFilterImpl
This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.
The client creates a document by invoking the methods for
standard SAX2 events, always beginning with the
startDocument
method and ending with
the endDocument
method. There are convenience
methods provided so that clients to not have to create empty
attribute lists or provide empty strings as parameters; for
example, the method invocation
w.startElement("foo");
is equivalent to the regular SAX2 ContentHandler method
w.startElement("", "foo", "", new AttributesImpl());
Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output:
XMLWriter w = new XMLWriter(); w.startDocument(); w.startElement("greeting"); w.characters("Hello, world!"); w.endElement("greeting"); w.endDocument();
The resulting document will look like this:
<?xml version="1.0" standalone="yes"?> <greeting>Hello, world!</greeting>
In fact, there is an even simpler convenience method, dataElement, designed for writing elements that contain only character data, so the code to generate the document could be shortened to
XMLWriter w = new XMLWriter(); w.startDocument(); w.dataElement("greeting", "Hello, world!"); w.endDocument();
According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in
w.dataElement("item", "1"); w.dataElement("item", "2"); w.dataElement("item", "3");
you will end up with
<item>1</item><item>3</item><item>3</item>
You need to invoke one of the characters methods
explicitly to add newlines or indentation. Alternatively, you
can use DataWriter
, which
is derived from this class -- it is optimized for writing
purely data-oriented (or field-oriented) XML, and does automatic
linebreaks and indentation (but does not support mixed content
properly).
The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example:
w.startDocument(); w.emptyElement("http://www.foo.com/ns/", "foo"); w.endDocument();
The resulting document will look like this:
<?xml version="1.0" standalone="yes"?> <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>
In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:
setPrefix
method.Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).
Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method:
w.setPrefix("http://www.foo.com/ns/", "foo"); w.startDocument(); w.emptyElement("http://www.foo.com/ns/", "foo"); w.endDocument();
The resulting document will look like this:
<?xml version="1.0" standalone="yes"?> <foo:foo xmlns:foo="http://www.foo.com/ns/"/>
The default Namespace simply uses an empty string as the prefix:
w.setPrefix("http://www.foo.com/ns/", ""); w.startDocument(); w.emptyElement("http://www.foo.com/ns/", "foo"); w.endDocument();
The resulting document will look like this:
<?xml version="1.0" standalone="yes"?> <foo xmlns="http://www.foo.com/ns/"/>
By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example:
<xml version="1.0" standalone="yes"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> <rdf:Description about="http://www.foo.com/ids/books/12345"> <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title> <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title> <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title> </rdf:Description> </rdf:RDF>
The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there:
w.forceNSDecl("http://www.purl.org/dc/");
Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants:
<xml version="1.0" standalone="yes"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://www.purl.org/dc/"> <rdf:Description about="http://www.foo.com/ids/books/12345"> <dc:title>A Dark Night</dc:title> <dc:creator>Jane Smith</dc:title> <dc:date>2000-09-09</dc:title> </rdf:Description> </rdf:RDF>
This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.
XMLFilter
,
Changed private to protected on several methods to allow subclassing.
Added methods to allow disabling entity conversion of characters
outside lower Ascii range.
Allow setting output doctype name (DTD).
Use system platform end-of-line sequence instead of just \n.
Use generics for hash tables.
Philip R. Burns. 2007/04/23 .
Modifier and Type | Field and Description |
---|---|
protected static java.lang.String |
LINE_SEPARATOR
Line separator.
|
Constructor and Description |
---|
XMLWriter()
Create a new XML writer.
|
XMLWriter(java.io.Writer writer)
Create a new XML writer.
|
XMLWriter(org.xml.sax.XMLReader xmlreader)
Create a new XML writer.
|
XMLWriter(org.xml.sax.XMLReader xmlreader,
java.io.Writer writer)
Create a new XML writer.
|
Modifier and Type | Method and Description |
---|---|
void |
characters(char[] ch,
int start,
int len)
Write character data.
|
void |
characters(java.lang.String data)
Write a string of character data, with XML escaping.
|
void |
dataElement(java.lang.String localName,
java.lang.String content)
Write an element with character data content but no attributes or Namespace URI.
|
void |
dataElement(java.lang.String uri,
java.lang.String localName,
java.lang.String content)
Write an element with character data content but no attributes.
|
void |
dataElement(java.lang.String uri,
java.lang.String localName,
java.lang.String qName,
org.xml.sax.Attributes atts,
java.lang.String content)
Write an element with character data content.
|
void |
emptyElement(java.lang.String localName)
Add an empty element without a Namespace URI, qname or attributes.
|
void |
emptyElement(java.lang.String uri,
java.lang.String localName)
Add an empty element without a qname or attributes.
|
void |
emptyElement(java.lang.String uri,
java.lang.String localName,
java.lang.String qName,
org.xml.sax.Attributes atts)
Write an empty element.
|
void |
endDocument()
Write a newline at the end of the document.
|
void |
endElement(java.lang.String localName)
End an element without a Namespace URI or qname.
|
void |
endElement(java.lang.String uri,
java.lang.String localName)
End an element without a qname.
|
void |
endElement(java.lang.String uri,
java.lang.String localName,
java.lang.String qName)
Write an end tag.
|
void |
flush()
Flush the output.
|
void |
forceNSDecl(java.lang.String uri)
Force a Namespace to be declared on the root element.
|
void |
forceNSDecl(java.lang.String uri,
java.lang.String prefix)
Force a Namespace declaration with a preferred prefix.
|
java.lang.String |
getPrefix(java.lang.String uri)
Get the current or preferred prefix for a Namespace URI.
|
void |
ignorableWhitespace(char[] ch,
int start,
int length)
Write ignorable whitespace.
|
void |
processingInstruction(java.lang.String target,
java.lang.String data)
Write a processing instruction.
|
void |
reset()
Reset the writer.
|
void |
setDoctype(java.lang.String doctypeName,
java.lang.String doctypeSystem)
Set the doctype name and system.
|
void |
setOutput(java.io.Writer writer)
Set a new output destination for the document.
|
void |
setOutputCharsAsIs(boolean outputCharsAsIs)
Enable or disable character conversion to entity references.
|
void |
setPrefix(java.lang.String uri,
java.lang.String prefix)
Specify a preferred prefix for a Namespace URI.
|
void |
startDocument()
Write the XML declaration at the beginning of the document.
|
void |
startElement(java.lang.String localName)
Start a new element without a qname, attributes or a Namespace URI.
|
void |
startElement(java.lang.String uri,
java.lang.String localName)
Start a new element without a qname or attributes.
|
void |
startElement(java.lang.String uri,
java.lang.String localName,
java.lang.String qName,
org.xml.sax.Attributes atts)
Write a start tag.
|
protected void |
write(char c)
Write a raw character.
|
protected void |
write(java.lang.String s)
Write a raw string.
|
protected void |
writeEsc(char[] ch,
int start,
int length,
boolean isAttVal)
Write an array of data characters with escaping.
|
endPrefixMapping, error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, notationDecl, parse, parse, resolveEntity, setContentHandler, setDocumentLocator, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, setProperty, skippedEntity, startPrefixMapping, unparsedEntityDecl, warning
public XMLWriter()
Write to standard output.
public XMLWriter(java.io.Writer writer)
Write to the writer provided.
writer
- The output destination, or null to use standard
output.public XMLWriter(org.xml.sax.XMLReader xmlreader)
Use the specified XML reader as the parent.
xmlreader
- The parent in the filter chain, or null
for no parent.public XMLWriter(org.xml.sax.XMLReader xmlreader, java.io.Writer writer)
Use the specified XML reader as the parent, and write to the specified writer.
xmlreader
- The parent in the filter chain, or null
for no parent.writer
- The output destination, or null to use standard
output.public void reset()
This method is especially useful if the writer throws an
exception before it is finished, and you want to reuse the
writer for a new document. It is usually a good idea to
invoke flush
before resetting the writer,
to make sure that no output is lost.
This method is invoked automatically by the
startDocument
method before writing
a new document.
Note: this method will not clear the prefix or URI information in the writer or the selected output writer.
flush()
public void flush() throws java.io.IOException
This method flushes the output stream. It is especially useful when you need to make certain that the entire document has been written to output but do not want to close the output stream.
This method is invoked automatically by the
endDocument
method after writing a
document.
java.io.IOException
reset()
public void setOutput(java.io.Writer writer)
writer
- The output destination, or null to use
standard output.flush()
public void setDoctype(java.lang.String doctypeName, java.lang.String doctypeSystem)
doctypeName
- The doctype name.doctypeSystem
- The doctype system.public void setPrefix(java.lang.String uri, java.lang.String prefix)
Note that this method does not actually force the Namespace
to be declared; to do that, use the forceNSDecl
method as well.
uri
- The Namespace URI.prefix
- The preferred prefix, or "" to select
the default Namespace.getPrefix(java.lang.String)
,
forceNSDecl(java.lang.String)
,
forceNSDecl(java.lang.String,java.lang.String)
public java.lang.String getPrefix(java.lang.String uri)
uri
- The Namespace URI.setPrefix(java.lang.String, java.lang.String)
public void forceNSDecl(java.lang.String uri)
By default, the XMLWriter will declare only the Namespaces needed for an element; as a result, a Namespace may be declared many places in a document if it is not used on the root element.
This method forces a Namespace to be declared on the root element even if it is not used there, and reduces the number of xmlns attributes in the document.
uri
- The Namespace URI to declare.forceNSDecl(java.lang.String,java.lang.String)
,
setPrefix(java.lang.String, java.lang.String)
public void forceNSDecl(java.lang.String uri, java.lang.String prefix)
This is a convenience method that invokes setPrefix
then forceNSDecl
.
uri
- The Namespace URI to declare on the root element.prefix
- The preferred prefix for the Namespace, or ""
for the default Namespace.setPrefix(java.lang.String, java.lang.String)
,
forceNSDecl(java.lang.String)
public void startDocument() throws org.xml.sax.SAXException
startDocument
in interface org.xml.sax.ContentHandler
startDocument
in class org.xml.sax.helpers.XMLFilterImpl
org.xml.sax.SAXException
- If there is an error
writing the XML declaration, or if a handler further down
the filter chain raises an exception.ContentHandler.startDocument()
public void endDocument() throws org.xml.sax.SAXException
endDocument
in interface org.xml.sax.ContentHandler
endDocument
in class org.xml.sax.helpers.XMLFilterImpl
org.xml.sax.SAXException
- If there is an error
writing the newline, or if a handler further down
the filter chain raises an exception.ContentHandler.endDocument()
public void startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts) throws org.xml.sax.SAXException
startElement
in interface org.xml.sax.ContentHandler
startElement
in class org.xml.sax.helpers.XMLFilterImpl
uri
- The Namespace URI, or the empty string if none
is available.localName
- The element's local (unprefixed) name (required).qName
- The element's qualified (prefixed) name, or the
empty string is none is available. This method will
use the qName as a template for generating a prefix
if necessary, but it is not guaranteed to use the
same qName.atts
- The element's attribute list (must not be null).org.xml.sax.SAXException
- If there is an error
writing the start tag, or if a handler further down
the filter chain raises an exception.ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
public void endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName) throws org.xml.sax.SAXException
endElement
in interface org.xml.sax.ContentHandler
endElement
in class org.xml.sax.helpers.XMLFilterImpl
uri
- The Namespace URI, or the empty string if none
is available.localName
- The element's local (unprefixed) name (required).qName
- The element's qualified (prefixed) name, or the
empty string is none is available. This method will
use the qName as a template for generating a prefix
if necessary, but it is not guaranteed to use the
same qName.org.xml.sax.SAXException
- If there is an error
writing the end tag, or if a handler further down
the filter chain raises an exception.ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)
public void characters(char[] ch, int start, int len) throws org.xml.sax.SAXException
characters
in interface org.xml.sax.ContentHandler
characters
in class org.xml.sax.helpers.XMLFilterImpl
ch
- The array of characters to write.start
- The starting position in the array.len
- The number of characters to write.org.xml.sax.SAXException
- If there is an error
writing the characters, or if a handler further down
the filter chain raises an exception.ContentHandler.characters(char[], int, int)
public void ignorableWhitespace(char[] ch, int start, int length) throws org.xml.sax.SAXException
ignorableWhitespace
in interface org.xml.sax.ContentHandler
ignorableWhitespace
in class org.xml.sax.helpers.XMLFilterImpl
ch
- The array of characters to write.start
- The starting position in the array.length
- The number of characters to write.org.xml.sax.SAXException
- If there is an error
writing the whitespace, or if a handler further down
the filter chain raises an exception.ContentHandler.ignorableWhitespace(char[], int, int)
public void processingInstruction(java.lang.String target, java.lang.String data) throws org.xml.sax.SAXException
processingInstruction
in interface org.xml.sax.ContentHandler
processingInstruction
in class org.xml.sax.helpers.XMLFilterImpl
target
- The PI target.data
- The PI data.org.xml.sax.SAXException
- If there is an error
writing the PI, or if a handler further down
the filter chain raises an exception.ContentHandler.processingInstruction(java.lang.String, java.lang.String)
public void emptyElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts) throws org.xml.sax.SAXException
startElement
and an endElement
event will
be passed on down the filter chain.uri
- The element's Namespace URI, or the empty string
if the element has no Namespace or if Namespace
processing is not being performed.localName
- The element's local name (without prefix). This
parameter must be provided.qName
- The element's qualified name (with prefix), or
the empty string if none is available. This parameter
is strictly advisory: the writer may or may not use
the prefix attached.atts
- The element's attribute list.org.xml.sax.SAXException
- If there is an error
writing the empty tag, or if a handler further down
the filter chain raises an exception.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
,
endElement(java.lang.String, java.lang.String, java.lang.String)
public void startElement(java.lang.String uri, java.lang.String localName) throws org.xml.sax.SAXException
This method will provide a default empty attribute
list and an empty string for the qualified name.
It invokes startElement(String, String, String, Attributes)
directly.
uri
- The element's Namespace URI.localName
- The element's local name.org.xml.sax.SAXException
- If there is an error
writing the start tag, or if a handler further down
the filter chain raises an exception.startElement(String, String, String, Attributes)
public void startElement(java.lang.String localName) throws org.xml.sax.SAXException
This method will provide an empty string for the Namespace URI, and empty string for the qualified name, and a default empty attribute list. It invokes #startElement(String, String, String, Attributes)} directly.
localName
- The element's local name.org.xml.sax.SAXException
- If there is an error
writing the start tag, or if a handler further down
the filter chain raises an exception.startElement(String, String, String, Attributes)
public void endElement(java.lang.String uri, java.lang.String localName) throws org.xml.sax.SAXException
This method will supply an empty string for the qName.
It invokes endElement(String, String, String)
directly.
uri
- The element's Namespace URI.localName
- The element's local name.org.xml.sax.SAXException
- If there is an error
writing the end tag, or if a handler further down
the filter chain raises an exception.endElement(String, String, String)
public void endElement(java.lang.String localName) throws org.xml.sax.SAXException
This method will supply an empty string for the qName
and an empty string for the Namespace URI.
It invokes endElement(String, String, String)
directly.
localName
- The element's local name.org.xml.sax.SAXException
- If there is an error
writing the end tag, or if a handler further down
the filter chain raises an exception.endElement(String, String, String)
public void emptyElement(java.lang.String uri, java.lang.String localName) throws org.xml.sax.SAXException
This method will supply an empty string for the qname
and an empty attribute list. It invokes
emptyElement(String, String, String, Attributes)
directly.
uri
- The element's Namespace URI.localName
- The element's local name.org.xml.sax.SAXException
- If there is an error
writing the empty tag, or if a handler further down
the filter chain raises an exception.emptyElement(String, String, String, Attributes)
public void emptyElement(java.lang.String localName) throws org.xml.sax.SAXException
This method will supply an empty string for the qname,
and empty string for the Namespace URI, and an empty
attribute list. It invokes
emptyElement(String, String, String, Attributes)
directly.
localName
- The element's local name.org.xml.sax.SAXException
- If there is an error
writing the empty tag, or if a handler further down
the filter chain raises an exception.emptyElement(String, String, String, Attributes)
public void dataElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts, java.lang.String content) throws org.xml.sax.SAXException
This is a convenience method to write a complete element with character data content, including the start tag and end tag.
This method invokes
startElement(String, String, String, Attributes)
,
followed by
characters(String)
, followed by
endElement(String, String, String)
.
uri
- The element's Namespace URI.localName
- The element's local name.qName
- The element's default qualified name.atts
- The element's attributes.content
- The character data content.org.xml.sax.SAXException
- If there is an error
writing the empty tag, or if a handler further down
the filter chain raises an exception.startElement(String, String, String, Attributes)
,
characters(String)
,
endElement(String, String, String)
public void dataElement(java.lang.String uri, java.lang.String localName, java.lang.String content) throws org.xml.sax.SAXException
This is a convenience method to write a complete element with character data content, including the start tag and end tag. This method provides an empty string for the qname and an empty attribute list.
This method invokes
startElement(String, String, String, Attributes)
,
followed by
characters(String)
, followed by
endElement(String, String, String)
.
uri
- The element's Namespace URI.localName
- The element's local name.content
- The character data content.org.xml.sax.SAXException
- If there is an error
writing the empty tag, or if a handler further down
the filter chain raises an exception.startElement(String, String, String, Attributes)
,
characters(String)
,
endElement(String, String, String)
public void dataElement(java.lang.String localName, java.lang.String content) throws org.xml.sax.SAXException
This is a convenience method to write a complete element with character data content, including the start tag and end tag. The method provides an empty string for the Namespace URI, and empty string for the qualified name, and an empty attribute list.
This method invokes
startElement(String, String, String, Attributes)
,
followed by
characters(String)
, followed by
endElement(String, String, String)
.
localName
- The element's local name.content
- The character data content.org.xml.sax.SAXException
- If there is an error
writing the empty tag, or if a handler further down
the filter chain raises an exception.startElement(String, String, String, Attributes)
,
characters(String)
,
endElement(String, String, String)
public void characters(java.lang.String data) throws org.xml.sax.SAXException
This is a convenience method that takes an XML
String, converts it to a character array, then invokes
characters(char[], int, int)
.
data
- The character data.org.xml.sax.SAXException
- If there is an error
writing the string, or if a handler further down
the filter chain raises an exception.characters(char[], int, int)
public void setOutputCharsAsIs(boolean outputCharsAsIs)
outputCharsAsIs
- True to disable conversion of
characters outside lower Ascii
range to entity reference form
(e.g., nnn; ).protected void write(char c) throws org.xml.sax.SAXException
c
- The character to write.org.xml.sax.SAXException
- If there is an error writing
the character, this method will throw an IOException
wrapped in a SAXException.protected void write(java.lang.String s) throws org.xml.sax.SAXException
s
- org.xml.sax.SAXException
- If there is an error writing
the string, this method will throw an IOException
wrapped in a SAXExceptionprotected void writeEsc(char[] ch, int start, int length, boolean isAttVal) throws org.xml.sax.SAXException
ch
- The array of characters.start
- The starting position.length
- The number of characters to use.isAttVal
- true if this is an attribute value literal.org.xml.SAXException
- If there is an error writing
the characters, this method will throw an
IOException wrapped in a SAXException.org.xml.sax.SAXException