Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.xml.txw2.output
Class XMLWriter

    java.lang.Object
      org.xml.sax.helpers.XMLFilterImpl
          com.sun.xml.txw2.output.XMLWriter

All Implemented Interfaces:
  org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.ext.LexicalHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader

Direct Known Subclasses:
  DataWriter

    public class XMLWriter

extends org.xml.sax.helpers.XMLFilterImpl
implements org.xml.sax.ext.LexicalHandler

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:

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

Since:
  JAXB1.0
Version:
  0.2
Author:
  David Megginson, david@megginson.com
See Also:
  `XMLFilter`, `ContentHandler`

Constructor Summary
`XMLWriter(java.io.Writer writer, java.lang.String encoding)`
`XMLWriter(java.io.Writer writer, java.lang.String encoding, CharacterEscapeHandler _escapeHandler)` Create a new XML writer.

Method Summary
`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` | `comment(char[] ch, int start, int length)`
`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` | `endCDATA()`
`void` | `endDocument()` Write a newline at the end of the document.
`void` | `endDTD()`
`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` | `endEntity(java.lang.String name)`
`void` | `flush()` Flush the output.
`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` | `setEncoding(java.lang.String encoding)`
`void` | `setHeader(java.lang.String _header)` Sets the header string.
`void` | `setOutput(java.io.Writer writer, java.lang.String _encoding)` Set a new output destination for the document.
`void` | `setXmlDecl(boolean _writeXmlDecl)` Set whether the writer should print out the XML declaration (<?xml version='1.0' ...
`void` | `startCDATA()`
`void` | `startDocument()` Write the XML declaration at the beginning of the document.
`void` | `startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)`
`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.
`void` | `startEntity(java.lang.String name)`
`void` | `startPrefixMapping(java.lang.String prefix, java.lang.String uri)`

Methods inherited from class org.xml.sax.helpers.XMLFilterImpl
`endPrefixMapping, error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, notationDecl, parse, parse, resolveEntity, setContentHandler, setDocumentLocator, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, setProperty, skippedEntity, unparsedEntityDecl, warning`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### XMLWriter

    public XMLWriter(java.io.Writer writer,
                     java.lang.String encoding,
                     CharacterEscapeHandler _escapeHandler)

  Create a new XML writer.

  Write to the writer provided.

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

### XMLWriter

    public XMLWriter(java.io.Writer writer,
                     java.lang.String encoding)

Method Detail

### reset

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

### flush

    public void flush()
               throws java.io.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.

  Throws:
    `java.io.IOException`
  See Also:
    `reset()`

### setOutput

    public void setOutput(java.io.Writer writer,
                          java.lang.String _encoding)

  Set a new output destination for the document.

  Parameters:
    `writer` - The output destination, or null to use standard output.
  See Also:
    `flush()`

### setEncoding

    public void setEncoding(java.lang.String encoding)

### setXmlDecl

    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.

### setHeader

    public void setHeader(java.lang.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` - passing null will work as if the empty string is passed.

### startPrefixMapping

    public void startPrefixMapping(java.lang.String prefix,
                                   java.lang.String uri)
                            throws org.xml.sax.SAXException

  Specified by:
    `startPrefixMapping` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `startPrefixMapping` in class `org.xml.sax.helpers.XMLFilterImpl`
  Throws:
    `org.xml.sax.SAXException`

### startDocument

    public void startDocument()
                       throws org.xml.sax.SAXException

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

  Specified by:
    `startDocument` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `startDocument` in class `org.xml.sax.helpers.XMLFilterImpl`
  Throws:
    `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.
  See Also:
    `ContentHandler.startDocument()`

### endDocument

    public void endDocument()
                     throws org.xml.sax.SAXException

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

  Specified by:
    `endDocument` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `endDocument` in class `org.xml.sax.helpers.XMLFilterImpl`
  Throws:
    `org.xml.sax.SAXException` - If there is an error writing the newline, or if a handler further down the filter chain raises an exception.
  See Also:
    `ContentHandler.endDocument()`

### startElement

    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

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

  Specified by:
    `startElement` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `startElement` in class `org.xml.sax.helpers.XMLFilterImpl`
  Parameters:
    `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).
  Throws:
    `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.
  See Also:
    `ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

### endElement

    public void endElement(java.lang.String uri,
                           java.lang.String localName,
                           java.lang.String qName)
                    throws org.xml.sax.SAXException

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

  Specified by:
    `endElement` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `endElement` in class `org.xml.sax.helpers.XMLFilterImpl`
  Parameters:
    `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.
  Throws:
    `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.
  See Also:
    `ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)`

### characters

    public void characters(char[] ch,
                           int start,
                           int len)
                    throws org.xml.sax.SAXException

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

  Specified by:
    `characters` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `characters` in class `org.xml.sax.helpers.XMLFilterImpl`
  Parameters:
    `ch` - The array of characters to write.
    `start` - The starting position in the array.
    `len` - The number of characters to write.
  Throws:
    `org.xml.sax.SAXException` - If there is an error writing the characters, or if a handler further down the filter chain raises an exception.
  See Also:
    `ContentHandler.characters(char[], int, int)`

### ignorableWhitespace

    public void ignorableWhitespace(char[] ch,
                                    int start,
                                    int length)
                             throws org.xml.sax.SAXException

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

  Specified by:
    `ignorableWhitespace` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `ignorableWhitespace` in class `org.xml.sax.helpers.XMLFilterImpl`
  Parameters:
    `ch` - The array of characters to write.
    `start` - The starting position in the array.
    `length` - The number of characters to write.
  Throws:
    `org.xml.sax.SAXException` - If there is an error writing the whitespace, or if a handler further down the filter chain raises an exception.
  See Also:
    `ContentHandler.ignorableWhitespace(char[], int, int)`

### processingInstruction

    public void processingInstruction(java.lang.String target,
                                      java.lang.String data)
                               throws org.xml.sax.SAXException

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

  Specified by:
    `processingInstruction` in interface `org.xml.sax.ContentHandler`
  Overrides:
    `processingInstruction` in class `org.xml.sax.helpers.XMLFilterImpl`
  Parameters:
    `target` - The PI target.
    `data` - The PI data.
  Throws:
    `org.xml.sax.SAXException` - If there is an error writing the PI, or if a handler further down the filter chain raises an exception.
  See Also:
    `ContentHandler.processingInstruction(java.lang.String, java.lang.String)`

### startElement

    public void startElement(java.lang.String uri,
                             java.lang.String localName)
                      throws org.xml.sax.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` - The element's Namespace URI.
    `localName` - The element's local name.
  Throws:
    `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.
  See Also:
    `startElement(String, String, String, Attributes)`

### startElement

    public void startElement(java.lang.String localName)
                      throws org.xml.sax.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` - The element's local name.
  Throws:
    `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.
  See Also:
    `startElement(String, String, String, Attributes)`

### endElement

    public void endElement(java.lang.String uri,
                           java.lang.String localName)
                    throws org.xml.sax.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` - The element's Namespace URI.
    `localName` - The element's local name.
  Throws:
    `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.
  See Also:
    `endElement(String, String, String)`

### endElement

    public void endElement(java.lang.String localName)
                    throws org.xml.sax.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` - The element's local name.
  Throws:
    `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.
  See Also:
    `endElement(String, String, String)`

### dataElement

    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

  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` - 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.
  Throws:
    `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.
  See Also:
    `startElement(String, String, String, Attributes)`, `characters(String)`, `endElement(String, String, String)`

### dataElement

    public void dataElement(java.lang.String uri,
                            java.lang.String localName,
                            java.lang.String content)
                     throws org.xml.sax.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` - The element's Namespace URI.
    `localName` - The element's local name.
    `content` - The character data content.
  Throws:
    `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.
  See Also:
    `startElement(String, String, String, Attributes)`, `characters(String)`, `endElement(String, String, String)`

### dataElement

    public void dataElement(java.lang.String localName,
                            java.lang.String content)
                     throws org.xml.sax.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` - The element's local name.
    `content` - The character data content.
  Throws:
    `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.
  See Also:
    `startElement(String, String, String, Attributes)`, `characters(String)`, `endElement(String, String, String)`

### characters

    public void characters(java.lang.String data)
                    throws org.xml.sax.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` - The character data.
  Throws:
    `org.xml.sax.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)`

### startDTD

    public void startDTD(java.lang.String name,
                         java.lang.String publicId,
                         java.lang.String systemId)
                  throws org.xml.sax.SAXException

  Specified by:
    `startDTD` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

### endDTD

    public void endDTD()
                throws org.xml.sax.SAXException

  Specified by:
    `endDTD` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

### startEntity

    public void startEntity(java.lang.String name)
                     throws org.xml.sax.SAXException

  Specified by:
    `startEntity` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

### endEntity

    public void endEntity(java.lang.String name)
                   throws org.xml.sax.SAXException

  Specified by:
    `endEntity` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

### startCDATA

    public void startCDATA()
                    throws org.xml.sax.SAXException

  Specified by:
    `startCDATA` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

### endCDATA

    public void endCDATA()
                  throws org.xml.sax.SAXException

  Specified by:
    `endCDATA` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

### comment

    public void comment(char[] ch,
                        int start,
                        int length)
                 throws org.xml.sax.SAXException

  Specified by:
    `comment` in interface `org.xml.sax.ext.LexicalHandler`
  Throws:
    `org.xml.sax.SAXException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD