tribble.xml
Interface XmlOutputStreamI

All Known Implementing Classes:

XmlOutputStreamAdapter

public interface XmlOutputStreamI

Generic XML output stream.

Usage

Implementations of this interface provide the capability of writing XML documents. They should provide at least one constructor or method that specifies an underlying output stream for the XML output.

    import tribble.xml.*;

    public class MyXmlOutputStream
        implements tribble.xml.XmlOutputStreamI
    {
        public MyXmlOutputStream(java.io.OutputStream out) ...;
        ...
    }
 

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:

    XmlOutputStreamI    xml;
    Properties          props;

    xml = new MyXmlOutputStream(...);
    props = ...;
    xml.initialize(props);
 

Next we specify that we want an <?xml> directive node 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> node, 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 nodes, 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> node 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 nodes:

    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> node

    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 node (emp:employee):

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

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: 1.1 $ $Date: 2005/02/19 07:10:34 $

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.

See Also:

XmlReaderI

Field Summary

static java.lang.String	REV Revision information.
static int	SERIES API series number.

Method Summary

void	addAttribute(java.lang.String attr, java.lang.String val) Add an attribute value to the current XML element.
void	addCharacter(int ch) Append a character to the text content of the current XML element.
void	addText(java.lang.String text) Append text content to the current XML element.
void	close() Close this XML output stream.
void	endDirective() Terminate the current directive node for this XML output stream.
void	endTag() Terminate the current element node for this XML output stream.
void	flush() Flush any pending output to this XML output stream.
void	initialize(java.util.Hashtable parms) Initialize this XML output stream.
void	setNamespace(java.lang.String namesp) Establish the namespace prefix for XML element nodes written to this output stream.
void	startDirective(java.lang.String name) Write a directive node to this XML output stream.
void	startTag(java.lang.String tag) Write an element node to this XML output stream.
void	startTag(java.lang.String namesp, java.lang.String tag) Write an element node to this XML output stream.

Field Detail

REV

public static final java.lang.String REV

Revision information.

See Also:

Constant Field Values

SERIES

public static final int SERIES

API series number.

See Also:

Constant Field Values

Method Detail

initialize

public void initialize(java.util.Hashtable parms)
                throws java.io.IOException

Initialize this XML output stream.

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

The implementation of this interface may allow this method to be called more than once.

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.

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.

Throws:

java.io.IOException - Thrown if an I/O (output) error occurs.

Since:

1.1, 2005-02-18

See Also:

initialize(), flush()

setNamespace

public void setNamespace(java.lang.String namesp)
                  throws java.io.IOException

Establish the namespace prefix for XML element nodes written to this output stream.

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

Parameters:

namesp - The default namespace prefix for subsequent XML elements. 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 node to this XML output stream.

For example, the call

    startDirective("xml"); 

writes the following to the output stream:

    <?xml> 

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

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

Parameters:

name - A directive node name. For example, a name of "perms" causes an XML directive element 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 node for this XML output stream.

This call closes the directive node opened by a previous call to startDirective().

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 node to this XML output stream.

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

For example, the call

    startTag("ns", "tag"); 

writes the following to the output stream:

    <ns:tag> 

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

Parameters:

namesp - The namespace prefix of the element, without the ':' separator. This argument can be empty ("") or null, in which case the node has no namespace prefix.

tag - The name of the element. 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:

startTag(), endTag(), addAttribute()

startTag

public void startTag(java.lang.String tag)
              throws java.io.IOException

Write an element node to this XML output stream.

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

For example, the call

    startTag("tag"); 

writes the following to the output stream:

    <ns:tag> 

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

Parameters:

tag - The name of the element. 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:

startTag(), setNamespace(), endTag(), addAttribute()

endTag

public void endTag()
            throws java.io.IOException

Terminate the current element node for this XML output stream.

This call closes the element opened by a previous call to startTag().

For example, the call

    endTag(); 

writes the following to the output stream:

    </ns:tag> 

Throws:

java.io.IOException - Thrown if an I/O (write) error occurs.

Since:

1.1, 2005-02-18

See Also:

startTag(), 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 element.

For example, the call

    addAttribute("size", "80"); 

writes the following to the output stream:

    size="80" 

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

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

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 can be implemented to call the addCharacter() method for each character in text.

Parameters:

text - Text characters to append to the content of the current XML element.

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

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

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.

Parameters:

ch - A text character code to append to the content of the current XML element.

Throws:

java.io.IOException - Thrown if an I/O (write) error occurs.

Since:

1.1, 2005-02-18

See Also:

startTag(), addText()