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.namespace.NamespaceContext; 32 33 /** 34 * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does 35 * not perform well formedness checking on its input. However 36 * the writeCharacters method is required to escape & , < and > 37 * For attribute values the writeAttribute method will escape the 38 * above characters plus " to ensure that all character content 39 * and attribute values are well formed. 40 * 41 * Each NAMESPACE 42 * and ATTRIBUTE must be individually written. 43 * 44 * <table border="1" cellpadding="2" cellspacing="0"> 45 * <thead> 46 * <tr> 47 * <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th> 48 * </tr> 49 * <tr> 50 * <th>Method</th> <!-- method --> 51 * <th colspan="2"><code>isRepairingNamespaces</code> == true</th> 52 * <th colspan="2"><code>isRepairingNamespaces</code> == false</th> 53 * </tr> 54 * <tr> 55 * <th></th> <!-- method --> 56 * <th>namespaceURI bound</th> 57 * <th>namespaceURI unbound</th> 58 * <th>namespaceURI bound</th> 59 * <th>namespaceURI unbound</th> 60 * </tr> 61 * </thead> 62 * 63 * <tbody> 64 * <tr> 65 * <th><code>writeAttribute(namespaceURI, localName, value)</code></th> 66 * <!-- isRepairingNamespaces == true --> 67 * <td> 68 * <!-- namespaceURI bound --> 69 * prefix:localName="value" <sup>[1]</sup> 70 * </td> 71 * <td> 72 * <!-- namespaceURI unbound --> 73 * xmlns:{generated}="namespaceURI" {generated}:localName="value" 74 * </td> 75 * <!-- isRepairingNamespaces == false --> 76 * <td> 77 * <!-- namespaceURI bound --> 78 * prefix:localName="value" <sup>[1]</sup> 79 * </td> 80 * <td> 81 * <!-- namespaceURI unbound --> 82 * <code>XMLStreamException</code> 83 * </td> 84 * </tr> 85 * 86 * <tr> 87 * <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th> 88 * <!-- isRepairingNamespaces == true --> 89 * <td> 90 * <!-- namespaceURI bound --> 91 * bound to same prefix:<br /> 92 * prefix:localName="value" <sup>[1]</sup><br /> 93 * <br /> 94 * bound to different prefix:<br /> 95 * xmlns:{generated}="namespaceURI" {generated}:localName="value" 96 * </td> 97 * <td> 98 * <!-- namespaceURI unbound --> 99 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup> 100 * </td> 101 * <!-- isRepairingNamespaces == false --> 102 * <td> 103 * <!-- namespaceURI bound --> 104 * bound to same prefix:<br /> 105 * prefix:localName="value" <sup>[1][2]</sup><br /> 106 * <br /> 107 * bound to different prefix:<br /> 108 * <code>XMLStreamException</code><sup>[2]</sup> 109 * </td> 110 * <td> 111 * <!-- namespaceURI unbound --> 112 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup> 113 * </td> 114 * </tr> 115 * 116 * <tr> 117 * <th><code>writeStartElement(namespaceURI, localName)</code><br /> 118 * <br /> 119 * <code>writeEmptyElement(namespaceURI, localName)</code></th> 120 * <!-- isRepairingNamespaces == true --> 121 * <td > 122 * <!-- namespaceURI bound --> 123 * <prefix:localName> <sup>[1]</sup> 124 * </td> 125 * <td> 126 * <!-- namespaceURI unbound --> 127 * <{generated}:localName xmlns:{generated}="namespaceURI"> 128 * </td> 129 * <!-- isRepairingNamespaces == false --> 130 * <td> 131 * <!-- namespaceURI bound --> 132 * <prefix:localName> <sup>[1]</sup> 133 * </td> 134 * <td> 135 * <!-- namespaceURI unbound --> 136 * <code>XMLStreamException</code> 137 * </td> 138 * </tr> 139 * 140 * <tr> 141 * <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br /> 142 * <br /> 143 * <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th> 144 * <!-- isRepairingNamespaces == true --> 145 * <td> 146 * <!-- namespaceURI bound --> 147 * bound to same prefix:<br /> 148 * <prefix:localName> <sup>[1]</sup><br /> 149 * <br /> 150 * bound to different prefix:<br /> 151 * <{generated}:localName xmlns:{generated}="namespaceURI"> 152 * </td> 153 * <td> 154 * <!-- namespaceURI unbound --> 155 * <prefix:localName xmlns:prefix="namespaceURI"> <sup>[4]</sup> 156 * </td> 157 * <!-- isRepairingNamespaces == false --> 158 * <td> 159 * <!-- namespaceURI bound --> 160 * bound to same prefix:<br /> 161 * <prefix:localName> <sup>[1]</sup><br /> 162 * <br /> 163 * bound to different prefix:<br /> 164 * <code>XMLStreamException</code> 165 * </td> 166 * <td> 167 * <!-- namespaceURI unbound --> 168 * <prefix:localName> 169 * </td> 170 * </tr> 171 * </tbody> 172 * <tfoot> 173 * <tr> 174 * <td colspan="5"> 175 * Notes: 176 * <ul> 177 * <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li> 178 * <li>[2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written</li> 179 * <li>[3] if prefix == "" || null, then a prefix is randomly generated</li> 180 * <li>[4] if prefix == "" || null, then it is treated as the default Namespace and no prefix is generated or written, an xmlns declaration is generated and written if the namespaceURI is unbound</li> 181 * <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</li> 182 * </ul> 183 * </td> 184 * </tr> 185 * </tfoot> 186 * </table> 187 * 188 * @version 1.0 189 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 190 * @see XMLOutputFactory 191 * @see XMLStreamReader 192 * @since 1.6 193 */ 194 public interface XMLStreamWriter { 195 196 /** 197 * Writes a start tag to the output. All writeStartElement methods 198 * open a new scope in the internal namespace context. Writing the 199 * corresponding EndElement causes the scope to be closed. 200 * @param localName local name of the tag, may not be null 201 * @throws XMLStreamException | 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.namespace.NamespaceContext; 32 33 /** 34 * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does 35 * not perform well formedness checking on its input. However 36 * the writeCharacters method is required to escape {@literal &, < and >} 37 * For attribute values the writeAttribute method will escape the 38 * above characters plus {@literal "} to ensure that all character content 39 * and attribute values are well formed. 40 * 41 * Each NAMESPACE 42 * and ATTRIBUTE must be individually written. 43 * 44 * <table border="1" cellpadding="2" cellspacing="0"> 45 * <thead> 46 * <tr> 47 * <th colspan="5">XML Namespaces, {@code javax.xml.stream.isRepairingNamespaces} and write method behaviour</th> 48 * </tr> 49 * <tr> 50 * <th>Method</th> <!-- method --> 51 * <th colspan="2">{@code isRepairingNamespaces} == true</th> 52 * <th colspan="2">{@code isRepairingNamespaces} == false</th> 53 * </tr> 54 * <tr> 55 * <th></th> <!-- method --> 56 * <th>namespaceURI bound</th> 57 * <th>namespaceURI unbound</th> 58 * <th>namespaceURI bound</th> 59 * <th>namespaceURI unbound</th> 60 * </tr> 61 * </thead> 62 * 63 * <tbody> 64 * <tr> 65 * <th>{@code writeAttribute(namespaceURI, localName, value)}</th> 66 * <!-- isRepairingNamespaces == true --> 67 * <td> 68 * <!-- namespaceURI bound --> 69 * prefix:localName="value" <sup>[1]</sup> 70 * </td> 71 * <td> 72 * <!-- namespaceURI unbound --> 73 * xmlns:{generated}="namespaceURI" {generated}:localName="value" 74 * </td> 75 * <!-- isRepairingNamespaces == false --> 76 * <td> 77 * <!-- namespaceURI bound --> 78 * prefix:localName="value" <sup>[1]</sup> 79 * </td> 80 * <td> 81 * <!-- namespaceURI unbound --> 82 * {@code XMLStreamException} 83 * </td> 84 * </tr> 85 * 86 * <tr> 87 * <th>{@code writeAttribute(prefix, namespaceURI, localName, value)}</th> 88 * <!-- isRepairingNamespaces == true --> 89 * <td> 90 * <!-- namespaceURI bound --> 91 * bound to same prefix:<br> 92 * prefix:localName="value" <sup>[1]</sup><br> 93 * <br> 94 * bound to different prefix:<br> 95 * xmlns:{generated}="namespaceURI" {generated}:localName="value" 96 * </td> 97 * <td> 98 * <!-- namespaceURI unbound --> 99 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup> 100 * </td> 101 * <!-- isRepairingNamespaces == false --> 102 * <td> 103 * <!-- namespaceURI bound --> 104 * bound to same prefix:<br> 105 * prefix:localName="value" <sup>[1][2]</sup><br> 106 * <br> 107 * bound to different prefix:<br> 108 * {@code XMLStreamException}<sup>[2]</sup> 109 * </td> 110 * <td> 111 * <!-- namespaceURI unbound --> 112 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup> 113 * </td> 114 * </tr> 115 * 116 * <tr> 117 * <th>{@code writeStartElement(namespaceURI, localName)}<br> 118 * <br> 119 * {@code writeEmptyElement(namespaceURI, localName)}</th> 120 * <!-- isRepairingNamespaces == true --> 121 * <td > 122 * <!-- namespaceURI bound --> 123 * {@code <prefix:localName>} <sup>[1]</sup> 124 * </td> 125 * <td> 126 * <!-- namespaceURI unbound --> 127 * {@code <{generated}:localName xmlns:{generated}="namespaceURI">} 128 * </td> 129 * <!-- isRepairingNamespaces == false --> 130 * <td> 131 * <!-- namespaceURI bound --> 132 * {@code prefix:localName>} <sup>[1]</sup> 133 * </td> 134 * <td> 135 * <!-- namespaceURI unbound --> 136 * {@code XMLStreamException} 137 * </td> 138 * </tr> 139 * 140 * <tr> 141 * <th>{@code writeStartElement(prefix, localName, namespaceURI)}<br> 142 * <br> 143 * {@code writeEmptyElement(prefix, localName, namespaceURI)}</th> 144 * <!-- isRepairingNamespaces == true --> 145 * <td> 146 * <!-- namespaceURI bound --> 147 * bound to same prefix:<br> 148 * {@code <prefix:localName>} <sup>[1]</sup><br> 149 * <br> 150 * bound to different prefix:<br> 151 * {@code <{generated}:localName xmlns:{generated}="namespaceURI">} 152 * </td> 153 * <td> 154 * <!-- namespaceURI unbound --> 155 * {@code <prefix:localName xmlns:prefix="namespaceURI">} <sup>[4]</sup> 156 * </td> 157 * <!-- isRepairingNamespaces == false --> 158 * <td> 159 * <!-- namespaceURI bound --> 160 * bound to same prefix:<br> 161 * {@code <prefix:localName>} <sup>[1]</sup><br> 162 * <br> 163 * bound to different prefix:<br> 164 * {@code XMLStreamException} 165 * </td> 166 * <td> 167 * <!-- namespaceURI unbound --> 168 * {@code <prefix:localName>} 169 * </td> 170 * </tr> 171 * </tbody> 172 * <tfoot> 173 * <tr> 174 * <td colspan="5"> 175 * Notes: 176 * <ul> 177 * <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li> 178 * <li>[2] if prefix == "" || null {@literal &&} namespaceURI == "", then 179 no prefix or Namespace declaration is generated or written</li> 180 * <li>[3] if prefix == "" || null, then a prefix is randomly generated</li> 181 * <li>[4] if prefix == "" || null, then it is treated as the default Namespace and 182 no prefix is generated or written, an xmlns declaration is generated 183 and written if the namespaceURI is unbound</li> 184 * <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to 185 define the default Namespace and an XMLStreamException is thrown</li> 186 * </ul> 187 * </td> 188 * </tr> 189 * </tfoot> 190 * </table> 191 * 192 * @version 1.0 193 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 194 * @see XMLOutputFactory 195 * @see XMLStreamReader 196 * @since 1.6 197 */ 198 public interface XMLStreamWriter { 199 200 /** 201 * Writes a start tag to the output. All writeStartElement methods 202 * open a new scope in the internal namespace context. Writing the 203 * corresponding EndElement causes the scope to be closed. 204 * @param localName local name of the tag, may not be null 205 * @throws XMLStreamException |