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 }