31 import javax.xml.namespace.NamespaceContext; |
31 import javax.xml.namespace.NamespaceContext; |
32 |
32 |
33 /** |
33 /** |
34 * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does |
34 * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does |
35 * not perform well formedness checking on its input. However |
35 * not perform well formedness checking on its input. However |
36 * the writeCharacters method is required to escape & , < and > |
36 * the writeCharacters method is required to escape {@literal &, < and >} |
37 * For attribute values the writeAttribute method will escape the |
37 * For attribute values the writeAttribute method will escape the |
38 * above characters plus " to ensure that all character content |
38 * above characters plus {@literal "} to ensure that all character content |
39 * and attribute values are well formed. |
39 * and attribute values are well formed. |
40 * |
40 * |
41 * Each NAMESPACE |
41 * Each NAMESPACE |
42 * and ATTRIBUTE must be individually written. |
42 * and ATTRIBUTE must be individually written. |
43 * |
43 * |
44 * <table border="1" cellpadding="2" cellspacing="0"> |
44 * <table border="1" cellpadding="2" cellspacing="0"> |
45 * <thead> |
45 * <thead> |
46 * <tr> |
46 * <tr> |
47 * <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th> |
47 * <th colspan="5">XML Namespaces, {@code javax.xml.stream.isRepairingNamespaces} and write method behaviour</th> |
48 * </tr> |
48 * </tr> |
49 * <tr> |
49 * <tr> |
50 * <th>Method</th> <!-- method --> |
50 * <th>Method</th> <!-- method --> |
51 * <th colspan="2"><code>isRepairingNamespaces</code> == true</th> |
51 * <th colspan="2">{@code isRepairingNamespaces} == true</th> |
52 * <th colspan="2"><code>isRepairingNamespaces</code> == false</th> |
52 * <th colspan="2">{@code isRepairingNamespaces} == false</th> |
53 * </tr> |
53 * </tr> |
54 * <tr> |
54 * <tr> |
55 * <th></th> <!-- method --> |
55 * <th></th> <!-- method --> |
56 * <th>namespaceURI bound</th> |
56 * <th>namespaceURI bound</th> |
57 * <th>namespaceURI unbound</th> |
57 * <th>namespaceURI unbound</th> |
77 * <!-- namespaceURI bound --> |
77 * <!-- namespaceURI bound --> |
78 * prefix:localName="value" <sup>[1]</sup> |
78 * prefix:localName="value" <sup>[1]</sup> |
79 * </td> |
79 * </td> |
80 * <td> |
80 * <td> |
81 * <!-- namespaceURI unbound --> |
81 * <!-- namespaceURI unbound --> |
82 * <code>XMLStreamException</code> |
82 * {@code XMLStreamException} |
83 * </td> |
83 * </td> |
84 * </tr> |
84 * </tr> |
85 * |
85 * |
86 * <tr> |
86 * <tr> |
87 * <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th> |
87 * <th>{@code writeAttribute(prefix, namespaceURI, localName, value)}</th> |
88 * <!-- isRepairingNamespaces == true --> |
88 * <!-- isRepairingNamespaces == true --> |
89 * <td> |
89 * <td> |
90 * <!-- namespaceURI bound --> |
90 * <!-- namespaceURI bound --> |
91 * bound to same prefix:<br /> |
91 * bound to same prefix:<br> |
92 * prefix:localName="value" <sup>[1]</sup><br /> |
92 * prefix:localName="value" <sup>[1]</sup><br> |
93 * <br /> |
93 * <br> |
94 * bound to different prefix:<br /> |
94 * bound to different prefix:<br> |
95 * xmlns:{generated}="namespaceURI" {generated}:localName="value" |
95 * xmlns:{generated}="namespaceURI" {generated}:localName="value" |
96 * </td> |
96 * </td> |
97 * <td> |
97 * <td> |
98 * <!-- namespaceURI unbound --> |
98 * <!-- namespaceURI unbound --> |
99 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup> |
99 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup> |
100 * </td> |
100 * </td> |
101 * <!-- isRepairingNamespaces == false --> |
101 * <!-- isRepairingNamespaces == false --> |
102 * <td> |
102 * <td> |
103 * <!-- namespaceURI bound --> |
103 * <!-- namespaceURI bound --> |
104 * bound to same prefix:<br /> |
104 * bound to same prefix:<br> |
105 * prefix:localName="value" <sup>[1][2]</sup><br /> |
105 * prefix:localName="value" <sup>[1][2]</sup><br> |
106 * <br /> |
106 * <br> |
107 * bound to different prefix:<br /> |
107 * bound to different prefix:<br> |
108 * <code>XMLStreamException</code><sup>[2]</sup> |
108 * {@code XMLStreamException}<sup>[2]</sup> |
109 * </td> |
109 * </td> |
110 * <td> |
110 * <td> |
111 * <!-- namespaceURI unbound --> |
111 * <!-- namespaceURI unbound --> |
112 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup> |
112 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup> |
113 * </td> |
113 * </td> |
114 * </tr> |
114 * </tr> |
115 * |
115 * |
116 * <tr> |
116 * <tr> |
117 * <th><code>writeStartElement(namespaceURI, localName)</code><br /> |
117 * <th>{@code writeStartElement(namespaceURI, localName)}<br> |
118 * <br /> |
118 * <br> |
119 * <code>writeEmptyElement(namespaceURI, localName)</code></th> |
119 * {@code writeEmptyElement(namespaceURI, localName)}</th> |
120 * <!-- isRepairingNamespaces == true --> |
120 * <!-- isRepairingNamespaces == true --> |
121 * <td > |
121 * <td > |
122 * <!-- namespaceURI bound --> |
122 * <!-- namespaceURI bound --> |
123 * <prefix:localName> <sup>[1]</sup> |
123 * {@code <prefix:localName>} <sup>[1]</sup> |
124 * </td> |
124 * </td> |
125 * <td> |
125 * <td> |
126 * <!-- namespaceURI unbound --> |
126 * <!-- namespaceURI unbound --> |
127 * <{generated}:localName xmlns:{generated}="namespaceURI"> |
127 * {@code <{generated}:localName xmlns:{generated}="namespaceURI">} |
128 * </td> |
128 * </td> |
129 * <!-- isRepairingNamespaces == false --> |
129 * <!-- isRepairingNamespaces == false --> |
130 * <td> |
130 * <td> |
131 * <!-- namespaceURI bound --> |
131 * <!-- namespaceURI bound --> |
132 * <prefix:localName> <sup>[1]</sup> |
132 * {@code prefix:localName>} <sup>[1]</sup> |
133 * </td> |
133 * </td> |
134 * <td> |
134 * <td> |
135 * <!-- namespaceURI unbound --> |
135 * <!-- namespaceURI unbound --> |
136 * <code>XMLStreamException</code> |
136 * {@code XMLStreamException} |
137 * </td> |
137 * </td> |
138 * </tr> |
138 * </tr> |
139 * |
139 * |
140 * <tr> |
140 * <tr> |
141 * <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br /> |
141 * <th>{@code writeStartElement(prefix, localName, namespaceURI)}<br> |
142 * <br /> |
142 * <br> |
143 * <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th> |
143 * {@code writeEmptyElement(prefix, localName, namespaceURI)}</th> |
144 * <!-- isRepairingNamespaces == true --> |
144 * <!-- isRepairingNamespaces == true --> |
145 * <td> |
145 * <td> |
146 * <!-- namespaceURI bound --> |
146 * <!-- namespaceURI bound --> |
147 * bound to same prefix:<br /> |
147 * bound to same prefix:<br> |
148 * <prefix:localName> <sup>[1]</sup><br /> |
148 * {@code <prefix:localName>} <sup>[1]</sup><br> |
149 * <br /> |
149 * <br> |
150 * bound to different prefix:<br /> |
150 * bound to different prefix:<br> |
151 * <{generated}:localName xmlns:{generated}="namespaceURI"> |
151 * {@code <{generated}:localName xmlns:{generated}="namespaceURI">} |
152 * </td> |
152 * </td> |
153 * <td> |
153 * <td> |
154 * <!-- namespaceURI unbound --> |
154 * <!-- namespaceURI unbound --> |
155 * <prefix:localName xmlns:prefix="namespaceURI"> <sup>[4]</sup> |
155 * {@code <prefix:localName xmlns:prefix="namespaceURI">} <sup>[4]</sup> |
156 * </td> |
156 * </td> |
157 * <!-- isRepairingNamespaces == false --> |
157 * <!-- isRepairingNamespaces == false --> |
158 * <td> |
158 * <td> |
159 * <!-- namespaceURI bound --> |
159 * <!-- namespaceURI bound --> |
160 * bound to same prefix:<br /> |
160 * bound to same prefix:<br> |
161 * <prefix:localName> <sup>[1]</sup><br /> |
161 * {@code <prefix:localName>} <sup>[1]</sup><br> |
162 * <br /> |
162 * <br> |
163 * bound to different prefix:<br /> |
163 * bound to different prefix:<br> |
164 * <code>XMLStreamException</code> |
164 * {@code XMLStreamException} |
165 * </td> |
165 * </td> |
166 * <td> |
166 * <td> |
167 * <!-- namespaceURI unbound --> |
167 * <!-- namespaceURI unbound --> |
168 * <prefix:localName> |
168 * {@code <prefix:localName>} |
169 * </td> |
169 * </td> |
170 * </tr> |
170 * </tr> |
171 * </tbody> |
171 * </tbody> |
172 * <tfoot> |
172 * <tfoot> |
173 * <tr> |
173 * <tr> |
174 * <td colspan="5"> |
174 * <td colspan="5"> |
175 * Notes: |
175 * Notes: |
176 * <ul> |
176 * <ul> |
177 * <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li> |
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> |
178 * <li>[2] if prefix == "" || null {@literal &&} namespaceURI == "", then |
|
179 * 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>[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>[4] if prefix == "" || null, then it is treated as the default Namespace and |
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 * 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> |
182 * </ul> |
186 * </ul> |
183 * </td> |
187 * </td> |
184 * </tr> |
188 * </tr> |
185 * </tfoot> |
189 * </tfoot> |
186 * </table> |
190 * </table> |