tribble.xml
Class XmlOutputStreamAdapter

java.lang.Object
  tribble.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()