Java Doc for XmlWriter.java in  » Web-Services » restlet-1.0.8 » org » restlet » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 XmlWriter.startDocument startDocument method and ending with the XmlWriter.endDocument 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 the data format mode (set the "dataFormat" property) which is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly). See details below.

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

Data Format

This mode, enabled by the "dataFormat" property, pretty-prints field-oriented XML without mixed content. All added indentation and newlines will be passed on down the filter chain (if any).

In general, all whitespace in an XML document is potentially significant, so a general-purpose XML writing tool cannot add newlines or indentation.

There is, however, a large class of XML documents where information is strictly fielded: each element contains either character data or other elements, but not both. For this special case, it is possible for a writing tool to provide automatic indentation and newlines without requiring extra work from the user. Note that this class will likely not yield appropriate results for document-oriented XML like XHTML pages, which mix character data and elements together.

This writer mode will automatically place each start tag on a new line, optionally indented if an indent step is provided (by default, there is no indentation). If an element contains other elements, the end tag will also appear on a new line with leading indentation. Consider, for example, the following code:

 XmlWriter w = new XmlWriter();
 w.setDataFormat(true);
 w.setIndentStep(2);
 w.startDocument();
 w.startElement("Person");
 w.dataElement("name", "Jane Smith");
 w.dataElement("date-of-birth", "1965-05-23");
 w.dataElement("citizenship", "US");
 w.endElement("Person");
 w.endDocument();
 

This code will produce the following document:

 <?xml version="1.0" standalone="yes"?>
 <Person>
 <name>Jane Smith</name>
 <date-of-birth>1965-05-23</date-of-birth>
 <citizenship>US</citizenship>
 </Person>
 

This is a convenience method to write a complete element with character data content, including the start tag and end tag.

This is a convenience method to write a complete element with character data content, including the start tag and end tag.

This method will supply an empty string for the qname, and empty string for the Namespace URI, and an empty attribute list.

This method will supply an empty string for the qname and an empty attribute list.

This method will supply an empty string for the qName and an empty string for the Namespace URI.

This method will supply an empty string for the qName.

This method flushes the output stream.

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.

This method will provide an empty string for the Namespace URI, and empty string for the qualified name, and a default empty attribute list.

This method will provide a default empty attribute list and an empty string for the qualified name.

Write to standard output.

Write to the writer provided.

Use the specified XML reader as the parent.

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

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

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 XmlWriter.startElement(String,String,String,Attributes) , followed by XmlWriter.characters(String) , followed by XmlWriter.endElement(String,String,String) .

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 XmlWriter.startElement(String,String,String,Attributes) , followed by XmlWriter.characters(String) , followed by XmlWriter.endElement(String,String,String) .

This is a convenience method to write a complete element with character data content, including the start tag and end tag.

This method invokes XmlWriter.startElement(String,String,String,Attributes) , followed by XmlWriter.characters(String) , followed by XmlWriter.endElement(String,String,String) .

This method will supply an empty string for the qname, and empty string for the Namespace URI, and an empty attribute list. It invokes XmlWriter.emptyElement(String,String,String,Attributes) directly.

This method will supply an empty string for the qname and an empty attribute list. It invokes XmlWriter.emptyElement(String,String,String,Attributes) directly.

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

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

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 XmlWriter.endDocument endDocument method after writing a document.

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.

This is a convenience method that invokes XmlWriter.setPrefix setPrefix then XmlWriter.forceNSDecl(java.lang.String) forceNSDecl .

Return the current indent step: each start tag will be indented by this number of spaces times the number of ancestors that the element has.

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 XmlWriter.flush flush before resetting the writer, to make sure that no output is lost.

This method is invoked automatically by the XmlWriter.startDocument 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.

Note that this method does not actually force the Namespace to be declared; to do that, use the XmlWriter.forceNSDecl(java.lang.String) forceNSDecl method as well.

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.

This method will provide a default empty attribute list and an empty string for the qualified name. It invokes XmlWriter.startElement(String,String,String,Attributes) directly.