--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jaxp/src/javax/xml/stream/XMLEventWriter.java Thu Apr 12 08:38:26 2012 -0700
@@ -0,0 +1,256 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * 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();
+
+
+}