public interface

XMLStreamWriter

javax.xml.stream.XMLStreamWriter

Class Overview

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 & , < and > For attribute values the writeAttribute method will escape the above characters plus " to ensure that all character content and attribute values are well formed. Each NAMESPACE and ATTRIBUTE must be individually written.

XML Namespaces, javax.xml.stream.isRepairingNamespaces and write method behaviour
Method isRepairingNamespaces == true isRepairingNamespaces == false
namespaceURI bound namespaceURI unbound namespaceURI bound namespaceURI unbound
writeAttribute(namespaceURI, localName, value) prefix:localName="value" [1] xmlns:{generated}="namespaceURI" {generated}:localName="value" prefix:localName="value" [1] XMLStreamException
writeAttribute(prefix, namespaceURI, localName, value) bound to same prefix:
prefix:localName="value" [1]

bound to different prefix:
xmlns:{generated}="namespaceURI" {generated}:localName="value" 		xmlns:prefix="namespaceURI" prefix:localName="value" [3] bound to same prefix:
prefix:localName="value" [1][2]

bound to different prefix:
XMLStreamException[2] 		xmlns:prefix="namespaceURI" prefix:localName="value" [2][5]
writeStartElement(namespaceURI, localName)

writeEmptyElement(namespaceURI, localName)		 <prefix:localName> [1] <{generated}:localName xmlns:{generated}="namespaceURI"> <prefix:localName> [1] XMLStreamException
writeStartElement(prefix, localName, namespaceURI)

writeEmptyElement(prefix, localName, namespaceURI)		 bound to same prefix:
<prefix:localName> [1]

bound to different prefix:
<{generated}:localName xmlns:{generated}="namespaceURI"> 		<prefix:localName xmlns:prefix="namespaceURI"> [4] bound to same prefix:
<prefix:localName> [1]

bound to different prefix:
XMLStreamException 		<prefix:localName> 
Notes:
  • [1] if namespaceURI == default Namespace URI, then no prefix is written
  • [2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written
  • [3] if prefix == "" || null, then a prefix is randomly generated
  • [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
  • [5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown

See Also

Summary

Public Methods
abstract void close()
Close this writer and free any resources associated with the writer.
abstract void flush()
Write any cached data to the underlying output mechanism.
abstract NamespaceContext getNamespaceContext()
Returns the current namespace context.
abstract String getPrefix(String uri)
Gets the prefix the uri is bound to
abstract Object getProperty(String name)
Get the value of a feature/property from the underlying implementation
abstract void setDefaultNamespace(String uri)
Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.
abstract void setNamespaceContext(NamespaceContext context)
Sets the current namespace context for prefix and uri bindings.
abstract void setPrefix(String prefix, String uri)
Sets the prefix the uri is bound to.
abstract void writeAttribute(String localName, String value)
Writes an attribute to the output stream without a prefix.
abstract void writeAttribute(String namespaceURI, String localName, String value)
Writes an attribute to the output stream
abstract void writeAttribute(String prefix, String namespaceURI, String localName, String value)
Writes an attribute to the output stream
abstract void writeCData(String data)
Writes a CData section
abstract void writeCharacters(char[] text, int start, int len)
Write text to the output
abstract void writeCharacters(String text)
Write text to the output
abstract void writeComment(String data)
Writes an xml comment with the data enclosed
abstract void writeDTD(String dtd)
Write a DTD section.
abstract void writeDefaultNamespace(String namespaceURI)
Writes the default namespace to the stream
abstract void writeEmptyElement(String localName)
Writes an empty element tag to the output
abstract void writeEmptyElement(String namespaceURI, String localName)
Writes an empty element tag to the output
abstract void writeEmptyElement(String prefix, String localName, String namespaceURI)
Writes an empty element tag to the output
abstract void writeEndDocument()
Closes any start tags and writes corresponding end tags.
abstract void writeEndElement()
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.
abstract void writeEntityRef(String name)
Writes an entity reference
abstract void writeNamespace(String prefix, String namespaceURI)
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
abstract void writeProcessingInstruction(String target, String data)
Writes a processing instruction
abstract void writeProcessingInstruction(String target)
Writes a processing instruction
abstract void writeStartDocument(String encoding, String version)
Write the XML Declaration.
abstract void writeStartDocument(String version)
Write the XML Declaration.
abstract void writeStartDocument()
Write the XML Declaration.
abstract void writeStartElement(String namespaceURI, String localName)
Writes a start tag to the output
abstract void writeStartElement(String localName)
Writes a start tag to the output.
abstract void writeStartElement(String prefix, String localName, String namespaceURI)
Writes a start tag to the output

Public Methods

public abstract void close ()

Close this writer and free any resources associated with the writer. This must not close the underlying output stream.

Throws
XMLStreamException

public abstract void flush ()

Write any cached data to the underlying output mechanism.

Throws
XMLStreamException

public abstract NamespaceContext getNamespaceContext ()

Returns the current namespace context.

Returns
  • the current NamespaceContext

public abstract String getPrefix (String uri)

Gets the prefix the uri is bound to

Returns
  • the prefix or null
Throws
XMLStreamException

public abstract Object getProperty (String name)

Get the value of a feature/property from the underlying implementation

Parameters
name The name of the property, may not be null
Returns
  • The value of the property
Throws
IllegalArgumentException if the property is not supported
NullPointerException if the name is null

public abstract void setDefaultNamespace (String uri)

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.

Parameters
uri the uri to bind to the default namespace, may be null
Throws
XMLStreamException

public abstract void setNamespaceContext (NamespaceContext context)

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.

Parameters
context the namespace context to use for this writer, may not be null
Throws
XMLStreamException

public abstract void setPrefix (String prefix, String uri)

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.

Parameters
prefix the prefix to bind to the uri, may not be null
uri the uri to bind to the prefix, may be null
Throws
XMLStreamException

public abstract void writeAttribute (String localName, String value)

Writes an attribute to the output stream without a prefix.

Parameters
localName the local name of the attribute
value the value of the attribute
Throws
IllegalStateException if the current state does not allow Attribute writing
XMLStreamException

public abstract void writeAttribute (String namespaceURI, String localName, String value)

Writes an attribute to the output stream

Parameters
namespaceURI the uri of the prefix for this attribute
localName the local name of the attribute
value the value of the attribute
Throws
IllegalStateException if the current state does not allow Attribute writing
XMLStreamException if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

public abstract void writeAttribute (String prefix, String namespaceURI, String localName, String value)

Writes an attribute to the output stream

Parameters
prefix the prefix for this attribute
namespaceURI the uri of the prefix for this attribute
localName the local name of the attribute
value the value of the attribute
Throws
IllegalStateException if the current state does not allow Attribute writing
XMLStreamException if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

public abstract void writeCData (String data)

Writes a CData section

Parameters
data the data contained in the CData Section, may not be null
Throws
XMLStreamException

public abstract void writeCharacters (char[] text, int start, int len)

Write text to the output

Parameters
text the value to write
start the starting position in the array
len the number of characters to write
Throws
XMLStreamException

public abstract void writeCharacters (String text)

Write text to the output

Parameters
text the value to write
Throws
XMLStreamException

public abstract void writeComment (String data)

Writes an xml comment with the data enclosed

Parameters
data the data contained in the comment, may be null
Throws
XMLStreamException

public abstract void writeDTD (String dtd)

Write a DTD section. This string represents the entire doctypedecl production from the XML 1.0 specification.

Parameters
dtd the DTD to be written
Throws
XMLStreamException

public abstract void writeDefaultNamespace (String namespaceURI)

Writes the default namespace to the stream

Parameters
namespaceURI the uri to bind the default namespace to
Throws
IllegalStateException if the current state does not allow Namespace writing
XMLStreamException

public abstract void writeEmptyElement (String localName)

Writes an empty element tag to the output

Parameters
localName local name of the tag, may not be null
Throws
XMLStreamException

public abstract void writeEmptyElement (String namespaceURI, String localName)

Writes an empty element tag to the output

Parameters
namespaceURI the uri to bind the tag to, may not be null
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 abstract void writeEmptyElement (String prefix, String localName, String namespaceURI)

Writes an empty element tag to the output

Parameters
prefix the prefix of the tag, may not be null
localName local name of the tag, may not be null
namespaceURI the uri to bind the tag to, may not be null
Throws
XMLStreamException

public abstract void writeEndDocument ()

Closes any start tags and writes corresponding end tags.

Throws
XMLStreamException

public abstract void writeEndElement ()

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 abstract void writeEntityRef (String name)

Writes an entity reference

Parameters
name the name of the entity
Throws
XMLStreamException

public abstract void writeNamespace (String prefix, String namespaceURI)

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

Parameters
prefix the prefix to bind this namespace to
namespaceURI the uri to bind the prefix to
Throws
IllegalStateException if the current state does not allow Namespace writing
XMLStreamException

public abstract void writeProcessingInstruction (String target, String data)

Writes a processing instruction

Parameters
target the target of the processing instruction, may not be null
data the data contained in the processing instruction, may not be null
Throws
XMLStreamException

public abstract void writeProcessingInstruction (String target)

Writes a processing instruction

Parameters
target the target of the processing instruction, may not be null
Throws
XMLStreamException

public abstract void writeStartDocument (String encoding, String version)

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

Parameters
encoding encoding of the xml declaration
version version of the xml document
Throws
XMLStreamException If given encoding does not match encoding of the underlying stream

public abstract void writeStartDocument (String version)

Write the XML Declaration. Defaults the XML version to 1.0

Parameters
version version of the xml document
Throws
XMLStreamException

public abstract void writeStartDocument ()

Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8

Throws
XMLStreamException

public abstract void writeStartElement (String namespaceURI, String localName)

Writes a start tag to the output

Parameters
namespaceURI the namespaceURI of the prefix to use, may not be null
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 abstract void writeStartElement (String localName)

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.

Parameters
localName local name of the tag, may not be null
Throws
XMLStreamException

public abstract void writeStartElement (String prefix, String localName, String namespaceURI)

Writes a start tag to the output

Parameters
prefix the prefix of the tag, may not be null
localName local name of the tag, may not be null
namespaceURI the uri to bind the prefix to, may not be null
Throws
XMLStreamException