/*   Copyright 2004 The Apache Software Foundation
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.apache.xmlbeans.xml.stream;

/**
 *
 * This is the top level interface for iterating over XML Events
 * in an XML document.
 *
 * <p> Difference from SAX </p>
 * <p> An event stream can be thought of encapsulating SAX
 * events. It applies an iterator/pull metaphor to the parser 
 * allowing procedural, stream-based, handling of input XML rather than
 * having to write chained event handlers to handle complex XML
 * documents.
 * <p> Difference from DOM </p>
 * <p>The pull metaphor allows single-pass, stream-based  parsing of the document rather
 * than tree based manipulation.</p>
 *
 * @since XMLInputStream 1.0
 * @version 1.0
 * @see org.apache.xmlbeans.xml.stream.XMLEvent
 * @see org.apache.xmlbeans.xml.stream.CharacterData
 * @see org.apache.xmlbeans.xml.stream.ProcessingInstruction
 * @see org.apache.xmlbeans.xml.stream.StartElement
 * @see org.apache.xmlbeans.xml.stream.EndElement
 * @see org.apache.xmlbeans.xml.stream.CharacterData
 * @see org.apache.xmlbeans.xml.stream.XMLName
 */

// REVIEW pdapkus@bea.com 2002-Sep-13 -- while I like the convenience
// of many of these methods, it strikes me that many of these methods
// could implemented as static methods in a utility class.  the down
// side to having them in this base interface is that it makes the
// contract for implementers unnecessarily steap and results in
// duplicated code in methods that can't extend one of the common base
// classes.  

public interface XMLInputStream {
  /**
   * Get the next XMLEvent on the stream
   * @see org.apache.xmlbeans.xml.stream.XMLEvent
   */
  public XMLEvent next() throws XMLStreamException;
  /**
   * Check if there are more events to pull of the stream
   * @see org.apache.xmlbeans.xml.stream.XMLEvent
   */
  public boolean hasNext() throws XMLStreamException;
  /**
   * Skip the next stream event
   */
  public void skip() throws XMLStreamException;
  /**
   * Skips the entire next start tag / end tag pair.
   */
  public void skipElement() throws XMLStreamException;
  /**
   * Check the next XMLEvent without reading it from the stream.
   * Returns null if the stream is at EOF or has no more XMLEvents.
   * @see org.apache.xmlbeans.xml.stream.XMLEvent
   */
  public XMLEvent peek() throws XMLStreamException;
  /**
   * Position the stream at the next XMLEvent of this type.  The method
   * returns true if the stream contains another XMLEvent of this type
   * and false otherwise.
   * @param eventType An integer code that indicates the element type.
   * @see org.apache.xmlbeans.xml.stream.XMLEvent
   */
  public boolean skip(int eventType) throws XMLStreamException;
  /**
   * Position the stream at the next element of this name.  The method
   * returns true if the stream contains another element with this name
   * and false otherwise.  Skip is a forward operator only.  It does
   * not look backward in the stream.
   * @param name An object that defines an XML name.
   * If the XMLName.getNameSpaceName() method on the XMLName argument returns
   * null the XMLName will match just the local name.  Prefixes are
   * not checked for equality.
   * @see org.apache.xmlbeans.xml.stream.XMLName
   */
  public boolean skip(XMLName name) throws XMLStreamException;
  /**
   * Position the stream at the next element of this name and this type.
   * The method returns true if the stream contains another element 
   * with this name of this type and false otherwise.  
   * @param name An object that defines an XML name.
   * If the XMLName.getNameSpaceName() method on the XMLName argument returns
   * null the XMLName will match just the local name.  Prefixes are
   * not checked for equality.
   * @param eventType An integer code that indicates the element type.
   * @see org.apache.xmlbeans.xml.stream.XMLEvent
   * @see org.apache.xmlbeans.xml.stream.XMLName
   */
  public boolean skip(XMLName name, int eventType) throws XMLStreamException;
  /**
   * getSubStream() returns a stream which points to the entire next element in the
   * current stream.  For example: take a document that has a root node A, where the children
   * of A are B, C, and D. If the stream is pointing to the start element of A, getSubStream() will return 
   * A, B, C and D including the start element of A and the end element of A.  The position of the parent
   * stream is not changed and the events read by the substream are written back to its parent.   
   */
  public XMLInputStream getSubStream() throws XMLStreamException;
  /**
   * Closes this input stream and releases any system resources associated with the stream.
   */
  public void close() throws XMLStreamException;

  /**
   * Returns the reference resolver that was set for this stream,
   * returns null if no ReferenceResolver has been set.
   * @see org.apache.xmlbeans.xml.stream.ReferenceResolver
   */
  public ReferenceResolver getReferenceResolver();
  /**
   * Provides a way to set the ReferenceResolver of the stream,
   * this is mostly needed for handle references to other parts of the
   * document.
   * @see org.apache.xmlbeans.xml.stream.ReferenceResolver
   */
  public void setReferenceResolver(ReferenceResolver resolver);
}