Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> com >> rohanclan >> ashpool >> [ core overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of com.rohanclan.ashpool.core.XMLWriter JAVADOC | Sourc code of com.rohanclan.ashpool.core.XMLWriter SOURCE | Download com.rohanclan.ashpool.core.XMLWriter DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.rohanclan.ashpool.core
Class XMLWriter  view XMLWriter download XMLWriter.java

java.lang.Object
  extended byorg.xml.sax.helpers.XMLFilterImpl
      extended bycom.rohanclan.ashpool.core.XMLWriter
All Implemented Interfaces:
org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader
Direct Known Subclasses:
DataWriter
public class XMLWriter
extends org.xml.sax.helpers.XMLFilterImpl

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 55 method and ending with the endDocument 55 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 55 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.

Version:
0.2

Field Summary
private  java.util.Hashtable doneDeclTable
           
private  int elementLevel
           
private  org.xml.sax.Attributes EMPTY_ATTS
           
private  java.util.Hashtable forcedDeclTable
           
private  org.xml.sax.helpers.NamespaceSupport nsSupport
           
private  java.io.Writer output
           
private  int prefixCounter
           
private  java.util.Hashtable prefixTable
           
 
Fields inherited from class org.xml.sax.helpers.XMLFilterImpl
 
Constructor Summary
XMLWriter()
          Create a new XML writer.
XMLWriter(java.io.Writer writer)
          Create a new XML writer.
XMLWriter(org.xml.sax.XMLReader xmlreader)
          Create a new XML writer.
XMLWriter(org.xml.sax.XMLReader xmlreader, java.io.Writer writer)
          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 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.
private  java.lang.String doPrefix(java.lang.String uri, java.lang.String qName, boolean isElement)
          Determine the prefix for an element or attribute name.
 void emptyElement(java.lang.String localName)
          Add an empty element without a Namespace URI, qname or attributes.
 void emptyElement(java.lang.String uri, java.lang.String localName)
          Add an empty element without a qname or attributes.
 void emptyElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)
          Write an empty element.
 void endDocument()
          Write a newline at the end of the document.
 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 flush()
          Flush the output.
 void forceNSDecl(java.lang.String uri)
          Force a Namespace to be declared on the root element.
 void forceNSDecl(java.lang.String uri, java.lang.String prefix)
          Force a Namespace declaration with a preferred prefix.
private  void forceNSDecls()
          Force all Namespaces to be declared.
 java.lang.String getPrefix(java.lang.String uri)
          Get the current or preferred prefix for a Namespace URI.
 void ignorableWhitespace(char[] ch, int start, int length)
          Write ignorable whitespace.
private  void init(java.io.Writer writer)
          Internal initialization method.
 void processingInstruction(java.lang.String target, java.lang.String data)
          Write a processing instruction.
 void reset()
          Reset the writer.
 void setOutput(java.io.Writer writer)
          Set a new output destination for the document.
 void setPrefix(java.lang.String uri, java.lang.String prefix)
          Specify a preferred prefix for a Namespace URI.
 void startDocument()
          Write the XML declaration at the beginning of the document.
 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.
private  void write(char c)
          Write a raw character.
private  void write(java.lang.String s)
          Write a raw string.
private  void writeAttributes(org.xml.sax.Attributes atts)
          Write out an attribute list, escaping values.
private  void writeEsc(char[] ch, int start, int length, boolean isAttVal)
          Write an array of data characters with escaping.
private  void writeName(java.lang.String uri, java.lang.String localName, java.lang.String qName, boolean isElement)
          Write an element or attribute name.
private  void writeNSDecls()
          Write out the list of Namespace declarations.
 
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, startPrefixMapping, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_ATTS

private final org.xml.sax.Attributes EMPTY_ATTS

prefixTable

private java.util.Hashtable prefixTable

forcedDeclTable

private java.util.Hashtable forcedDeclTable

doneDeclTable

private java.util.Hashtable doneDeclTable

elementLevel

private int elementLevel

output

private java.io.Writer output

nsSupport

private org.xml.sax.helpers.NamespaceSupport nsSupport

prefixCounter

private int prefixCounter
Constructor Detail

XMLWriter

public XMLWriter()
Create a new XML writer.

Write to standard output.

XMLWriter

public XMLWriter(java.io.Writer writer)
Create a new XML writer.

Write to the writer provided.

XMLWriter

public XMLWriter(org.xml.sax.XMLReader xmlreader)
Create a new XML writer.

Use the specified XML reader as the parent.

XMLWriter

public XMLWriter(org.xml.sax.XMLReader xmlreader,
                 java.io.Writer writer)
Create a new XML writer.

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

Method Detail

init

private void init(java.io.Writer writer)
Internal initialization method.

All of the public constructors invoke this method.

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

This method is invoked automatically by the startDocument 55 method before writing a new document.

Note: this method will not clear the prefix or URI information in the writer or the selected output writer.

flush

public void flush()
           throws 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 close the output stream.

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

setOutput

public void setOutput(java.io.Writer writer)
Set a new output destination for the document.

setPrefix

public void setPrefix(java.lang.String uri,
                      java.lang.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 55 method as well.

getPrefix

public java.lang.String getPrefix(java.lang.String uri)
Get the current or preferred prefix for a Namespace URI.

forceNSDecl

public void forceNSDecl(java.lang.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.

forceNSDecl

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

This is a convenience method that invokes setPrefix 55 then forceNSDecl 55 .

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.

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.

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.

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.

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.

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.

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.

emptyElement

public void emptyElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes atts)
                  throws org.xml.sax.SAXException
Write an empty element. This method writes an empty element tag rather than a start tag followed by an end tag. Both a startElement 55 and an endElement 55 event will be passed on down the filter chain.

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

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.

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

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

emptyElement

public void emptyElement(java.lang.String uri,
                         java.lang.String localName)
                  throws org.xml.sax.SAXException
Add an empty element without a qname or attributes.

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

emptyElement

public void emptyElement(java.lang.String localName)
                  throws org.xml.sax.SAXException
Add an empty element without a Namespace URI, qname or attributes.

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

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

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

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

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

forceNSDecls

private void forceNSDecls()
Force all Namespaces to be declared. This method is used on the root element to ensure that the predeclared Namespaces all appear.

doPrefix

private java.lang.String doPrefix(java.lang.String uri,
                                  java.lang.String qName,
                                  boolean isElement)
Determine the prefix for an element or attribute name. TODO: this method probably needs some cleanup.

write

private void write(char c)
            throws org.xml.sax.SAXException
Write a raw character.

write

private void write(java.lang.String s)
            throws org.xml.sax.SAXException
Write a raw string.

writeAttributes

private void writeAttributes(org.xml.sax.Attributes atts)
                      throws org.xml.sax.SAXException
Write out an attribute list, escaping values. The names will have prefixes added to them.

writeEsc

private void writeEsc(char[] ch,
                      int start,
                      int length,
                      boolean isAttVal)
               throws org.xml.sax.SAXException
Write an array of data characters with escaping.

writeNSDecls

private void writeNSDecls()
                   throws org.xml.sax.SAXException
Write out the list of Namespace declarations.

writeName

private void writeName(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String qName,
                       boolean isElement)
                throws org.xml.sax.SAXException
Write an element or attribute name.

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> com >> rohanclan >> ashpool >> [ core overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of com.rohanclan.ashpool.core.XMLWriter JAVADOC | Sourc code of com.rohanclan.ashpool.core.XMLWriter SOURCE | Download com.rohanclan.ashpool.core.XMLWriter DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD