tribble.xml
Class XmlOutputStreamAdapter

java.lang.Object
  extended bytribble.xml.XmlOutputStreamAdapter
All Implemented Interfaces:
XmlOutputStreamI

public class XmlOutputStreamAdapter
extends java.lang.Object
implements XmlOutputStreamI

Generic XML output stream.

This default implementation of the XmlOutputStreamI interface provides a very simple functional XML output stream.

Example

We want to generate the following XML document:

    <?xml version='1.0' stand-alone='yes'?>
    <emp:employee
        type='perm' ssn='647-37-0999'>
      <emp:name>John Q. Smith</emp:name>
      <emp:address>
        <emp:street>3817 Newhaven Dr.</emp:street>
        <emp:city>Dallas</emp:city>
        <emp:state>TX</emp:state>
        <emp:zip>75022</emp:zip>
      </emp:address>
      <emp:hire when='2001-02-11'/>
      <emp:dept>Customer Support A</emp:dept>
    </emp:employee>
 

First we create an XML output stream and initialize it:

    Writer              out;
    XmlOutputStreamI    xml;
    Properties          props;

    out = ...;
    xml = new XmlOutputStreamAdapter(out);
    props = ...;
    xml.initialize(props);
 

Next we specify that we want an <?xml> directive tag in the output with a stand-alone='yes' attribute:

    xml.startDirective("xml");
    xml.addAttribute("stand-alone", "yes");
    xml.endDirective();
 

Next we start the outermost <emp:employee> tag, and set its attributes:

    xml.startTag("emp", "employee");
    xml.addAttribute("type", "perm");
    xml.addAttribute("ssn", "647-37-0999");
 

For convenience, we can set the namespace prefix for all of the remaining tags, since they are all the same (emp:), and use the simpler form of the startTag() method:

    xml.setNamespace("emp");
 

Next we add the <emp:name> tag and its text content:

    xml.startTag("name");
    xml.addText("John Q. Smith");
    xml.endTag();
 

Likewise, we continue in a similar fashion for the remaining XML tags:

    xml.startTag("address");
    xml.startTag("street");
    xml.addText("3817 Newhaven Dr.");
    xml.endTag();

    xml.startTag("city");
    xml.addText("Dallas");
    xml.endTag();

    xml.startTag("state");
    xml.addText("TX");
    xml.endTag();

    xml.startTag("zip");
    xml.addText("75022");
    xml.endTag();
    xml.endTag();       // Close the <emp:address> tag

    xml.startTag("hire");
    xml.addAttribute("when", "2001-02-11");
    xml.endTag();

    xml.startTag("dept");
    xml.addText("Customer Support A");
    xml.endTag();
 

Next we terminate the outermost XML tag (emp:employee):

    xml.endTag();       // Close the <emp:employee> tag
 

Finally we flush any pending output for the output stream and then close it:

    xml.flush();
    xml.close();
 

Since:
2005-02-18
Version:
API 1.0, $Revision$ $Date$
Author:
David R. Tribble (david@tribble.com).
Copyright 2005 by David R. Tribble, all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.

Field Summary
protected static java.lang.String ENT_AMP
          Character entity: '&'.
protected static java.lang.String ENT_APOS
          Character entity: '''.
protected static java.lang.String ENT_GT
          Character entity: '>'.
protected static java.lang.String ENT_LT
          Character entity: '<'.
protected static java.lang.String ENT_QUOT
          Character entity: '"'.
protected  int m_colNo
          Current output column position (starting at 1).
protected  java.lang.String m_dir
          Current directive tag.
protected  java.lang.String m_elem
          Current element tag.
protected  java.lang.String m_namesp
          Default XML namespace prefix.
protected  int m_nest
          XML element node nesting level.
protected  java.io.Writer m_out
          Output stream.
protected  java.util.ArrayList m_prefixes
          Nested element namespace prefixes stack.
protected  short m_state
          Current XML output state.
protected  java.util.ArrayList m_tags
          Nested element tags stack.
static int SERIES
          API series number.
protected static short ST_DIR
          Output state: Within a directive.
protected static short ST_TAG
          Output state: Within an element tag.
protected static short ST_TEXT
          Output state: Within an element text content.
 
Constructor Summary
XmlOutputStreamAdapter(java.io.Writer out)
          Constructor.
 
Method Summary
 void addAttribute(java.lang.String attr, java.lang.String val)
          Add an attribute value to the current XML tag.
 void addCharacter(int ch)
          Append a character to the text content of the current XML tag.
 void addText(java.lang.String text)
          Append text content to the current XML tag.
 void close()
          Close this XML output stream.
 void endDirective()
          Terminate the current directive tag for this XML output stream.
 void endTag()
          Terminate the current element tag for this XML output stream.
protected  void finalize()
          Finalization.
 void flush()
          Flush any pending output to this XML output stream.
 void initialize(java.util.Hashtable parms)
          Initialize this XML output stream.
static void main(java.lang.String[] args)
          Test driver for this class.
 void setNamespace(java.lang.String namesp)
          Establish the namespace prefix for XML tags written to this output stream.
 void startDirective(java.lang.String name)
          Write a directive tag to this XML output stream.
 void startTag(java.lang.String tag)
          Write an element tag to this XML output stream.
 void startTag(java.lang.String namesp, java.lang.String tag)
          Write an element tag to this XML output stream.
protected  void writeName(java.lang.String name)
          Write an identifier name to this XML output stream.
protected  void writeQuoted(java.lang.String val)
          Write a quoted attribute string to this XML output stream.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SERIES

public static final int SERIES
API series number.

See Also:
Constant Field Values

ENT_AMP

protected static final java.lang.String ENT_AMP
Character entity: '&'.

See Also:
Constant Field Values

ENT_LT

protected static final java.lang.String ENT_LT
Character entity: '<'.

See Also:
Constant Field Values

ENT_GT

protected static final java.lang.String ENT_GT
Character entity: '>'.

See Also:
Constant Field Values

ENT_APOS

protected static final java.lang.String ENT_APOS
Character entity: '''.

See Also:
Constant Field Values

ENT_QUOT

protected static final java.lang.String ENT_QUOT
Character entity: '"'.

See Also:
Constant Field Values

ST_TEXT

protected static final short ST_TEXT
Output state: Within an element text content.

See Also:
Constant Field Values

ST_DIR

protected static final short ST_DIR
Output state: Within a directive.

See Also:
Constant Field Values

ST_TAG

protected static final short ST_TAG
Output state: Within an element tag.

See Also:
Constant Field Values

m_out

protected java.io.Writer m_out
Output stream.


m_namesp

protected java.lang.String m_namesp
Default XML namespace prefix.


m_elem

protected java.lang.String m_elem
Current element tag.


m_dir

protected java.lang.String m_dir
Current directive tag.


m_tags

protected java.util.ArrayList m_tags
Nested element tags stack.


m_prefixes

protected java.util.ArrayList m_prefixes
Nested element namespace prefixes stack.


m_colNo

protected int m_colNo
Current output column position (starting at 1).


m_nest

protected int m_nest
XML element node nesting level.


m_state

protected short m_state
Current XML output state.

Constructor Detail

XmlOutputStreamAdapter

public XmlOutputStreamAdapter(java.io.Writer out)
Constructor.

Parameters:
out - The text output stream to which the XML document is to be written.
Since:
1.1, 2005-05-28
Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception
Test driver for this class.

This writes a sample XML document to the standard output stream. See the Example section for details.

Parameters:
args - Command line arguments.
Throws:
java.lang.Exception
Since:
1.1, 2005-02-19

initialize

public void initialize(java.util.Hashtable parms)
Initialize this XML output stream.

This must be the first method to be called on this object, prior to adding any tags or attributes.

This implementation of this method does not do anything. Implementations that extend this class may override this method to have it do something useful.

Specified by:
initialize in interface XmlOutputStreamI
Parameters:
parms - A hash table containing name/value pairs with which to initialize this XML output stream. This argument may be allowed to be null, depending on the implementation of this interface.
Throws:
java.io.IOException - Thrown if the specified hash table entries are malformed, or if some other error occurs.
Since:
1.1, 2005-02-18
See Also:
close()

flush

public void flush()
           throws java.io.IOException
Flush any pending output to this XML output stream.

Specified by:
flush in interface XmlOutputStreamI
Throws:
java.io.IOException - Thrown if an I/O (output) error occurs.
Since:
1.1, 2005-02-18
See Also:
close()

close

public void close()
           throws java.io.IOException
Close this XML output stream.

This must be the last method to be called on this XML output object.

Implementations of this method typically should call the flush() method.

Specified by:
close in interface XmlOutputStreamI
Throws:
java.io.IOException - Thrown if an I/O (output) error occurs.
Since:
1.1, 2005-02-18
See Also:
flush()

setNamespace

public void setNamespace(java.lang.String namesp)
                  throws java.io.IOException
Establish the namespace prefix for XML tags written to this output stream.

This setting stays in force until a subsequent call to this method changes it.

Specified by:
setNamespace in interface XmlOutputStreamI
Parameters:
namesp - The default namespace prefix for subsequent XML tags. Note that the ':' separator should not be included. This argument can be empty ("") or null, in which case there is no default namespace prefix.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18

startDirective

public void startDirective(java.lang.String name)
                    throws java.io.IOException
Write a directive tag to this XML output stream.

Attributes can be added to a directive using the addAttribute() method.

The directive must be terminated by calling the endDirective() method.

Specified by:
startDirective in interface XmlOutputStreamI
Parameters:
name - A directive tag name. For example, a name of "perms" causes an XML directive tag of <?perms?> to be written.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
endDirective(), addAttribute()

endDirective

public void endDirective()
                  throws java.io.IOException
Terminate the current directive tag for this XML output stream.

Specified by:
endDirective in interface XmlOutputStreamI
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
startDirective()

startTag

public void startTag(java.lang.String namesp,
                     java.lang.String tag)
              throws java.io.IOException
Write an element tag to this XML output stream.

The new tag will be nested within the previously unterminated tag, if there is one.

The XML tag must be terminated by calling the endTag() method.

Specified by:
startTag in interface XmlOutputStreamI
Parameters:
namesp - The namespace prefix of the tag, without the ':' separator. This argument can be empty ("") or null, in which case the tag has no namespace prefix.
tag - The name of the tag. For example, a name of "ssn" and a namespace of "emp" will be written to the XML output stream as <emp:ssn>.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
endTag(), startTag()

startTag

public void startTag(java.lang.String tag)
              throws java.io.IOException
Write an element tag to this XML output stream.

The new tag will be nested within the previously unterminated tag, if there is one. The new tag will use the default namespace prefix, if one has been established.

The XML tag must be terminated by calling the endTag() method.

Specified by:
startTag in interface XmlOutputStreamI
Parameters:
tag - The name of the tag. For example, a name of "ssn" and a default namespace of "emp" will be written to the XML output stream as <emp:ssn>.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
setNamespace(), endTag(), startTag()

addAttribute

public void addAttribute(java.lang.String attr,
                         java.lang.String val)
                  throws java.io.IOException
Add an attribute value to the current XML tag.

Specified by:
addAttribute in interface XmlOutputStreamI
Parameters:
attr - An attribute name.
val - The text value of the attribute.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
startTag()

addText

public void addText(java.lang.String text)
             throws java.io.IOException
Append text content to the current XML tag.

This method may be called multiple times, each call appending additional text characters to the content of the current XML tag.

Unprintable characters (e.g., control characters) and special characters (e.g., angle brackets '<' and '>') are written to the output stream as XML character entities (e.g., &#127; or &lt;). Unprintable characters can also be written explicitly using the addCharacter() method.

Each newline sequence (CR \u000D, LF \u000A, or a CR LF pair) is written as a single canonical newline, according to the conventions of the underlying output stream.

Note that this method calls the addCharacter() method for each character in text.

Specified by:
addText in interface XmlOutputStreamI
Parameters:
text - Text characters to append to the content of the current XML tag.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
startTag(), addCharacter()

addCharacter

public void addCharacter(int ch)
                  throws java.io.IOException
Append a character to the text content of the current XML tag.

This method may be called multiple times, each call appending additional text characters to the content of the current XML tag.

Printable characters are written as is to the XML output stream, according to the character encoding of the underlying output stream. Unprintable characters (e.g., control characters) are written as character entities (&#dd;).

A newline sequence (CR \u000D, LF \u000A, or a CR LF pair) is written as a single canonical newline, according to the conventions of the underlying output stream.

Specified by:
addCharacter in interface XmlOutputStreamI
Parameters:
ch - A text character code to append to the content of the current XML tag.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
startTag(), addText()

endTag

public void endTag()
            throws java.io.IOException
Terminate the current element tag for this XML output stream.

Specified by:
endTag in interface XmlOutputStreamI
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
startTag(), startTag()

finalize

protected void finalize()
                 throws java.lang.Throwable
Finalization.

Throws:
java.lang.Throwable
Since:
1.1, 2005-02-18

writeName

protected void writeName(java.lang.String name)
                  throws java.io.IOException
Write an identifier name to this XML output stream.

Parameters:
name - An identifier, i.e., an element tag, directive tag, or attribute name.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18

writeQuoted

protected void writeQuoted(java.lang.String val)
                    throws java.io.IOException
Write a quoted attribute string to this XML output stream.

Parameters:
val - The text value of the attribute.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2005-02-18
See Also:
addAttribute()