public class XMLWriter extends org.xml.sax.helpers.XMLFilterImpl
Changes:
System.getProperty("line.separator")
for creation of new
lines.The following documentation from the XMLWriter class still applies:
=====================
Filter to write an XML document from a SAX event stream.
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 do 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 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.
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.
The default Namespace simply uses an empty string as the prefix.
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.
XMLFilterImpl
,
ContentHandler
Constructor and Description |
---|
XMLWriter(Writer writer,
String encoding)
Create a new XML writer.
|
XMLWriter(XMLReader xmlreader,
Writer writer,
String encoding)
Create a new XML writer.
|
Modifier and Type | Method and Description |
---|---|
void |
characters(char[] ch,
int start,
int len)
If we are inside an element, append the character data to an internal
buffer.
|
void |
characters(String data)
Write a string of character data, with XML escaping.
|
void |
close() |
void |
comment(String comment)
Convenience mechanism to write a comment.
|
void |
dataElement(String localName,
String content)
Write an element with character data content but no attributes or
Namespace URI.
|
void |
dataElement(String localName,
String content,
DiffElement.Operation op) |
void |
dataElement(String uri,
String localName,
String content)
Write an element with character data content but no attributes.
|
void |
dataElement(String uri,
String localName,
String qName,
Attributes atts,
String content)
Write an element with character data content.
|
void |
dataElement(String localName,
String content,
String attributeName,
String attributeValue) |
void |
dataElement(String localName,
String content,
String attributeName,
String attributeValue,
DiffElement.Operation op) |
void |
dataElement(String uri,
String localName,
String content,
String attributeName,
String attributeValue) |
void |
emptyElement(String localName,
Attributes atts)
Write an element with character data content, wrapped within CDATA.
|
void |
emptyElement(String localName,
String attributeName,
String attributeValue) |
void |
emptyElement(String uri,
String localName,
String qName,
Attributes atts) |
void |
emptyElement(String localName,
String attributeName,
String attributeValue,
DiffElement.Operation op) |
void |
endDocument()
Write a newline at the end of the document.
|
void |
endElement(String localName)
End an element without a Namespace URI or qname.
|
void |
endElement(String uri,
String localName)
End an element without a qname.
|
void |
endElement(String uri,
String localName,
String qName)
Writes and emits character content reported for the element.
|
void |
flush()
Flush the output.
|
void |
forceNSDecl(String uri)
Force a Namespace to be declared on the root element.
|
void |
forceNSDecl(String uri,
String prefix)
Force a Namespace declaration with a preferred prefix.
|
int |
getIndentStep()
Return the current indent step.
|
String |
getPrefix(String uri)
Get the current or preferred prefix for a Namespace URI.
|
void |
ignorableWhitespace(char[] ch,
int start,
int length)
Ignorable whitespace is NOT written.
|
void |
processingInstruction(String target,
String data)
Writes a processing instruction.
|
void |
reset()
Reset the writer.
|
void |
setIndentStep(int indentStep)
Set the current indent step.
|
protected void |
setOutput(Writer writer)
Set the output destination for the document.
|
void |
setPrefix(String uri,
String prefix)
Specify a preferred prefix for a Namespace URI.
|
void |
startDocument()
Writes the XML declaration at the beginning of the document.
|
void |
startElement(String localName)
Start a new element without a qname, attributes or a Namespace URI.
|
void |
startElement(String uri,
String localName)
Start a new element without a qname or attributes.
|
void |
startElement(String localName,
String attributeName,
String attributeValue)
Convenience method: start an element with only local name and a single
attribute.
|
void |
startElement(String uri,
String localName,
String qName,
Attributes atts)
Write a start tag.
|
void |
startElement(String localName,
String attributeName,
String attributeValue,
DiffElement.Operation op)
Convenience method: start an element with only local name and a single
attribute.
|
void |
startElement(String uri,
String localName,
String attributeName,
String attributeValue)
Convenience method: start an element with a single attribute.
|
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
protected Writer output
public XMLWriter(Writer writer, String encoding)
Write to the writer provided. The writer must already be configured to use the correct character encoding.
writer
- The output destination, or null to use standard output.encoding
- Content to be placed in the "encoding" attribute of the xml
processing instruction that will be written at the start of
the document. Defaults to "UTF-8".public XMLWriter(XMLReader xmlreader, Writer writer, String encoding)
Use the specified XML reader as the parent, and write to the specified writer. The writer must already be configured to use the correct character encoding.
xmlreader
- The parent in the filter chain, or null for no parent.writer
- The output destination, or null to use standard output.encoding
- Content to be placed in the "encoding" attribute of the xml
processing instruction that will be written at the start of
the document. Defaults to "UTF-8".public int getIndentStep()
Return the current indent step: each start tag will be indented by this number of spaces times the number of ancestors that the element has.
setIndentStep(int)
public void setIndentStep(int indentStep)
indentStep
- The new indent step (0 or less for no indentation).getIndentStep()
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 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.
IOException
reset()
public void close() throws IOException
IOException
protected void setOutput(Writer writer)
writer
- The output destination, or null to use standard output.flush()
public void setPrefix(String uri, 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 String getPrefix(String uri)
uri
- The Namespace URI.setPrefix(java.lang.String, java.lang.String)
public void forceNSDecl(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(String uri, 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 SAXException
Passes the event on down the filter chain for further processing.
startDocument
in interface ContentHandler
startDocument
in class org.xml.sax.helpers.XMLFilterImpl
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 SAXException
endDocument
in interface ContentHandler
endDocument
in class org.xml.sax.helpers.XMLFilterImpl
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(String uri, String localName, String qName, Attributes atts) throws SAXException
startElement
in interface 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).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 startElement(String localName, String attributeName, String attributeValue) throws SAXException
localName
- attributeName
- attributeValue
- SAXException
public void startElement(String uri, String localName, String attributeName, String attributeValue) throws SAXException
uri
- localName
- attributeName
- attributeValue
- SAXException
public void startElement(String localName, String attributeName, String attributeValue, DiffElement.Operation op) throws SAXException
localName
- attributeName
- attributeValue
- op
- SAXException
public void endElement(String uri, String localName, String qName) throws SAXException
Passes the endElement event on down the filter chain for further processing.
endElement
in interface 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.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 SAXException
Ignore character data that is between end and start elements (e.g. line feeds).
Only character data of element content is ultimately passed on down the filter chain for further processing (with leading and trailing whitespace trimmed).
characters
in interface ContentHandler
characters
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.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 SAXException
However, the event is passed on down the filter chain for further processing.
ignorableWhitespace
in interface 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.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(String target, String data) throws SAXException
Passes the event on down the filter chain for further processing.
processingInstruction
in interface ContentHandler
processingInstruction
in class org.xml.sax.helpers.XMLFilterImpl
target
- The PI target.data
- The PI data.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 comment(String comment) throws SAXException
comment
- SAXException
public void startElement(String uri, String localName) throws 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.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(String localName) throws 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.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(String uri, String localName) throws 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.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(String localName) throws 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.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 dataElement(String uri, String localName, String qName, Attributes atts, String content) throws 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.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 emptyElement(String localName, Attributes atts) throws 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)
(within CDATA), 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.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 emptyElement(String localName, String attributeName, String attributeValue) throws SAXException
SAXException
public void emptyElement(String localName, String attributeName, String attributeValue, DiffElement.Operation op) throws SAXException
SAXException
public void emptyElement(String uri, String localName, String qName, Attributes atts) throws SAXException
SAXException
public void dataElement(String uri, String localName, String content) throws 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.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(String localName, String content) throws 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.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(String localName, String content, DiffElement.Operation op) throws SAXException
SAXException
public void dataElement(String localName, String content, String attributeName, String attributeValue) throws SAXException
SAXException
public void dataElement(String uri, String localName, String content, String attributeName, String attributeValue) throws SAXException
SAXException
public void dataElement(String localName, String content, String attributeName, String attributeValue, DiffElement.Operation op) throws SAXException
SAXException
public void characters(String data) throws 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.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)
Copyright © 2017. All rights reserved.