/*
 * 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.namespace.NamespaceContext;

/**
 * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does
 * not perform well formedness checking on its input. However
 * the writeCharacters method is required to escape & , < and >
 * For attribute values the writeAttribute method will escape the
 * above characters plus " to ensure that all character content
 * and attribute values are well formed.
 *
 * Each NAMESPACE
 * and ATTRIBUTE must be individually written.
 *
 * <table border="1" cellpadding="2" cellspacing="0">
 * <thead>
 * <tr>
 * <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th>
 * </tr>
 * <tr>
 * <th>Method</th> <!-- method -->
 * <th colspan="2"><code>isRepairingNamespaces</code> == true</th>
 * <th colspan="2"><code>isRepairingNamespaces</code> == false</th>
 * </tr>
 * <tr>
 * <th></th> <!-- method -->
 * <th>namespaceURI bound</th>
 * <th>namespaceURI unbound</th>
 * <th>namespaceURI bound</th>
 * <th>namespaceURI unbound</th>
 * </tr>
 * </thead>
 *
 * <tbody>
 * <tr>
 * <th><code>writeAttribute(namespaceURI, localName, value)</code></th>
 * <!-- isRepairingNamespaces == true -->
 * <td>
 * <!-- namespaceURI bound -->
 * prefix:localName="value"&nbsp;<sup>[1]</sup>
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * xmlns:{generated}="namespaceURI" {generated}:localName="value"
 * </td>
 * <!-- isRepairingNamespaces == false -->
 * <td>
 * <!-- namespaceURI bound -->
 * prefix:localName="value"&nbsp;<sup>[1]</sup>
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * <code>XMLStreamException</code>
 * </td>
 * </tr>
 *
 * <tr>
 * <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th>
 * <!-- isRepairingNamespaces == true -->
 * <td>
 * <!-- namespaceURI bound -->
 * bound to same prefix:<br />
 * prefix:localName="value"&nbsp;<sup>[1]</sup><br />
 * <br />
 * bound to different prefix:<br />
 * xmlns:{generated}="namespaceURI" {generated}:localName="value"
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * xmlns:prefix="namespaceURI" prefix:localName="value"&nbsp;<sup>[3]</sup>
 * </td>
 * <!-- isRepairingNamespaces == false -->
 * <td>
 * <!-- namespaceURI bound -->
 * bound to same prefix:<br />
 * prefix:localName="value"&nbsp;<sup>[1][2]</sup><br />
 * <br />
 * bound to different prefix:<br />
 * <code>XMLStreamException</code><sup>[2]</sup>
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * xmlns:prefix="namespaceURI" prefix:localName="value"&nbsp;<sup>[2][5]</sup>
 * </td>
 * </tr>
 *
 * <tr>
 * <th><code>writeStartElement(namespaceURI, localName)</code><br />
 * <br />
 * <code>writeEmptyElement(namespaceURI, localName)</code></th>
 * <!-- isRepairingNamespaces == true -->
 * <td >
 * <!-- namespaceURI bound -->
 * &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup>
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt;
 * </td>
 * <!-- isRepairingNamespaces == false -->
 * <td>
 * <!-- namespaceURI bound -->
 * &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup>
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * <code>XMLStreamException</code>
 * </td>
 * </tr>
 *
 * <tr>
 * <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br />
 * <br />
 * <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th>
 * <!-- isRepairingNamespaces == true -->
 * <td>
 * <!-- namespaceURI bound -->
 * bound to same prefix:<br />
 * &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br />
 * <br />
 * bound to different prefix:<br />
 * &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt;
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * &lt;prefix:localName xmlns:prefix="namespaceURI"&gt;&nbsp;<sup>[4]</sup>
 * </td>
 * <!-- isRepairingNamespaces == false -->
 * <td>
 * <!-- namespaceURI bound -->
 * bound to same prefix:<br />
 * &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br />
 * <br />
 * bound to different prefix:<br />
 * <code>XMLStreamException</code>
 * </td>
 * <td>
 * <!-- namespaceURI unbound -->
 * &lt;prefix:localName&gt;&nbsp;
 * </td>
 * </tr>
 * </tbody>
 * <tfoot>
 * <tr>
 * <td colspan="5">
 * Notes:
 * <ul>
 * <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li>
 * <li>[2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written</li>
 * <li>[3] if prefix == "" || null, then a prefix is randomly generated</li>
 * <li>[4] if prefix == "" || null, then it is treated as the default Namespace and no prefix is generated or written, an xmlns declaration is generated and written if the namespaceURI is unbound</li>
 * <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</li>
 * </ul>
 * </td>
 * </tr>
 * </tfoot>
 * </table>
 *
 * @version 1.0
 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
 * @see XMLOutputFactory
 * @see XMLStreamReader
 * @since 1.6
 */
public interface XMLStreamWriter {

 /**
 * Writes a start tag to the output. All writeStartElement methods
 * open a new scope in the internal namespace context. Writing the
 * corresponding EndElement causes the scope to be closed.
 * @param localName local name of the tag, may not be null
 * @throws XMLStreamException
 */
 public void writeStartElement(String localName)
 throws XMLStreamException;

 /**
 * Writes a start tag to the output
 * @param namespaceURI the namespaceURI of the prefix to use, may not be null
 * @param localName local name of the tag, may not be null
 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
 * javax.xml.stream.isRepairingNamespaces has not been set to true
 */
 public void writeStartElement(String namespaceURI, String localName)
 throws XMLStreamException;

 /**
 * Writes a start tag to the output
 * @param localName local name of the tag, may not be null
 * @param prefix the prefix of the tag, may not be null
 * @param namespaceURI the uri to bind the prefix to, may not be null
 * @throws XMLStreamException
 */
 public void writeStartElement(String prefix,
 String localName,
 String namespaceURI)
 throws XMLStreamException;

 /**
 * Writes an empty element tag to the output
 * @param namespaceURI the uri to bind the tag to, may not be null
 * @param localName local name of the tag, may not be null
 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
 * javax.xml.stream.isRepairingNamespaces has not been set to true
 */
 public void writeEmptyElement(String namespaceURI, String localName)
 throws XMLStreamException;

 /**
 * Writes an empty element tag to the output
 * @param prefix the prefix of the tag, may not be null
 * @param localName local name of the tag, may not be null
 * @param namespaceURI the uri to bind the tag to, may not be null
 * @throws XMLStreamException
 */
 public void writeEmptyElement(String prefix, String localName, String namespaceURI)
 throws XMLStreamException;

 /**
 * Writes an empty element tag to the output
 * @param localName local name of the tag, may not be null
 * @throws XMLStreamException
 */
 public void writeEmptyElement(String localName)
 throws XMLStreamException;

 /**
 * Writes string data to the output without checking for well formedness.
 * The data is opaque to the XMLStreamWriter, i.e. the characters are written
 * blindly to the underlying output. If the method cannot be supported
 * in the currrent writing context the implementation may throw a
 * UnsupportedOperationException. For example note that any
 * namespace declarations, end tags, etc. will be ignored and could
 * interfere with proper maintanence of the writers internal state.
 *
 * @param data the data to write
 */
 // public void writeRaw(String data) throws XMLStreamException;

 /**
 * Writes an end tag to the output relying on the internal
 * state of the writer to determine the prefix and local name
 * of the event.
 * @throws XMLStreamException
 */
 public void writeEndElement()
 throws XMLStreamException;

 /**
 * Closes any start tags and writes corresponding end tags.
 * @throws XMLStreamException
 */
 public void writeEndDocument()
 throws XMLStreamException;

 /**
 * Close this writer and free any resources associated with the
 * writer. This must not close the underlying output stream.
 * @throws XMLStreamException
 */
 public void close()
 throws XMLStreamException;

 /**
 * Write any cached data to the underlying output mechanism.
 * @throws XMLStreamException
 */
 public void flush()
 throws XMLStreamException;

 /**
 * Writes an attribute to the output stream without
 * a prefix.
 * @param localName the local name of the attribute
 * @param value the value of the attribute
 * @throws IllegalStateException if the current state does not allow Attribute writing
 * @throws XMLStreamException
 */
 public void writeAttribute(String localName, String value)
 throws XMLStreamException;

 /**
 * Writes an attribute to the output stream
 * @param prefix the prefix for this attribute
 * @param namespaceURI the uri of the prefix for this attribute
 * @param localName the local name of the attribute
 * @param value the value of the attribute
 * @throws IllegalStateException if the current state does not allow Attribute writing
 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
 * javax.xml.stream.isRepairingNamespaces has not been set to true
 */

 public void writeAttribute(String prefix,
 String namespaceURI,
 String localName,
 String value)
 throws XMLStreamException;

 /**
 * Writes an attribute to the output stream
 * @param namespaceURI the uri of the prefix for this attribute
 * @param localName the local name of the attribute
 * @param value the value of the attribute
 * @throws IllegalStateException if the current state does not allow Attribute writing
 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
 * javax.xml.stream.isRepairingNamespaces has not been set to true
 */
 public void writeAttribute(String namespaceURI,
 String localName,
 String value)
 throws XMLStreamException;

 /**
 * Writes a namespace to the output stream
 * If the prefix argument to this method is the empty string,
 * "xmlns", or null this method will delegate to writeDefaultNamespace
 *
 * @param prefix the prefix to bind this namespace to
 * @param namespaceURI the uri to bind the prefix to
 * @throws IllegalStateException if the current state does not allow Namespace writing
 * @throws XMLStreamException
 */
 public void writeNamespace(String prefix, String namespaceURI)
 throws XMLStreamException;

 /**
 * Writes the default namespace to the stream
 * @param namespaceURI the uri to bind the default namespace to
 * @throws IllegalStateException if the current state does not allow Namespace writing
 * @throws XMLStreamException
 */
 public void writeDefaultNamespace(String namespaceURI)
 throws XMLStreamException;

 /**
 * Writes an xml comment with the data enclosed
 * @param data the data contained in the comment, may be null
 * @throws XMLStreamException
 */
 public void writeComment(String data)
 throws XMLStreamException;

 /**
 * Writes a processing instruction
 * @param target the target of the processing instruction, may not be null
 * @throws XMLStreamException
 */
 public void writeProcessingInstruction(String target)
 throws XMLStreamException;

 /**
 * Writes a processing instruction
 * @param target the target of the processing instruction, may not be null
 * @param data the data contained in the processing instruction, may not be null
 * @throws XMLStreamException
 */
 public void writeProcessingInstruction(String target,
 String data)
 throws XMLStreamException;

 /**
 * Writes a CData section
 * @param data the data contained in the CData Section, may not be null
 * @throws XMLStreamException
 */
 public void writeCData(String data)
 throws XMLStreamException;

 /**
 * Write a DTD section. This string represents the entire doctypedecl production
 * from the XML 1.0 specification.
 *
 * @param dtd the DTD to be written
 * @throws XMLStreamException
 */
 public void writeDTD(String dtd)
 throws XMLStreamException;

 /**
 * Writes an entity reference
 * @param name the name of the entity
 * @throws XMLStreamException
 */
 public void writeEntityRef(String name)
 throws XMLStreamException;

 /**
 * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
 * @throws XMLStreamException
 */
 public void writeStartDocument()
 throws XMLStreamException;

 /**
 * Write the XML Declaration. Defaults the XML version to 1.0
 * @param version version of the xml document
 * @throws XMLStreamException
 */
 public void writeStartDocument(String version)
 throws XMLStreamException;

 /**
 * Write the XML Declaration. Note that the encoding parameter does
 * not set the actual encoding of the underlying output. That must
 * be set when the instance of the XMLStreamWriter is created using the
 * XMLOutputFactory
 * @param encoding encoding of the xml declaration
 * @param version version of the xml document
 * @throws XMLStreamException If given encoding does not match encoding
 * of the underlying stream
 */
 public void writeStartDocument(String encoding,
 String version)
 throws XMLStreamException;

 /**
 * Write text to the output
 * @param text the value to write
 * @throws XMLStreamException
 */
 public void writeCharacters(String text)
 throws XMLStreamException;

 /**
 * Write text to the output
 * @param text the value to write
 * @param start the starting position in the array
 * @param len the number of characters to write
 * @throws XMLStreamException
 */
 public void writeCharacters(char[] text, int start, int len)
 throws XMLStreamException;

 /**
 * Gets the prefix the uri is bound to
 * @return the prefix or null
 * @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, may not be null
 * @param uri the uri to bind to the prefix, may be null
 * @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, may be null
 * @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. This method may only be called once at the start of
 * the document. It does not cause the namespaces to be declared.
 * If a namespace URI to prefix mapping is found in the namespace
 * context it is treated as declared and the prefix may be used
 * by the StreamWriter.
 * @param context the namespace context to use for this writer, may not be null
 * @throws XMLStreamException
 */
 public void setNamespaceContext(NamespaceContext context)
 throws XMLStreamException;

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

 /**
 * Get the value of a feature/property from the underlying implementation
 * @param name The name of the property, may not be null
 * @return The value of the property
 * @throws IllegalArgumentException if the property is not supported
 * @throws NullPointerException if the name is null
 */
 public Object getProperty(java.lang.String name) throws IllegalArgumentException;

}