1 /* 2 * Copyright (c) 2009, 2017, 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 54 */ 55 public void flush() throws XMLStreamException; 56 57 /** 58 * Frees any resources associated with this stream 59 * @throws XMLStreamException 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 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 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 * @throws XMLStreamException 204 */ 205 public String getPrefix(String uri) throws XMLStreamException; 206 207 /** 208 * Sets the prefix the uri is bound to. This prefix is bound 209 * in the scope of the current START_ELEMENT / END_ELEMENT pair. 210 * If this method is called before a START_ELEMENT has been written 211 * the prefix is bound in the root scope. 212 * @param prefix the prefix to bind to the uri 213 * @param uri the uri to bind to the prefix 214 * @throws XMLStreamException 215 */ 216 public void setPrefix(String prefix, String uri) throws XMLStreamException; 217 218 /** 219 * Binds a URI to the default namespace 220 * This URI is bound 221 * in the scope of the current START_ELEMENT / END_ELEMENT pair. 222 * If this method is called before a START_ELEMENT has been written 223 * the uri is bound in the root scope. 224 * @param uri the uri to bind to the default namespace 225 * @throws XMLStreamException 226 */ 227 public void setDefaultNamespace(String uri) throws XMLStreamException; 228 229 /** 230 * Sets the current namespace context for prefix and uri bindings. 231 * This context becomes the root namespace context for writing and 232 * will replace the current root namespace context. Subsequent calls 233 * to setPrefix and setDefaultNamespace will bind namespaces using 234 * the context passed to the method as the root context for resolving 235 * namespaces. 236 * @param context the namespace context to use for this writer 237 * @throws XMLStreamException 238 */ 239 public void setNamespaceContext(NamespaceContext context) 240 throws XMLStreamException; 241 242 /** 243 * Returns the current namespace context. 244 * @return the current namespace context 245 */ 246 public NamespaceContext getNamespaceContext(); 247 248 249 }