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