package javax.xml.stream;

import javax.xml.stream.events.*;
import javax.xml.stream.util.XMLEventConsumer;
import javax.xml.namespace.NamespaceContext;

/**
 *
 * This is the top level interface for writing XML documents.
 *
 * Instances of this interface are not required to validate the 
 * form of the XML.  
 *
 * @version 1.0
 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
 * @see XMLEventReader
 * @see javax.xml.stream.events.XMLEvent
 * @see javax.xml.stream.events.Characters
 * @see javax.xml.stream.events.ProcessingInstruction
 * @see javax.xml.stream.events.StartElement
 * @see javax.xml.stream.events.EndElement
 * @since 1.6
 */
public interface XMLEventWriter extends XMLEventConsumer {

  /**
   * Writes any cached events to the underlying output mechanism
   * @throws XMLStreamException
   */
  public void flush() throws XMLStreamException;

  /**
   * Frees any resources associated with this stream
   * @throws XMLStreamException
   */
  public void close() throws XMLStreamException;

  /**
   * Add an event to the output stream
   * Adding a START_ELEMENT will open a new namespace scope that 
   * will be closed when the corresponding END_ELEMENT is written.
   * <table border="2" rules="all" cellpadding="4">
   *   <thead>
   *     <tr>
   *       <th align="center" colspan="2">
   *         Required and optional fields for events added to the writer 
   *       </th>
   *     </tr>
   *   </thead>
   *   <tbody>
   *     <tr>
   *       <th>Event Type</th>
   *       <th>Required Fields</th>
   *       <th>Optional Fields</th>
   *       <th>Required Behavior</th>
   *     </tr>
   *     <tr>
   *       <td> START_ELEMENT  </td>
   *       <td> QName name </td>
   *       <td> namespaces , attributes </td>
   *       <td> A START_ELEMENT will be written by writing the name, 
   *       namespaces, and attributes of the event in XML 1.0 valid
   *       syntax for START_ELEMENTs.  
   *       The name is written by looking up the prefix for
   *       the namespace uri.  The writer can be configured to 
   *       respect prefixes of QNames.  If the writer is respecting
   *       prefixes it must use the prefix set on the QName.  The
   *       default behavior is to lookup the value for the prefix
   *       on the EventWriter's internal namespace context.   
   *       Each attribute (if any)
   *       is written using the behavior specified in the attribute
   *       section of this table.  Each namespace (if any) is written
   *       using the behavior specified in the namespace section of this
   *       table. 
   *       </td>
   *     </tr>
   *     <tr>
   *       <td> END_ELEMENT  </td>
   *       <td> Qname name  </td>
   *       <td> None </td>
   *       <td> A well formed END_ELEMENT tag is written.
   *       The name is written by looking up the prefix for
   *       the namespace uri.  The writer can be configured to 
   *       respect prefixes of QNames.  If the writer is respecting
   *       prefixes it must use the prefix set on the QName.  The
   *       default behavior is to lookup the value for the prefix
   *       on the EventWriter's internal namespace context. 
   *       If the END_ELEMENT name does not match the START_ELEMENT
   *       name an XMLStreamException is thrown.
   *       </td>
   *     </tr>
   *     <tr>
   *       <td> ATTRIBUTE  </td>
   *       <td> QName name , String value </td>
   *       <td> QName type </td>
   *       <td> An attribute is written using the same algorithm
   *            to find the lexical form as used in START_ELEMENT.
   *            The default is to use double quotes to wrap attribute
   *            values and to escape any double quotes found in the
   *            value.  The type value is ignored.