JAXB OSGI 4.0.9 · com.sun.xml.txw2.output.XMLWriter · APIdia, the JavaDoc alternative

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 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();

Whitespace

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

Namespace Support

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:

the qualified name
the startPrefixMapping(String, String) 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.

Field Summary

Modifier and Type	Field and Description
private int	elementLevel
private final Attributes	EMPTY_ATTS
private String	encoding
private final CharacterEscapeHandler	escapeHandler
private String	header This string will be written right after the xml declaration without any escaping.
private boolean	inCDATA
private final Map<String, String>	locallyDeclaredPrefix
private Writer	output
private boolean	startTagIsClosed
private boolean	writeXmlDecl

Constructor Summary

Access	Constructor and Description
public	XMLWriter(Writer The output destination, or null to use standard output. writer, String If non-null string is specified, it is written as a part of the XML declaration. encoding, CharacterEscapeHandler escape handler _escapeHandler) Create a new XML writer.
public	XMLWriter(Writer writer, String encoding)

Method Summary

Modifier and Type	Method and Description
public void	characters(char[] The array of characters to write. ch, int The starting position in the array. start, int The number of characters to write. len) Overrides org.xml.sax.helpers.XMLFilterImpl.characters. Implements org.xml.sax.ContentHandler.characters. Write character data.
public void	characters(String The character data. data) Write a string of character data, with XML escaping.
public void	comment(char[] ch, int start, int length) Implements org.xml.sax.ext.LexicalHandler.comment. Report an XML comment anywhere in the document.
public void	dataElement(String The element's Namespace URI. uri, String The element's local name. localName, String The element's default qualified name. qName, Attributes The element's attributes. atts, String The character data content. content) Write an element with character data content.
public void	dataElement(String The element's Namespace URI. uri, String The element's local name. localName, String The character data content. content) Write an element with character data content but no attributes.
public void	dataElement(String The element's local name. localName, String The character data content. content) Write an element with character data content but no attributes or Namespace URI.
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. Write a newline at the end of the document.
public void	endDTD() Implements org.xml.sax.ext.LexicalHandler.endDTD. Report the end of DTD declarations.
public void	endElement(String The Namespace URI, or the empty string if none is available. uri, String The element's local (unprefixed) name (required). localName, String 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. qName) Overrides org.xml.sax.helpers.XMLFilterImpl.endElement. Implements org.xml.sax.ContentHandler.endElement. Write an end tag.
public void	endElement(String The element's Namespace URI. uri, String The element's local name. localName) End an element without a qname.
public void	endElement(String The element's local name. localName) End an element without a Namespace URI or qname.
public void	endEntity(String name) Implements org.xml.sax.ext.LexicalHandler.endEntity. Report the end of an entity.
public void	flush() Flush the output.
public void	ignorableWhitespace(char[] The array of characters to write. ch, int The starting position in the array. start, int The number of characters to write. length) Overrides org.xml.sax.helpers.XMLFilterImpl.ignorableWhitespace. Implements org.xml.sax.ContentHandler.ignorableWhitespace. Write ignorable whitespace.
private void	init(Writer The output destination, or null to use standard output. writer, String encoding) Internal initialization method.
public void	processingInstruction(String The PI target. target, String The PI data. data) Overrides org.xml.sax.helpers.XMLFilterImpl.processingInstruction. Implements org.xml.sax.ContentHandler.processingInstruction. Write a processing instruction.
public void	reset() Reset the writer.
public void	setEncoding(String encoding)
public void	setHeader(String passing null will work as if the empty string is passed. _header) Sets the header string.
public void	setOutput(Writer The output destination, or null to use standard output. writer, String If non-null string is specified, it is written as a part of the XML declaration. _encoding) Set a new output destination for the document.
public void	setXmlDecl(boolean write out the XML declaration _writeXmlDecl) Set whether the writer should print out the XML declaration (`<?xml version='1.0' ...`
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. Write the XML declaration at the beginning of the document.
public void	startDTD(String name, String publicId, String systemId) Implements org.xml.sax.ext.LexicalHandler.startDTD. Report the start of DTD declarations, if any.
public void	startElement(String The Namespace URI, or the empty string if none is available. uri, String The element's local (unprefixed) name (required). localName, String 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. qName, Attributes The element's attribute list (must not be null). atts) Overrides org.xml.sax.helpers.XMLFilterImpl.startElement. Implements org.xml.sax.ContentHandler.startElement. Write a start tag.
public void	startElement(String The element's Namespace URI. uri, String The element's local name. localName) Start a new element without a qname or attributes.
public void	startElement(String The element's local name. localName) Start a new element without a qname, attributes or a Namespace URI.
public void	startEntity(String name) Implements org.xml.sax.ext.LexicalHandler.startEntity. Report the beginning of some internal and external XML entities.
public void	startPrefixMapping(String prefix, String uri) Overrides org.xml.sax.helpers.XMLFilterImpl.startPrefixMapping. Implements org.xml.sax.ContentHandler.startPrefixMapping. Filter a start Namespace prefix mapping event.
private void	write(char The character to write. c) Write a raw character.
private void	write(String s) Write a raw string.
private void	writeAttributes(Attributes The attribute list to write. atts) Write out an attribute list, escaping values.
private void	writeEsc(char[] The array of characters. ch, int The starting position. start, int The number of characters to use. length, boolean true if this is an attribute value literal. isAttVal) Write an array of data characters with escaping.
private void	writeName(String The Namespace URI. uri, String The local name. localName, String The prefixed name, if available, or the empty string. qName, boolean true if this is an element name, false if it is an attribute name. isElement) Write an element or attribute name.

Field Detail

elementLevel	back to summary
private int elementLevel

EMPTY_ATTS	back to summary
private final Attributes EMPTY_ATTS

encoding	back to summary
private String encoding

escapeHandler	back to summary
private final CharacterEscapeHandler escapeHandler

header	back to summary
private String header This string will be written right after the xml declaration without any escaping. Useful for generating a boiler-plate DOCTYPE decl , PIs, and comments.

header

back to summary

private String header

This string will be written right after the xml declaration without any escaping. Useful for generating a boiler-plate DOCTYPE decl , PIs, and comments.

inCDATA	back to summary
private boolean inCDATA

locallyDeclaredPrefix	back to summary
private final Map<String, String> locallyDeclaredPrefix

output	back to summary
private Writer output

startTagIsClosed	back to summary
private boolean startTagIsClosed

writeXmlDecl	back to summary
private boolean writeXmlDecl

Constructor Detail

XMLWriter	back to summary
public XMLWriter(Writer writer, String encoding, CharacterEscapeHandler _escapeHandler) Create a new XML writer. Write to the writer provided. Parameters writer:Writer The output destination, or null to use standard output. encoding:String If non-null string is specified, it is written as a part of the XML declaration. _escapeHandler:CharacterEscapeHandler escape handler

XMLWriter

back to summary

public XMLWriter(Writer writer, String encoding, CharacterEscapeHandler _escapeHandler)

Create a new XML writer.

Write to the writer provided.

Parameters

writer:Writer: The output destination, or null to use standard output.
encoding:String: If non-null string is specified, it is written as a part of the XML declaration.
_escapeHandler:CharacterEscapeHandler: escape handler

XMLWriter	back to summary
public XMLWriter(Writer writer, String encoding)

Method Detail

characters back to summary

characters	back to summary
public void characters(char[] ch, int start, int len) throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.characters. Implements org.xml.sax.ContentHandler.characters. Write character data. Pass the event on down the filter chain for further processing. Parameters ch:char[] The array of characters to write. start:int The starting position in the array. len:int The number of characters to write. Annotations @Override Exceptions SAXException: If there is an error writing the characters, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#characters(char[], int, int)`

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

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

Implements org.xml.sax.ContentHandler.characters.

Write character data. Pass the event on down the filter chain for further processing.

Parameters

ch:char[]: The array of characters to write.
start:int: The starting position in the array.
len:int: The number of characters to write.

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the characters, or if a handler further down the filter chain raises an exception.

characters back to summary

characters	back to summary
public void characters(String data) throws SAXException Write a string of character data, with XML escaping. This is a convenience method that takes an XML String, converts it to a character array, then invokes `characters(char[], int, int)`. Parameters data:String The character data. Exceptions SAXException: If there is an error writing the string, or if a handler further down the filter chain raises an exception. See Also `characters(char[], int, int)`

public void characters(String data) throws SAXException

Write a string of character data, with XML escaping.

This is a convenience method that takes an XML String, converts it to a character array, then invokes characters(char[], int, int).

Parameters

data:String: The character data.

Exceptions

SAXException:: If there is an error writing the string, or if a handler further down the filter chain raises an exception.

See Also

characters(char[], int, int)

comment	back to summary
public void comment(char[] ch, int start, int length) throws SAXException Implements org.xml.sax.ext.LexicalHandler.comment. Doc from org.xml.sax.ext.LexicalHandler.comment. Report an XML comment anywhere in the document. This callback will be used for comments inside or outside the document element, including comments in the external DTD subset (if read). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events (if used). Annotations @Override Exceptions SAXException: The application may raise an exception.

comment

back to summary

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

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

Doc from org.xml.sax.ext.LexicalHandler.comment.

Report an XML comment anywhere in the document.

This callback will be used for comments inside or outside the document element, including comments in the external DTD subset (if read). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events (if used).

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

dataElement back to summary

dataElement	back to summary
public void dataElement(String uri, String localName, String qName, Attributes atts, String content) throws SAXException Write an element with character data content. 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)`. Parameters uri:String The element's Namespace URI. localName:String The element's local name. qName:String The element's default qualified name. atts:Attributes The element's attributes. content:String The character data content. Exceptions SAXException: If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception. See Also `startElement(String, String, String, Attributes)`, `characters(String)`, `endElement(String, String, String)`

public void dataElement(String uri, String localName, String qName, Attributes atts, String content) throws SAXException

Write an element with character data content.

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

Parameters

uri:String: The element's Namespace URI.
localName:String: The element's local name.
qName:String: The element's default qualified name.
atts:Attributes: The element's attributes.
content:String: The character data content.

Exceptions

SAXException:: If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.

dataElement back to summary

dataElement	back to summary
public void dataElement(String uri, String localName, String content) throws SAXException Write an element with character data content but no attributes. 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)`. Parameters uri:String The element's Namespace URI. localName:String The element's local name. content:String The character data content. Exceptions SAXException: If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception. See Also `startElement(String, String, String, Attributes)`, `characters(String)`, `endElement(String, String, String)`

public void dataElement(String uri, String localName, String content) throws SAXException

Write an element with character data content but no attributes.

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

Parameters

uri:String: The element's Namespace URI.
localName:String: The element's local name.
content:String: The character data content.

Exceptions

SAXException:: If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.

dataElement back to summary

dataElement	back to summary
public void dataElement(String localName, String content) throws SAXException Write an element with character data content but no attributes or Namespace URI. 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)`. Parameters localName:String The element's local name. content:String The character data content. Exceptions SAXException: If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception. See Also `startElement(String, String, String, Attributes)`, `characters(String)`, `endElement(String, String, String)`

public void dataElement(String localName, String content) throws SAXException

Write an element with character data content but no attributes or Namespace URI.

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

Parameters

localName:String: The element's local name.
content:String: The character data content.

Exceptions

SAXException:: If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.

endCDATA	back to summary
public void endCDATA() throws SAXException Implements org.xml.sax.ext.LexicalHandler.endCDATA. Doc from org.xml.sax.ext.LexicalHandler.endCDATA. Report the end of a CDATA section. Annotations @Override Exceptions SAXException: The application may raise an exception.

endCDATA

back to summary

public void endCDATA() throws SAXException

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

Doc from org.xml.sax.ext.LexicalHandler.endCDATA.

Report the end of a CDATA section.

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

endDocument back to summary

endDocument	back to summary
public void endDocument() throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.endDocument. Implements org.xml.sax.ContentHandler.endDocument. Write a newline at the end of the document. Pass the event on down the filter chain for further processing. Annotations @Override Exceptions SAXException: If there is an error writing the newline, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#endDocument()`

public void endDocument() throws SAXException

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

Implements org.xml.sax.ContentHandler.endDocument.

Write a newline at the end of the document. Pass the event on down the filter chain for further processing.

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the newline, or if a handler further down the filter chain raises an exception.

endDTD	back to summary
public void endDTD() throws SAXException Implements org.xml.sax.ext.LexicalHandler.endDTD. Doc from org.xml.sax.ext.LexicalHandler.endDTD. Report the end of DTD declarations. This method is intended to report the end of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked. Annotations @Override Exceptions SAXException: The application may raise an exception.

endDTD

back to summary

public void endDTD() throws SAXException

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

Doc from org.xml.sax.ext.LexicalHandler.endDTD.

Report the end of DTD declarations.

This method is intended to report the end of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

endElement back to summary

endElement	back to summary
public void endElement(String uri, String localName, String qName) throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.endElement. Implements org.xml.sax.ContentHandler.endElement. Write an end tag. Pass the event on down the filter chain for further processing. Parameters uri:String The Namespace URI, or the empty string if none is available. localName:String The element's local (unprefixed) name (required). qName:String 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. Annotations @Override Exceptions SAXException: If there is an error writing the end tag, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#endElement(java.lang.String, java.lang.String, java.lang.String)`

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

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

Implements org.xml.sax.ContentHandler.endElement.

Write an end tag. Pass the event on down the filter chain for further processing.

Parameters

uri:String: The Namespace URI, or the empty string if none is available.
localName:String: The element's local (unprefixed) name (required).
qName:String: 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.

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the end tag, or if a handler further down the filter chain raises an exception.

endElement back to summary

endElement	back to summary
public void endElement(String uri, String localName) throws SAXException End an element without a qname. This method will supply an empty string for the qName. It invokes `endElement(String, String, String)` directly. Parameters uri:String The element's Namespace URI. localName:String The element's local name. Exceptions SAXException: If there is an error writing the end tag, or if a handler further down the filter chain raises an exception. See Also `endElement(String, String, String)`

public void endElement(String uri, String localName) throws SAXException

End an element without a qname.

This method will supply an empty string for the qName. It invokes endElement(String, String, String) directly.

Parameters

uri:String: The element's Namespace URI.
localName:String: The element's local name.

Exceptions

SAXException:: If there is an error writing the end tag, or if a handler further down the filter chain raises an exception.

See Also

endElement(String, String, String)

endElement back to summary

endElement	back to summary
public void endElement(String localName) throws SAXException End an element without a Namespace URI or qname. 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. Parameters localName:String The element's local name. Exceptions SAXException: If there is an error writing the end tag, or if a handler further down the filter chain raises an exception. See Also `endElement(String, String, String)`

public void endElement(String localName) throws SAXException

End an element without a Namespace URI or qname.

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.

Parameters

localName:String: The element's local name.

Exceptions

SAXException:: If there is an error writing the end tag, or if a handler further down the filter chain raises an exception.

See Also

endElement(String, String, String)

endEntity	back to summary
public void endEntity(String name) throws SAXException Implements org.xml.sax.ext.LexicalHandler.endEntity. Doc from org.xml.sax.ext.LexicalHandler.endEntity. Report the end of an entity. Annotations @Override Exceptions SAXException: The application may raise an exception.

endEntity

back to summary

public void endEntity(String name) throws SAXException

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

Doc from org.xml.sax.ext.LexicalHandler.endEntity.

Report the end of an entity.

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

flush back to summary

flush	back to summary
public void flush() throws IOException Flush the output. 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 _commit the output stream. This method is invoked automatically by the `endDocument` method after writing a document. Exceptions IOException: for errors See Also `reset()`

public void flush() throws IOException

Flush the output.

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 _commit the output stream.

This method is invoked automatically by the endDocument method after writing a document.

Exceptions

IOException:: for errors

See Also

reset()

ignorableWhitespace back to summary

ignorableWhitespace	back to summary
public void ignorableWhitespace(char[] ch, int start, int length) throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.ignorableWhitespace. Implements org.xml.sax.ContentHandler.ignorableWhitespace. Write ignorable whitespace. Pass the event on down the filter chain for further processing. Parameters ch:char[] The array of characters to write. start:int The starting position in the array. length:int The number of characters to write. Annotations @Override Exceptions SAXException: If there is an error writing the whitespace, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#ignorableWhitespace(char[], int, int)`

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

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

Implements org.xml.sax.ContentHandler.ignorableWhitespace.

Write ignorable whitespace. Pass the event on down the filter chain for further processing.

Parameters

ch:char[]: The array of characters to write.
start:int: The starting position in the array.
length:int: The number of characters to write.

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the whitespace, or if a handler further down the filter chain raises an exception.

init	back to summary
private void init(Writer writer, String encoding) Internal initialization method. All of the public constructors invoke this method. Parameters writer:Writer The output destination, or null to use standard output.

init

back to summary

private void init(Writer writer, String encoding)

Internal initialization method.

All of the public constructors invoke this method.

Parameters

writer:Writer: The output destination, or null to use standard output.

processingInstruction back to summary

processingInstruction	back to summary
public void processingInstruction(String target, String data) throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.processingInstruction. Implements org.xml.sax.ContentHandler.processingInstruction. Write a processing instruction. Pass the event on down the filter chain for further processing. Parameters target:String The PI target. data:String The PI data. Annotations @Override Exceptions SAXException: If there is an error writing the PI, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#processingInstruction(java.lang.String, java.lang.String)`

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

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

Implements org.xml.sax.ContentHandler.processingInstruction.

Write a processing instruction. Pass the event on down the filter chain for further processing.

Parameters

target:String: The PI target.
data:String: The PI data.

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the PI, or if a handler further down the filter chain raises an exception.

reset back to summary

reset	back to summary
public void reset() Reset the writer. 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. See Also `flush()`

public void reset()

Reset the writer.

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.

See Also: flush()

setEncoding	back to summary
public void setEncoding(String encoding)

setHeader	back to summary
public void setHeader(String _header) Sets the header string. This string will be written right after the xml declaration without any escaping. Useful for generating a boiler-plate DOCTYPE decl, PIs, and comments. Parameters _header:String passing null will work as if the empty string is passed.

setHeader

back to summary

public void setHeader(String _header)

Sets the header string. This string will be written right after the xml declaration without any escaping. Useful for generating a boiler-plate DOCTYPE decl, PIs, and comments.

Parameters

_header:String: passing null will work as if the empty string is passed.

setOutput back to summary

setOutput	back to summary
public void setOutput(Writer writer, String _encoding) Set a new output destination for the document. Parameters writer:Writer The output destination, or null to use standard output. _encoding:String If non-null string is specified, it is written as a part of the XML declaration. See Also `flush()`

public void setOutput(Writer writer, String _encoding)

Set a new output destination for the document.

Parameters

writer:Writer: The output destination, or null to use standard output.
_encoding:String: If non-null string is specified, it is written as a part of the XML declaration.

See Also

flush()

setXmlDecl back to summary

setXmlDecl	back to summary
public void setXmlDecl(boolean _writeXmlDecl) Set whether the writer should print out the XML declaration (`<?xml version='1.0' ... ?>`). This option is set to true by default. Parameters _writeXmlDecl:boolean write out the XML declaration

public void setXmlDecl(boolean _writeXmlDecl)

Set whether the writer should print out the XML declaration (<?xml version='1.0' ... ?>).

This option is set to true by default.

Parameters

_writeXmlDecl:boolean: write out the XML declaration

startCDATA back to summary

startCDATA	back to summary
public void startCDATA() throws SAXException Implements org.xml.sax.ext.LexicalHandler.startCDATA. Doc from org.xml.sax.ext.LexicalHandler.startCDATA. Report the start of a CDATA section. The contents of the CDATA section will be reported through the regular `characters` event; this event is intended only to report the boundary. Annotations @Override Exceptions SAXException: The application may raise an exception.

public void startCDATA() throws SAXException

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

Doc from org.xml.sax.ext.LexicalHandler.startCDATA.

Report the start of a CDATA section.

The contents of the CDATA section will be reported through the regular characters event; this event is intended only to report the boundary.

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

startDocument back to summary

startDocument	back to summary
public void startDocument() throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.startDocument. Implements org.xml.sax.ContentHandler.startDocument. Write the XML declaration at the beginning of the document. Pass the event on down the filter chain for further processing. Annotations @Override Exceptions SAXException: If there is an error writing the XML declaration, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#startDocument()`

public void startDocument() throws SAXException

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

Implements org.xml.sax.ContentHandler.startDocument.

Write the XML declaration at the beginning of the document. Pass the event on down the filter chain for further processing.

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the XML declaration, or if a handler further down the filter chain raises an exception.

startDTD back to summary

startDTD	back to summary
public void startDTD(String name, String publicId, String systemId) throws SAXException Implements org.xml.sax.ext.LexicalHandler.startDTD. Doc from org.xml.sax.ext.LexicalHandler.startDTD. Report the start of DTD declarations, if any. This method is intended to report the beginning of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked. All declarations reported through `DTDHandler` or `DeclHandler` events must appear between the startDTD and `endDTD` events. Declarations are assumed to belong to the internal DTD subset unless they appear between `startEntity` and `endEntity` events. Comments and processing instructions from the DTD should also be reported between the startDTD and endDTD events, in their original order of (logical) occurrence; they are not required to appear in their correct locations relative to DTDHandler or DeclHandler events, however. Note that the start/endDTD events will appear within the start/endDocument events from ContentHandler and before the first `startElement` event. Annotations @Override Exceptions SAXException: The application may raise an exception.

public void startDTD(String name, String publicId, String systemId) throws SAXException

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

Doc from org.xml.sax.ext.LexicalHandler.startDTD.

Report the start of DTD declarations, if any.

This method is intended to report the beginning of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

All declarations reported through DTDHandler or DeclHandler events must appear between the startDTD and endDTD events. Declarations are assumed to belong to the internal DTD subset unless they appear between startEntity and endEntity events. Comments and processing instructions from the DTD should also be reported between the startDTD and endDTD events, in their original order of (logical) occurrence; they are not required to appear in their correct locations relative to DTDHandler or DeclHandler events, however.

Note that the start/endDTD events will appear within the start/endDocument events from ContentHandler and before the first startElement event.

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

startElement back to summary

startElement	back to summary
public void startElement(String uri, String localName, String qName, Attributes atts) throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.startElement. Implements org.xml.sax.ContentHandler.startElement. Write a start tag. Pass the event on down the filter chain for further processing. Parameters uri:String The Namespace URI, or the empty string if none is available. localName:String The element's local (unprefixed) name (required). qName:String 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:Attributes The element's attribute list (must not be null). Annotations @Override Exceptions SAXException: If there is an error writing the start tag, or if a handler further down the filter chain raises an exception. See Also `org.xml.sax.ContentHandler#startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

public void startElement(String uri, String localName, String qName, Attributes atts) throws SAXException

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

Implements org.xml.sax.ContentHandler.startElement.

Write a start tag. Pass the event on down the filter chain for further processing.

Parameters

uri:String: The Namespace URI, or the empty string if none is available.
localName:String: The element's local (unprefixed) name (required).
qName:String: 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:Attributes: The element's attribute list (must not be null).

Annotations

@Override

Exceptions

SAXException:: If there is an error writing the start tag, or if a handler further down the filter chain raises an exception.

startElement back to summary

startElement	back to summary
public void startElement(String uri, String localName) throws SAXException Start a new element without a qname or attributes. 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. Parameters uri:String The element's Namespace URI. localName:String The element's local name. Exceptions SAXException: If there is an error writing the start tag, or if a handler further down the filter chain raises an exception. See Also `startElement(String, String, String, Attributes)`

public void startElement(String uri, String localName) throws SAXException

Start a new element without a qname or attributes.

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.

Parameters

uri:String: The element's Namespace URI.
localName:String: The element's local name.

Exceptions

SAXException:: If there is an error writing the start tag, or if a handler further down the filter chain raises an exception.

startElement back to summary

startElement	back to summary
public void startElement(String localName) throws SAXException Start a new element without a qname, attributes or a Namespace URI. 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. Parameters localName:String The element's local name. Exceptions SAXException: If there is an error writing the start tag, or if a handler further down the filter chain raises an exception. See Also `startElement(String, String, String, Attributes)`

public void startElement(String localName) throws SAXException

Start a new element without a qname, attributes or a Namespace URI.

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.

Parameters

localName:String: The element's local name.

Exceptions

SAXException:: If there is an error writing the start tag, or if a handler further down the filter chain raises an exception.

startEntity back to summary

startEntity	back to summary
public void startEntity(String name) throws SAXException Implements org.xml.sax.ext.LexicalHandler.startEntity. Doc from org.xml.sax.ext.LexicalHandler.startEntity. Report the beginning of some internal and external XML entities. The reporting of parameter entities (including the external DTD subset) is optional, and SAX2 drivers that report LexicalHandler events may not implement it; you can use the `http://xml.org/sax/features/lexical-handler/parameter-entities` feature to query or control the reporting of parameter entities. General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]". When a SAX2 driver is providing these events, all other events must be properly nested within start/end entity events. There is no additional requirement that events from `DeclHandler` or `DTDHandler` be properly ordered. Note that skipped entities will be reported through the `skippedEntity` event, which is part of the ContentHandler interface. Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances: general entities within attribute values parameter entities within declarations These will be silently expanded, with no indication of where the original entity boundaries were. Note also that the boundaries of character references (which are not really entities anyway) are not reported. All start/endEntity events must be properly nested. Annotations @Override Exceptions SAXException: The application may raise an exception.

public void startEntity(String name) throws SAXException

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

Doc from org.xml.sax.ext.LexicalHandler.startEntity.

Report the beginning of some internal and external XML entities.

The reporting of parameter entities (including the external DTD subset) is optional, and SAX2 drivers that report LexicalHandler events may not implement it; you can use the http://xml.org/sax/features/lexical-handler/parameter-entities feature to query or control the reporting of parameter entities.

General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]".

When a SAX2 driver is providing these events, all other events must be properly nested within start/end entity events. There is no additional requirement that events from DeclHandler or DTDHandler be properly ordered.

Note that skipped entities will be reported through the skippedEntity event, which is part of the ContentHandler interface.

Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances:

general entities within attribute values
parameter entities within declarations

These will be silently expanded, with no indication of where the original entity boundaries were.

Note also that the boundaries of character references (which are not really entities anyway) are not reported.

All start/endEntity events must be properly nested.

Annotations

@Override

Exceptions

SAXException:: The application may raise an exception.

startPrefixMapping	back to summary
public void startPrefixMapping(String prefix, String uri) throws SAXException Overrides org.xml.sax.helpers.XMLFilterImpl.startPrefixMapping. Implements org.xml.sax.ContentHandler.startPrefixMapping. Doc from org.xml.sax.helpers.XMLFilterImpl.startPrefixMapping. Filter a start Namespace prefix mapping event. Annotations @Override Exceptions SAXException: The client may throw an exception during processing.

startPrefixMapping

back to summary

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

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

Implements org.xml.sax.ContentHandler.startPrefixMapping.

Doc from org.xml.sax.helpers.XMLFilterImpl.startPrefixMapping.

Filter a start Namespace prefix mapping event.

Annotations

@Override

Exceptions

SAXException:: The client may throw an exception during processing.

write	back to summary
private void write(char c) throws IOException Write a raw character. Parameters c:char The character to write.

write

back to summary

private void write(char c) throws IOException

Write a raw character.

Parameters

c:char: The character to write.

write	back to summary
private void write(String s) throws IOException Write a raw string.

writeAttributes	back to summary
private void writeAttributes(Attributes atts) throws IOException, SAXException Write out an attribute list, escaping values. The names will have prefixes added to them. Parameters atts:Attributes The attribute list to write. Exceptions SAXException: If there is an error writing the attribute list, this method will throw an IOException wrapped in a SAXException.

writeAttributes

back to summary

private void writeAttributes(Attributes atts) throws IOException, SAXException

Write out an attribute list, escaping values. The names will have prefixes added to them.

Parameters

atts:Attributes: The attribute list to write.

Exceptions

SAXException:: If there is an error writing the attribute list, this method will throw an IOException wrapped in a SAXException.

writeEsc	back to summary
private void writeEsc(char[] ch, int start, int length, boolean isAttVal) throws SAXException, IOException Write an array of data characters with escaping. Parameters ch:char[] The array of characters. start:int The starting position. length:int The number of characters to use. isAttVal:boolean true if this is an attribute value literal. Exceptions SAXException: If there is an error writing the characters, this method will throw an IOException wrapped in a SAXException.

writeEsc

back to summary

private void writeEsc(char[] ch, int start, int length, boolean isAttVal) throws SAXException, IOException

Write an array of data characters with escaping.

Parameters

ch:char[]: The array of characters.
start:int: The starting position.
length:int: The number of characters to use.
isAttVal:boolean: true if this is an attribute value literal.

Exceptions

SAXException:: If there is an error writing the characters, this method will throw an IOException wrapped in a SAXException.

writeName	back to summary
private void writeName(String uri, String localName, String qName, boolean isElement) throws IOException Write an element or attribute name. Parameters uri:String The Namespace URI. localName:String The local name. qName:String The prefixed name, if available, or the empty string. isElement:boolean true if this is an element name, false if it is an attribute name.

writeName

back to summary

private void writeName(String uri, String localName, String qName, boolean isElement) throws IOException

Write an element or attribute name.

Parameters

uri:String: The Namespace URI.
localName:String: The local name.
qName:String: The prefixed name, if available, or the empty string.
isElement:boolean: true if this is an element name, false if it is an attribute name.

public Class XMLWriter

Whitespace

Namespace Support

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail