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