/* |
|
* Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. |
|
* 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. |
|
*/ |
|
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 class="striped"> |
|
* <caption>Required and optional fields for events added to the writer</caption> |
|
* <thead> |
|
* <tr> |
|
* <th scope="col">Event Type</th> |
|
* <th scope="col">Required Fields</th> |
|
* <th scope="col">Optional Fields</th> |
|
* <th scope="col">Required Behavior</th> |
|
* </tr> |
|
* </thead> |
|
* <tbody> |
|
* <tr> |
|
* <th scope="row"> START_ELEMENT </th> |
|
* <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> |
|
* <th scope="row"> END_ELEMENT </th> |
|
* <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> |
|
* <th scope="row"> ATTRIBUTE </th> |
|
* <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> |
|
* <th scope="row"> NAMESPACE </th> |
|
* <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> |
|
* <th scope="row"> PROCESSING_INSTRUCTION </th> |
|
* <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> |
|
* <th scope="row"> COMMENT </th> |
|
* <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> |
|
* <th scope="row"> START_DOCUMENT </th> |
|
* <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> |
|
* <th scope="row"> END_DOCUMENT </th> |
|
* <td> None </td> |
|
* <td> None </td> |
|
* <td> Nothing is written to the output </td> |
|
* </tr> |
|
* <tr> |
|
* <th scope="row"> DTD </th> |
|
* <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(); |
|
} |