Back to index...

	/*
	* 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;

	}

Back to index...