/*
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

/*
 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
 */

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) 2009 by Oracle Corporation. 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.
 * </td>
 * </tr>
 * <tr>
 * <td> NAMESPACE </td>
 * <td> String prefix, String namespaceURI,
 * boolean isDefaultNamespaceDeclaration
 * </td>
 * <td> None </td>
 * <td> A namespace declaration is written. If the
 * namespace is a default namespace declaration
 * (isDefault is true) then xmlns="$namespaceURI"
 * is written and the prefix is optional. If
 * isDefault is false, the prefix must be declared
 * and the writer must prepend xmlns to the prefix
 * and write out a standard prefix declaration.
 * </td>
 * </tr>
 * <tr>
 * <td> PROCESSING_INSTRUCTION </td>
 * <td> None</td>
 * <td> String target, String data</td>
 * <td> The data does not need to be present and may be
 * null. Target is required and many not be null.
 * The writer
 * will write data section
 * directly after the target,
 * enclosed in appropriate XML 1.0 syntax
 * </td>
 * </tr>
 * <tr>
 * <td> COMMENT </td>
 * <td> None </td>
 * <td> String comment </td>
 * <td> If the comment is present (not null) it is written, otherwise an
 * an empty comment is written
 * </td>
 * </tr>
 * <tr>
 * <td> START_DOCUMENT </td>
 * <td> None </td>
 * <td> String encoding , boolean standalone, String version </td>
 * <td> A START_DOCUMENT event is not required to be written to the
 * stream. If present the attributes are written inside
 * the appropriate XML declaration syntax
 * </td>
 * </tr>
 * <tr>
 * <td> END_DOCUMENT </td>
 * <td> None </td>
 * <td> None </td>
 * <td> Nothing is written to the output </td>
 * </tr>
 * <tr>
 * <td> DTD </td>
 * <td> String DocumentTypeDefinition </td>
 * <td> None </td>
 * <td> The DocumentTypeDefinition is written to the output </td>
 * </tr>
 * </tbody>
 * </table>
 * @param event the event to be added
 * @throws XMLStreamException
 */
 public void add(XMLEvent event) throws XMLStreamException;

 /**
 * Adds an entire stream to an output stream,
 * calls next() on the inputStream argument until hasNext() returns false
 * This should be treated as a convenience method that will
 * perform the following loop over all the events in an
 * event reader and call add on each event.
 *
 * @param reader the event stream to add to the output
 * @throws XMLStreamException
 */

 public void add(XMLEventReader reader) throws XMLStreamException;

 /**
 * Gets the prefix the uri is bound to
 * @param uri the uri to look up
 * @throws XMLStreamException
 */
 public String getPrefix(String uri) throws XMLStreamException;

 /**
 * Sets the prefix the uri is bound to. This prefix is bound
 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
 * If this method is called before a START_ELEMENT has been written
 * the prefix is bound in the root scope.
 * @param prefix the prefix to bind to the uri
 * @param uri the uri to bind to the prefix
 * @throws XMLStreamException
 */
 public void setPrefix(String prefix, String uri) throws XMLStreamException;

 /**
 * Binds a URI to the default namespace
 * This URI is bound
 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
 * If this method is called before a START_ELEMENT has been written
 * the uri is bound in the root scope.
 * @param uri the uri to bind to the default namespace
 * @throws XMLStreamException
 */
 public void setDefaultNamespace(String uri) throws XMLStreamException;

 /**
 * Sets the current namespace context for prefix and uri bindings.
 * This context becomes the root namespace context for writing and
 * will replace the current root namespace context. Subsequent calls
 * to setPrefix and setDefaultNamespace will bind namespaces using
 * the context passed to the method as the root context for resolving
 * namespaces.
 * @param context the namespace context to use for this writer
 * @throws XMLStreamException
 */
 public void setNamespaceContext(NamespaceContext context)
 throws XMLStreamException;

 /**
 * Returns the current namespace context.
 * @return the current namespace context
 */
 public NamespaceContext getNamespaceContext();


}