Java tutorial
/* * 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(); }