1 /*
   2  * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.stream;
  27 
  28 import javax.xml.stream.events.*;
  29 import javax.xml.stream.util.XMLEventConsumer;
  30 import javax.xml.namespace.NamespaceContext;
  31 
  32 /**
  33  *
  34  * This is the top level interface for writing XML documents.
  35  *
  36  * Instances of this interface are not required to validate the
  37  * form of the XML.
  38  *
  39  * @version 1.0
  40  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
  41  * @see XMLEventReader
  42  * @see javax.xml.stream.events.XMLEvent
  43  * @see javax.xml.stream.events.Characters
  44  * @see javax.xml.stream.events.ProcessingInstruction
  45  * @see javax.xml.stream.events.StartElement
  46  * @see javax.xml.stream.events.EndElement
  47  * @since 1.6
  48  */
  49 public interface XMLEventWriter extends XMLEventConsumer {
  50 
  51   /**
  52    * Writes any cached events to the underlying output mechanism
  53    * @throws XMLStreamException if an error occurs
  54    */
  55   public void flush() throws XMLStreamException;
  56 
  57   /**
  58    * Frees any resources associated with this stream
  59    * @throws XMLStreamException if an error occurs
  60    */
  61   public void close() throws XMLStreamException;
  62 
  63   /**
  64    * Add an event to the output stream
  65    * Adding a START_ELEMENT will open a new namespace scope that
  66    * will be closed when the corresponding END_ELEMENT is written.
  67    * <table class="striped">
  68    *   <caption>Required and optional fields for events added to the writer</caption>
  69    *   <thead>
  70    *     <tr>
  71    *       <th scope="col">Event Type</th>
  72    *       <th scope="col">Required Fields</th>
  73    *       <th scope="col">Optional Fields</th>
  74    *       <th scope="col">Required Behavior</th>
  75    *     </tr>
  76    *   </thead>
  77    *   <tbody>
  78    *     <tr>
  79    *       <th scope="row"> START_ELEMENT  </th>
  80    *       <td> QName name </td>
  81    *       <td> namespaces , attributes </td>
  82    *       <td> A START_ELEMENT will be written by writing the name,
  83    *       namespaces, and attributes of the event in XML 1.0 valid
  84    *       syntax for START_ELEMENTs.
  85    *       The name is written by looking up the prefix for
  86    *       the namespace uri.  The writer can be configured to
  87    *       respect prefixes of QNames.  If the writer is respecting
  88    *       prefixes it must use the prefix set on the QName.  The
  89    *       default behavior is to lookup the value for the prefix
  90    *       on the EventWriter's internal namespace context.
  91    *       Each attribute (if any)
  92    *       is written using the behavior specified in the attribute
  93    *       section of this table.  Each namespace (if any) is written
  94    *       using the behavior specified in the namespace section of this
  95    *       table.
  96    *       </td>
  97    *     </tr>
  98    *     <tr>
  99    *       <th scope="row"> END_ELEMENT  </th>
 100    *       <td> Qname name  </td>
 101    *       <td> None </td>
 102    *       <td> A well formed END_ELEMENT tag is written.
 103    *       The name is written by looking up the prefix for
 104    *       the namespace uri.  The writer can be configured to
 105    *       respect prefixes of QNames.  If the writer is respecting
 106    *       prefixes it must use the prefix set on the QName.  The
 107    *       default behavior is to lookup the value for the prefix
 108    *       on the EventWriter's internal namespace context.
 109    *       If the END_ELEMENT name does not match the START_ELEMENT
 110    *       name an XMLStreamException is thrown.
 111    *       </td>
 112    *     </tr>
 113    *     <tr>
 114    *       <th scope="row"> ATTRIBUTE  </th>
 115    *       <td> QName name , String value </td>
 116    *       <td> QName type </td>
 117    *       <td> An attribute is written using the same algorithm
 118    *            to find the lexical form as used in START_ELEMENT.
 119    *            The default is to use double quotes to wrap attribute
 120    *            values and to escape any double quotes found in the
 121    *            value.  The type value is ignored.
 122    *       </td>
 123    *     </tr>
 124    *     <tr>
 125    *       <th scope="row"> NAMESPACE  </th>
 126    *       <td> String prefix, String namespaceURI,
 127    *            boolean isDefaultNamespaceDeclaration
 128    *      </td>
 129    *       <td> None  </td>
 130    *       <td> A namespace declaration is written.  If the
 131    *            namespace is a default namespace declaration
 132    *            (isDefault is true) then xmlns="$namespaceURI"
 133    *            is written and the prefix is optional.  If
 134    *            isDefault is false, the prefix must be declared
 135    *            and the writer must prepend xmlns to the prefix
 136    *            and write out a standard prefix declaration.
 137    *      </td>
 138    *     </tr>
 139    *     <tr>
 140    *       <th scope="row"> PROCESSING_INSTRUCTION  </th>
 141    *       <td>   None</td>
 142    *       <td>   String target, String data</td>
 143    *       <td>   The data does not need to be present and may be
 144    *              null.  Target is required and many not be null.
 145    *              The writer
 146    *              will write data section
 147    *              directly after the target,
 148    *              enclosed in appropriate XML 1.0 syntax
 149    *      </td>
 150    *     </tr>
 151    *     <tr>
 152    *       <th scope="row"> COMMENT  </th>
 153    *       <td> None  </td>
 154    *       <td> String comment  </td>
 155    *       <td> If the comment is present (not null) it is written, otherwise an
 156    *            an empty comment is written
 157    *      </td>
 158    *     </tr>
 159    *     <tr>
 160    *       <th scope="row"> START_DOCUMENT  </th>
 161    *       <td> None  </td>
 162    *       <td> String encoding , boolean standalone, String version  </td>
 163    *       <td> A START_DOCUMENT event is not required to be written to the
 164    *             stream.  If present the attributes are written inside
 165    *             the appropriate XML declaration syntax
 166    *      </td>
 167    *     </tr>
 168    *     <tr>
 169    *       <th scope="row"> END_DOCUMENT  </th>
 170    *       <td> None </td>
 171    *       <td> None  </td>
 172    *       <td> Nothing is written to the output  </td>
 173    *     </tr>
 174    *     <tr>
 175    *       <th scope="row"> DTD  </th>
 176    *       <td> String DocumentTypeDefinition  </td>
 177    *       <td> None  </td>
 178    *       <td> The DocumentTypeDefinition is written to the output  </td>
 179    *     </tr>
 180    *   </tbody>
 181    * </table>
 182    * @param event the event to be added
 183    * @throws XMLStreamException if an error occurs
 184    */
 185   public void add(XMLEvent event) throws XMLStreamException;
 186 
 187   /**
 188    * Adds an entire stream to an output stream,
 189    * calls next() on the inputStream argument until hasNext() returns false
 190    * This should be treated as a convenience method that will
 191    * perform the following loop over all the events in an
 192    * event reader and call add on each event.
 193    *
 194    * @param reader the event stream to add to the output
 195    * @throws XMLStreamException if an error occurs
 196    */
 197 
 198   public void add(XMLEventReader reader) throws XMLStreamException;
 199 
 200   /**
 201    * Gets the prefix the uri is bound to
 202    * @param uri the uri to look up
 203    * @return the prefix
 204    * @throws XMLStreamException if an error occurs
 205    */
 206   public String getPrefix(String uri) throws XMLStreamException;
 207 
 208   /**
 209    * Sets the prefix the uri is bound to.  This prefix is bound
 210    * in the scope of the current START_ELEMENT / END_ELEMENT pair.
 211    * If this method is called before a START_ELEMENT has been written
 212    * the prefix is bound in the root scope.
 213    * @param prefix the prefix to bind to the uri
 214    * @param uri the uri to bind to the prefix
 215    * @throws XMLStreamException if an error occurs
 216    */
 217   public void setPrefix(String prefix, String uri) throws XMLStreamException;
 218 
 219   /**
 220    * Binds a URI to the default namespace
 221    * This URI is bound
 222    * in the scope of the current START_ELEMENT / END_ELEMENT pair.
 223    * If this method is called before a START_ELEMENT has been written
 224    * the uri is bound in the root scope.
 225    * @param uri the uri to bind to the default namespace
 226    * @throws XMLStreamException if an error occurs
 227    */
 228   public void setDefaultNamespace(String uri) throws XMLStreamException;
 229 
 230   /**
 231    * Sets the current namespace context for prefix and uri bindings.
 232    * This context becomes the root namespace context for writing and
 233    * will replace the current root namespace context.  Subsequent calls
 234    * to setPrefix and setDefaultNamespace will bind namespaces using
 235    * the context passed to the method as the root context for resolving
 236    * namespaces.
 237    * @param context the namespace context to use for this writer
 238    * @throws XMLStreamException if an error occurs
 239    */
 240   public void setNamespaceContext(NamespaceContext context)
 241     throws XMLStreamException;
 242 
 243   /**
 244    * Returns the current namespace context.
 245    * @return the current namespace context
 246    */
 247   public NamespaceContext getNamespaceContext();
 248 
 249 
 250 }