286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 286N/A * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does 286N/A * not perform well formedness checking on its input. However 286N/A * the writeCharacters method is required to escape & , < and > 286N/A * For attribute values the writeAttribute method will escape the 286N/A * above characters plus " to ensure that all character content 286N/A * and attribute values are well formed. 286N/A * and ATTRIBUTE must be individually written. 286N/A * <table border="1" cellpadding="2" cellspacing="0"> 286N/A * <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th> 286N/A * <th>Method</th> <!-- method --> 286N/A * <th colspan="2"><code>isRepairingNamespaces</code> == true</th> 286N/A * <th colspan="2"><code>isRepairingNamespaces</code> == false</th> 286N/A * <th></th> <!-- method --> 286N/A * <th>namespaceURI bound</th> 286N/A * <th>namespaceURI unbound</th> 286N/A * <th>namespaceURI bound</th> 286N/A * <th>namespaceURI unbound</th> 286N/A * <th><code>writeAttribute(namespaceURI, localName, value)</code></th> 286N/A * <!-- isRepairingNamespaces == true --> 286N/A * <!-- namespaceURI bound --> 286N/A * prefix:localName="value" <sup>[1]</sup> 286N/A * <!-- namespaceURI unbound --> 286N/A * xmlns:{generated}="namespaceURI" {generated}:localName="value" 286N/A * <!-- isRepairingNamespaces == false --> 286N/A * <!-- namespaceURI bound --> 286N/A * prefix:localName="value" <sup>[1]</sup> 286N/A * <!-- namespaceURI unbound --> 286N/A * <code>XMLStreamException</code> 286N/A * <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th> 286N/A * <!-- isRepairingNamespaces == true --> 286N/A * <!-- namespaceURI bound --> 286N/A * bound to same prefix:<br /> 286N/A * prefix:localName="value" <sup>[1]</sup><br /> 286N/A * bound to different prefix:<br /> 286N/A * xmlns:{generated}="namespaceURI" {generated}:localName="value" 286N/A * <!-- namespaceURI unbound --> 286N/A * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup> 286N/A * <!-- isRepairingNamespaces == false --> 286N/A * <!-- namespaceURI bound --> 286N/A * bound to same prefix:<br /> 286N/A * prefix:localName="value" <sup>[1][2]</sup><br /> 286N/A * bound to different prefix:<br /> 286N/A * <code>XMLStreamException</code><sup>[2]</sup> 286N/A * <!-- namespaceURI unbound --> 286N/A * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup> 286N/A * <th><code>writeStartElement(namespaceURI, localName)</code><br /> 286N/A * <code>writeEmptyElement(namespaceURI, localName)</code></th> 286N/A * <!-- isRepairingNamespaces == true --> 286N/A * <!-- namespaceURI bound --> 286N/A * <prefix:localName> <sup>[1]</sup> 286N/A * <!-- namespaceURI unbound --> 286N/A * <{generated}:localName xmlns:{generated}="namespaceURI"> 286N/A * <!-- isRepairingNamespaces == false --> 286N/A * <!-- namespaceURI bound --> 286N/A * <prefix:localName> <sup>[1]</sup> 286N/A * <!-- namespaceURI unbound --> 286N/A * <code>XMLStreamException</code> 286N/A * <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br /> 286N/A * <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th> 286N/A * <!-- isRepairingNamespaces == true --> 286N/A * <!-- namespaceURI bound --> 286N/A * bound to same prefix:<br /> 286N/A * <prefix:localName> <sup>[1]</sup><br /> 286N/A * bound to different prefix:<br /> 286N/A * <{generated}:localName xmlns:{generated}="namespaceURI"> 286N/A * <!-- namespaceURI unbound --> 286N/A * <prefix:localName xmlns:prefix="namespaceURI"> <sup>[4]</sup> 286N/A * <!-- isRepairingNamespaces == false --> 286N/A * <!-- namespaceURI bound --> 286N/A * bound to same prefix:<br /> 286N/A * <prefix:localName> <sup>[1]</sup><br /> 286N/A * bound to different prefix:<br /> 286N/A * <code>XMLStreamException</code> 286N/A * <!-- namespaceURI unbound --> 286N/A * <prefix:localName> 286N/A * <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li> 286N/A * <li>[2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written</li> 286N/A * <li>[3] if prefix == "" || null, then a prefix is randomly generated</li> 286N/A * <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> 286N/A * <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</li> 286N/A * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 286N/A * @see XMLOutputFactory 286N/A * Writes a start tag to the output. All writeStartElement methods 286N/A * open a new scope in the internal namespace context. Writing the 286N/A * corresponding EndElement causes the scope to be closed. 286N/A * @param localName local name of the tag, may not be null 286N/A * @throws XMLStreamException 286N/A * Writes a start tag to the output 286N/A * @param namespaceURI the namespaceURI of the prefix to use, may not be null 286N/A * @param localName local name of the tag, may not be null 286N/A * @throws XMLStreamException if the namespace URI has not been bound to a prefix and 286N/A * Writes a start tag to the output 286N/A * @param localName local name of the tag, may not be null 286N/A * @param prefix the prefix of the tag, may not be null 286N/A * @param namespaceURI the uri to bind the prefix to, may not be null 286N/A * @throws XMLStreamException 286N/A * Writes an empty element tag to the output 286N/A * @param namespaceURI the uri to bind the tag to, may not be null 286N/A * @param localName local name of the tag, may not be null 286N/A * @throws XMLStreamException if the namespace URI has not been bound to a prefix and 286N/A * Writes an empty element tag to the output 286N/A * @param prefix the prefix of the tag, may not be null 286N/A * @param localName local name of the tag, may not be null 286N/A * @param namespaceURI the uri to bind the tag to, may not be null 286N/A * @throws XMLStreamException 286N/A * Writes an empty element tag to the output 286N/A * @param localName local name of the tag, may not be null 286N/A * @throws XMLStreamException 286N/A * Writes string data to the output without checking for well formedness. 286N/A * The data is opaque to the XMLStreamWriter, i.e. the characters are written 286N/A * blindly to the underlying output. If the method cannot be supported 286N/A * in the currrent writing context the implementation may throw a 286N/A * UnsupportedOperationException. For example note that any 286N/A * namespace declarations, end tags, etc. will be ignored and could 286N/A * interfere with proper maintanence of the writers internal state. 286N/A * @param data the data to write 286N/A // public void writeRaw(String data) throws XMLStreamException; 286N/A * Writes an end tag to the output relying on the internal 286N/A * state of the writer to determine the prefix and local name 286N/A * @throws XMLStreamException 286N/A * Closes any start tags and writes corresponding end tags. 286N/A * @throws XMLStreamException 286N/A * Close this writer and free any resources associated with the 286N/A * writer. This must not close the underlying output stream. 286N/A * @throws XMLStreamException 286N/A * Write any cached data to the underlying output mechanism. 286N/A * @throws XMLStreamException 286N/A * Writes an attribute to the output stream without 286N/A * @param localName the local name of the attribute 286N/A * @param value the value of the attribute 286N/A * @throws IllegalStateException if the current state does not allow Attribute writing 286N/A * @throws XMLStreamException 286N/A * Writes an attribute to the output stream 286N/A * @param prefix the prefix for this attribute 286N/A * @param namespaceURI the uri of the prefix for this attribute 286N/A * @param localName the local name of the attribute 286N/A * @param value the value of the attribute 286N/A * @throws IllegalStateException if the current state does not allow Attribute writing 286N/A * @throws XMLStreamException if the namespace URI has not been bound to a prefix and 286N/A * Writes an attribute to the output stream 286N/A * @param namespaceURI the uri of the prefix for this attribute 286N/A * @param localName the local name of the attribute 286N/A * @param value the value of the attribute 286N/A * @throws IllegalStateException if the current state does not allow Attribute writing 286N/A * @throws XMLStreamException if the namespace URI has not been bound to a prefix and 286N/A * Writes a namespace to the output stream 286N/A * If the prefix argument to this method is the empty string, 286N/A * "xmlns", or null this method will delegate to writeDefaultNamespace 286N/A * @param prefix the prefix to bind this namespace to 286N/A * @param namespaceURI the uri to bind the prefix to 286N/A * @throws IllegalStateException if the current state does not allow Namespace writing 286N/A * @throws XMLStreamException 286N/A * Writes the default namespace to the stream 286N/A * @param namespaceURI the uri to bind the default namespace to 286N/A * @throws IllegalStateException if the current state does not allow Namespace writing 286N/A * @throws XMLStreamException 286N/A * Writes an xml comment with the data enclosed 286N/A * @param data the data contained in the comment, may be null 286N/A * @throws XMLStreamException 286N/A * Writes a processing instruction 286N/A * @param target the target of the processing instruction, may not be null 286N/A * @throws XMLStreamException 286N/A * Writes a processing instruction 286N/A * @param target the target of the processing instruction, may not be null 286N/A * @param data the data contained in the processing instruction, may not be null 286N/A * @throws XMLStreamException 286N/A * Writes a CData section 286N/A * @param data the data contained in the CData Section, may not be null 286N/A * @throws XMLStreamException 286N/A * Write a DTD section. This string represents the entire doctypedecl production 286N/A * from the XML 1.0 specification. 286N/A * @param dtd the DTD to be written 286N/A * @throws XMLStreamException 286N/A * Writes an entity reference 286N/A * @param name the name of the entity 286N/A * @throws XMLStreamException 286N/A * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8 286N/A * @throws XMLStreamException 286N/A * Write the XML Declaration. Defaults the XML version to 1.0 286N/A * @param version version of the xml document 286N/A * @throws XMLStreamException 286N/A * Write the XML Declaration. Note that the encoding parameter does 286N/A * not set the actual encoding of the underlying output. That must 286N/A * be set when the instance of the XMLStreamWriter is created using the 286N/A * @param encoding encoding of the xml declaration 286N/A * @param version version of the xml document 286N/A * @throws XMLStreamException If given encoding does not match encoding 286N/A * of the underlying stream 286N/A * Write text to the output 286N/A * @param text the value to write 286N/A * @throws XMLStreamException 286N/A * Write text to the output 286N/A * @param text the value to write 286N/A * @param start the starting position in the array 286N/A * @param len the number of characters to write 286N/A * @throws XMLStreamException 286N/A * Gets the prefix the uri is bound to 286N/A * @return the prefix or null 286N/A * @throws XMLStreamException 286N/A * Sets the prefix the uri is bound to. This prefix is bound 286N/A * in the scope of the current START_ELEMENT / END_ELEMENT pair. 286N/A * If this method is called before a START_ELEMENT has been written 286N/A * the prefix is bound in the root scope. 286N/A * @param prefix the prefix to bind to the uri, may not be null 286N/A * @param uri the uri to bind to the prefix, may be null 286N/A * @throws XMLStreamException 286N/A * Binds a URI to the default namespace 286N/A * in the scope of the current START_ELEMENT / END_ELEMENT pair. 286N/A * If this method is called before a START_ELEMENT has been written 286N/A * the uri is bound in the root scope. 286N/A * @param uri the uri to bind to the default namespace, may be null 286N/A * @throws XMLStreamException 286N/A * Sets the current namespace context for prefix and uri bindings. 286N/A * This context becomes the root namespace context for writing and 286N/A * will replace the current root namespace context. Subsequent calls 286N/A * to setPrefix and setDefaultNamespace will bind namespaces using 286N/A * the context passed to the method as the root context for resolving 286N/A * namespaces. This method may only be called once at the start of 286N/A * the document. It does not cause the namespaces to be declared. 286N/A * If a namespace URI to prefix mapping is found in the namespace 286N/A * context it is treated as declared and the prefix may be used 286N/A * @param context the namespace context to use for this writer, may not be null 286N/A * @throws XMLStreamException 286N/A * Returns the current namespace context. 286N/A * @return the current NamespaceContext 286N/A * @param name The name of the property, may not be null 286N/A * @return The value of the property 286N/A * @throws IllegalArgumentException if the property is not supported 286N/A * @throws NullPointerException if the name is null