Save This Page
Home » Xerces-J-src.2.9.1 » sax » [javadoc | source]
sax
public class: XMLWriter [javadoc | source]
java.lang.Object
   org.xml.sax.helpers.XMLFilterImpl
      sax.XMLFilterBase
         sax.XMLWriter

All Implemented Interfaces:
    LexicalHandler, ErrorHandler, EntityResolver, XMLFilter, ContentHandler, DTDHandler

Filter to write an XML document from a SAX event stream. Code and comments adapted from XMLWriter-0.2, written by David Megginson and released into the public domain, without warranty.

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.

The following code will send a simple XML document to standard output:

XMLWriter w = new XMLWriter();

w.startDocument();
w.dataElement("greeting", "Hello, world!");
w.endDocument();

The resulting document will look like this:

<?xml version="1.0"?>

<greeting>Hello, world!</greeting>

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 DataFormatFilter add 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"?>

<_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:

  1. the qualified name
  2. the 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"?>

<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"?>

<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"?>

<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"?>

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

Fields inherited from sax.XMLFilterBase:
EMPTY_ATTS,  LEXICAL_HANDLER_NAMES
Constructor:
 public XMLWriter() 
 public XMLWriter(Writer writer) 
    Create a new XML writer.

    Write to the writer provided.

    Parameters:
    writer - The output destination, or null to use standard output.
 public XMLWriter(XMLReader xmlreader) 
    Create a new XML writer.

    Use the specified XML reader as the parent.

    Parameters:
    xmlreader - The parent in the filter chain, or null for no parent.
 public XMLWriter(XMLReader xmlreader,
    Writer writer) 
    Create a new XML writer.

    Use the specified XML reader as the parent, and write to the specified writer.

    Parameters:
    xmlreader - The parent in the filter chain, or null for no parent.
    writer - The output destination, or null to use standard output.
Method from sax.XMLWriter Summary:
characters,   comment,   endCDATA,   endDTD,   endDocument,   endElement,   endEntity,   flush,   forceNSDecl,   forceNSDecl,   getPrefix,   ignorableWhitespace,   processingInstruction,   reset,   setOutput,   setPrefix,   startCDATA,   startDTD,   startDocument,   startElement,   startEntity
Methods from sax.XMLFilterBase:
characters,   comment,   dataElement,   dataElement,   dataElement,   dataElement,   emptyElement,   emptyElement,   emptyElement,   emptyElement,   endCDATA,   endDTD,   endElement,   endElement,   endEntity,   getLexicalHandler,   getProperty,   parse,   setLexicalHandler,   setProperty,   startCDATA,   startDTD,   startElement,   startElement,   startElement,   startEntity
Methods from org.xml.sax.helpers.XMLFilterImpl:
characters,   endDocument,   endElement,   endPrefixMapping,   error,   fatalError,   getContentHandler,   getDTDHandler,   getEntityResolver,   getErrorHandler,   getFeature,   getParent,   getProperty,   ignorableWhitespace,   notationDecl,   parse,   parse,   processingInstruction,   resolveEntity,   setContentHandler,   setDTDHandler,   setDocumentLocator,   setEntityResolver,   setErrorHandler,   setFeature,   setParent,   setProperty,   skippedEntity,   startDocument,   startElement,   startPrefixMapping,   unparsedEntityDecl,   warning
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from sax.XMLWriter Detail:
 public  void characters(char[] ch,
    int start,
    int len) throws SAXException 
    Write character data. Pass the event on down the filter chain for further processing.
 public  void comment(char[] ch,
    int start,
    int length) throws SAXException 
 public  void endCDATA() throws SAXException 
 public  void endDTD() throws SAXException 
    Write end of DOCTYPE declaration. Pass the event on down the filter chain for further processing.
 public  void endDocument() throws SAXException 
    Write a newline at the end of the document. Pass the event on down the filter chain for further processing.
 public  void endElement(String uri,
    String localName,
    String qName) throws SAXException 
    Write an end tag. Pass the event on down the filter chain for further processing.
 public  void endEntity(String name) throws SAXException 
 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 close the output stream.

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

 public  void forceNSDecl(String uri) 
    Force a Namespace to be declared on the root element.

    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.

 public  void forceNSDecl(String uri,
    String prefix) 
    Force a Namespace declaration with a preferred prefix.

    This is a convenience method that invokes setPrefix then forceNSDecl .

 public String getPrefix(String uri) 
    Get the current or preferred prefix for a Namespace URI.
 public  void ignorableWhitespace(char[] ch,
    int start,
    int length) throws SAXException 
    Write ignorable whitespace. Pass the event on down the filter chain for further processing.
 public  void processingInstruction(String target,
    String data) throws SAXException 
    Write a processing instruction. Pass the event on down the filter chain for further processing.
 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.

 public  void setOutput(Writer writer) 
    Set a new output destination for the document.
 public  void setPrefix(String uri,
    String prefix) 
    Specify a preferred prefix for a Namespace URI.

    Note that this method does not actually force the Namespace to be declared; to do that, use the forceNSDecl method as well.

 public  void startCDATA() throws SAXException 
 public  void startDTD(String name,
    String publicId,
    String systemId) throws SAXException 
    Write start of DOCTYPE declaration. Pass the event on down the filter chain for further processing.
 public  void startDocument() throws SAXException 
    Write the XML declaration at the beginning of the document. Pass the event on down the filter chain for further processing.
 public  void startElement(String uri,
    String localName,
    String qName,
    Attributes atts) throws SAXException 
    Write a start tag. Pass the event on down the filter chain for further processing.
 public  void startEntity(String name) throws SAXException