//==============================================================================
// XmlItemI.java
//------------------------------------------------------------------------------

package tribble.xml;


// System imports

import java.io.IOException;
import java.io.Reader;

import java.lang.Exception;
import java.lang.String;
import java.lang.UnsupportedOperationException;

// Local imports

// (None)


/*******************************************************************************
* XML item.
*
* <p>
* All XML elements, nodes, attributes, text contents, etc., implement this
* interface.
*
* <p>
* There are five types of XML items:
*
* <dl>
*  <p>
*  <dt> Attribute
*  <dd>
*   This is name/value pair within a tagged element or directive.
*   The value part is optional.
*   <br>
*   For example: <br>
*   <tt>sku='JR-243(H)' delivery-required</tt>
*
*  <p>
*  <dt> Comment
*  <dd>
*   This is one or more lines of comment text, which do not affect the content
*   or meaning of the document.
*   Comments may appear anywhere a tagged element can appear.
*   <br>
*   For example: <br>
*   <tt>&lt;!-- Customer record updated 2003-06-17 12:56:24 --&gt;</tt>
*
*  <p>
*  <dt> Directive
*  <dd>
*   This is an out-of-band directive, which may contain attributes.
*   <br>
*   For example: <br>
*   <tt>&lt;?xml version='1.0'?&gt;</tt>
*
*  <p>
*  <dt> Element
*  <dd>
*   This is a tagged node, which may contain attributes, content text, and
*   other (nested) tagged elements.
*   <br>
*   For example: <br>
*   <tt>&lt;item sku='JR-243(H)'&gt;Business desk, oak finish&lt;/item&gt;</tt>
*
*  <p>
*  <dt> Text
*  <dd>
*   This is content text of a tagged element.
*   Elements are not required to have content text.
*   Content text can have leading and trailing whitespace characters, and
*   may contain multiple newlines.
*   <br>
*   For example: <br>
*   <tt>&lt;item&gt;Business desk, oak finish&lt;/item&gt;</tt>
*
* </dl>
*
* <!------------------------------------------------------------------------ -->
* @version	$Revision: 1.4 $ $Date: 2003/07/17 01:11:29 $
* @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.
*/

public interface XmlItemI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/xml/XmlItemI.java $Revision: 1.4 $ $Date: 2003/07/17 01:11:29 $\n";


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

    //----------------------------------
    // XML item types

    /** Item type: Unknown. */
    public static final String		TYPE_UNKNOWN =		"unknown";

    /** Item type: Attribute. */
    public static final String		TYPE_ATTRIBUTE =	"attribute";

    /** Item type: Comment. */
    public static final String		TYPE_COMMENT =		"comment";

    /** Item type: Directive element. */
    public static final String		TYPE_DIRECTIVE =	"directive";

    /** Item type: Element (tagged node). */
    public static final String		TYPE_ELEMENT =		"element";

    /** Item type: Text content. */
    public static final String		TYPE_TEXT =		"text";


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

    /***************************************************************************
    * Retrieve the type of this XML item.
    *
    * @return
    * Type of this item, which is one of the
    * <a href="#TYPE_UNKNOWN"><tt>TYPE_<i>XXX</i></tt></a> constants.
    *
    * @since	1.1, 2003-04-13
    */

    public String getType();
        /*const*/


    /***************************************************************************
    * Retrieve the source line number of this XML item.
    *
    * @return
    * Line number of the XML input source stream from which this item was
    * read (starting at 1), or zero if the line number is not available.
    *
    * @since	1.1, 2003-04-13
    */

    public int getLineNumber();
        /*const*/


    /***************************************************************************
    * Retrieve the source column number of this XML item.
    *
    * @return
    * Column number of the XML input source stream from which this item was
    * read (starting at 1), or zero if the source column number is not
    * available.
    *
    * @since	1.1, 2003-04-13
    */

    public int getColumnNumber();
        /*const*/


    /***************************************************************************
    * Retrieve the parent element of this XML item.
    *
    * <p>
    * Parsers are not required to implement this method.
    * If this method is not implemented, it must throw a
    * <tt>java.lang.UnsupportedOperationException</tt>.
    *
    * @return
    * The XML element that contains this XML item.
    * Note that the top-most element has no parent (i.e., its parent is null).
    *
    * @throws	UnsupportedOperationException (unchecked)
    * Thrown if this method is not implemented.
    *
    * @since	1.4, 2003-07-06
    */

    public XmlElementI getParentElement();
        /*const*/
}

// End XmlItemI.java