//==============================================================================
// XmlWriterI.java
//------------------------------------------------------------------------------

package tribble.xml;


// System imports

import java.io.IOException;
import java.io.Writer;

import java.lang.Exception;
import java.lang.IllegalStateException;
import java.lang.String;


// Local imports

// (None)


/*******************************************************************************
* XML document writer.
*
* <p>
* This interface is used to implement any kind of high-level output stream that
* writes XML documents.  XML documents are written in a "push" fashion, where
* each item (node tag, attribute, and text content) is written individually
* by request.
*
* <p>
* Implementations of this interface should provide at least one constructor that
* takes some kind of output text stream (such as a <tt>java.io.Writer</tt> or
* <tt>java.io.OutputStream</tt>) as input.
* For example:
* <pre>
*    class <b>MyXmlWriter</b>
*        implements tribble.xml.XmlWriterI
*    {
*        // Constructor
*        public <b>MyXmlWriter</b>(java.io.Writer out)
*        {
*            ...
*        }
*
*        ...
*    } </pre>
*
* <!------------------------------------------------------------------------ -->
*<!-- INCOMPLETE
* <p>
* <b> Usage </b>
*
* <p>
* The typical use of an XML writer class is:
* <pre>
+INCOMPLETE
* </pre>
*!-->
*
* <!------------------------------------------------------------------------ -->
* @version	$Revision: 1.2 $ $Date: 2003/04/16 03:16:55 $
* @since	2003-04-13
* @author
*	David R. Tribble
*	(<a href="mailto:david@tribble.com">david@tribble.com</a>).
*	<br>
*	Copyright ©2003 by David R. Tribble, all rights reserved.
*	<br>
*	Permission is granted to freely use and distribute this source code
*	provided that the original copyright and authorship notices remain
*	intact.
*
* @see	XmlReaderI
*/

public interface XmlWriterI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/xml/XmlWriterI.java $Revision: 1.2 $ $Date: 2003/04/16 03:16:55 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constants

    // (None)


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods

    /***************************************************************************
    * Write an XML element to this XML output stream.
    *
    * @param	ent
    * An XML tagged element.
    *
    * @throws	IOException
    * Thrown if an I/O (write) error occurs.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if this writer is not in the proper state for writing an element.
    *
    * @since	1.1, 2003-04-13
    */

    public void writeElement(XmlElementI ent)
        throws IOException;


    /***************************************************************************
    * Write an XML element attribute to this XML output stream.
    *
    * @param	attr
    * An XML element attribute.
    *
    * @throws	IOException
    * Thrown if an I/O (write) error occurs.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if this writer is not in the proper state for writing an element
    * attribute.
    *
    * @since	1.1, 2003-04-13
    */

    public void writeAttribute(XmlAttributeI attr)
        throws IOException;


    /***************************************************************************
    * Write the text content of the current XML element to this XML output
    * stream.
    *
    * @param	text
    * Text contents of the current XML element.
    *
    * @throws	IOException
    * Thrown if an I/O (write) error occurs.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if this writer is not in the proper state for writing the text
    * contents of an element.
    *
    * @since	1.1, 2003-04-13
    */

    public void writeText(String text)
        throws IOException;


    /***************************************************************************
    * Write a comment to this XML output stream.
    *
    * @param	text
    * Comment text.
    *
    * @throws	IOException
    * Thrown if an I/O (write) error occurs.
    *
    * @throws	IllegalStateException (unchecked)
    * Thrown if this writer is not in the proper state for writing a comment.
    *
    * @since	1.2, 2003-04-15
    */

    public void writeComment(String text)
        throws IOException;
}

// End XmlWriterI.java