APIdia Launch Partner
Top Description Methods
javax.xml.stream

public Interface XMLStreamWriter

Known Direct Subinterfaces
com.sun.xml.internal.stream.writers.XMLStreamWriterBase
Imports
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 &, < 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:
Author
Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
Since
1.6
Version
1.0
See Also
XMLOutputFactory, XMLStreamReader

Method Summary

Modifier and TypeMethod and Description
public void
close()

Close this writer and free any resources associated with the writer.

public void
flush()

Write any cached data to the underlying output mechanism.

public NamespaceContext

Returns:

the current NamespaceContext
getNamespaceContext()

Returns the current namespace context.

public String

Returns:

the prefix or null
getPrefix(String
the uri the prefix is bound to
uri)

Gets the prefix the uri is bound to.

public Object

Returns:

The value of the property
getProperty(String
The name of the property, may not be null
name)

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

public void
setDefaultNamespace(String
the uri to bind to the default namespace, may be null
uri)

Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.

public void
setNamespaceContext(NamespaceContext
the namespace context to use for this writer, may not be null
context)

Sets the current namespace context for prefix and uri bindings.

public void
setPrefix(String
the prefix to bind to the uri, may not be null
prefix, String
the uri to bind to the prefix, may be null
uri)

Sets the prefix the uri is bound to.

public void
writeAttribute(String
the local name of the attribute
localName, String
the value of the attribute
value)

Writes an attribute to the output stream without a prefix.

public void
writeAttribute(String
the prefix for this attribute
prefix, String
the uri of the prefix for this attribute
namespaceURI, String
the local name of the attribute
localName, String
the value of the attribute
value)

Writes an attribute to the output stream

public void
writeAttribute(String
the uri of the prefix for this attribute
namespaceURI, String
the local name of the attribute
localName, String
the value of the attribute
value)

Writes an attribute to the output stream

public void
writeCData(String
the data contained in the CData Section, may not be null
data)

Writes a CData section

public void
writeCharacters(String
the value to write
text)

Write text to the output

public void
writeCharacters(char[]
the value to write
text, int
the starting position in the array
start, int
the number of characters to write
len)

Write text to the output

public void
writeComment(String
the data contained in the comment, may be null
data)

Writes an xml comment with the data enclosed

public void
writeDefaultNamespace(String
the uri to bind the default namespace to
namespaceURI)

Writes the default namespace to the stream

public void
writeDTD(String
the DTD to be written
dtd)

Write a DTD section.

public void
writeEmptyElement(String
the uri to bind the tag to, may not be null
namespaceURI, String
local name of the tag, may not be null
localName)

Writes an empty element tag to the output

public void
writeEmptyElement(String
the prefix of the tag, may not be null
prefix, String
local name of the tag, may not be null
localName, String
the uri to bind the tag to, may not be null
namespaceURI)

Writes an empty element tag to the output

public void
writeEmptyElement(String
local name of the tag, may not be null
localName)

Writes an empty element tag to the output

public void
writeEndDocument()

Closes any start tags and writes corresponding end tags.

public 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.

public void
writeEntityRef(String
the name of the entity
name)

Writes an entity reference

public void
writeNamespace(String
the prefix to bind this namespace to
prefix, String
the uri to bind the prefix to
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

public void
writeProcessingInstruction(String
the target of the processing instruction, may not be null
target)

Writes a processing instruction

public void
writeProcessingInstruction(String
the target of the processing instruction, may not be null
target, String
the data contained in the processing instruction, may not be null
data)

Writes a processing instruction

public void
writeStartDocument()

Write the XML Declaration.

public void
writeStartDocument(String
version of the xml document
version)

Write the XML Declaration.

public void
writeStartDocument(String
encoding of the xml declaration
encoding, String
version of the xml document
version)

Write the XML Declaration.

public void
writeStartElement(String
local name of the tag, may not be null
localName)

Writes a start tag to the output.

public void
writeStartElement(String
the namespaceURI of the prefix to use, may not be null
namespaceURI, String
local name of the tag, may not be null
localName)

Writes a start tag to the output

public void
writeStartElement(String
the prefix of the tag, may not be null
prefix, String
local name of the tag, may not be null
localName, String
the uri to bind the prefix to, may not be null
namespaceURI)

Writes a start tag to the output

Method Detail

closeback to summary
public void close() throws XMLStreamException

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

Exceptions
XMLStreamException:
if an error occurs
flushback to summary
public void flush() throws XMLStreamException

Write any cached data to the underlying output mechanism.

Exceptions
XMLStreamException:
if an error occurs
getNamespaceContextback to summary
public NamespaceContext getNamespaceContext()

Returns the current namespace context.

Returns:NamespaceContext

the current NamespaceContext

getPrefixback to summary
public String getPrefix(String uri) throws XMLStreamException

Gets the prefix the uri is bound to.

Parameters
uri:String

the uri the prefix is bound to

Returns:String

the prefix or null

Exceptions
XMLStreamException:
if an error occurs
getPropertyback to summary
public Object getProperty(String name) throws IllegalArgumentException

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

Parameters
name:String

The name of the property, may not be null

Returns:Object

The value of the property

Exceptions
IllegalArgumentException:
if the property is not supported
NullPointerException:
if the name is null
setDefaultNamespaceback to summary
public void setDefaultNamespace(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.

Parameters
uri:String

the uri to bind to the default namespace, may be null

Exceptions
XMLStreamException:
if an error occurs
setNamespaceContextback to summary
public void setNamespaceContext(NamespaceContext context) 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.

Parameters
context:NamespaceContext

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

Exceptions
XMLStreamException:
if an error occurs
setPrefixback to summary
public void setPrefix(String prefix, 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.

Parameters
prefix:String

the prefix to bind to the uri, may not be null

uri:String

the uri to bind to the prefix, may be null

Exceptions
XMLStreamException:
if an error occurs
writeAttributeback to summary
public void writeAttribute(String localName, String value) throws XMLStreamException

Writes an attribute to the output stream without a prefix.

Parameters
localName:String

the local name of the attribute

value:String

the value of the attribute

Exceptions
XMLStreamException:
if an error occurs
IllegalStateException:
if the current state does not allow Attribute writing
writeAttributeback to summary
public void writeAttribute(String prefix, String namespaceURI, String localName, String value) throws XMLStreamException

Writes an attribute to the output stream

Parameters
prefix:String

the prefix for this attribute

namespaceURI:String

the uri of the prefix for this attribute

localName:String

the local name of the attribute

value:String

the value of the attribute

Exceptions
XMLStreamException:
if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true
IllegalStateException:
if the current state does not allow Attribute writing
writeAttributeback to summary
public void writeAttribute(String namespaceURI, String localName, String value) throws XMLStreamException

Writes an attribute to the output stream

Parameters
namespaceURI:String

the uri of the prefix for this attribute

localName:String

the local name of the attribute

value:String

the value of the attribute

Exceptions
XMLStreamException:
if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true
IllegalStateException:
if the current state does not allow Attribute writing
writeCDataback to summary
public void writeCData(String data) throws XMLStreamException

Writes a CData section

Parameters
data:String

the data contained in the CData Section, may not be null

Exceptions
XMLStreamException:
if an error occurs
writeCharactersback to summary
public void writeCharacters(String text) throws XMLStreamException

Write text to the output

Parameters
text:String

the value to write

Exceptions
XMLStreamException:
if an error occurs
writeCharactersback to summary
public void writeCharacters(char[] text, int start, int len) throws XMLStreamException

Write text to the output

Parameters
text:char[]

the value to write

start:int

the starting position in the array

len:int

the number of characters to write

Exceptions
XMLStreamException:
if an error occurs
writeCommentback to summary
public void writeComment(String data) throws XMLStreamException

Writes an xml comment with the data enclosed

Parameters
data:String

the data contained in the comment, may be null

Exceptions
XMLStreamException:
if an error occurs
writeDefaultNamespaceback to summary
public void writeDefaultNamespace(String namespaceURI) throws XMLStreamException

Writes the default namespace to the stream

Parameters
namespaceURI:String

the uri to bind the default namespace to

Exceptions
XMLStreamException:
if an error occurs
IllegalStateException:
if the current state does not allow Namespace writing
writeDTDback to summary
public void writeDTD(String dtd) throws XMLStreamException

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

Parameters
dtd:String

the DTD to be written

Exceptions
XMLStreamException:
if an error occurs
writeEmptyElementback to summary
public void writeEmptyElement(String namespaceURI, String localName) throws XMLStreamException

Writes an empty element tag to the output

Parameters
namespaceURI:String

the uri to bind the tag to, may not be null

localName:String

local name of the tag, may not be null

Exceptions
XMLStreamException:
if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true
writeEmptyElementback to summary
public void writeEmptyElement(String prefix, String localName, String namespaceURI) throws XMLStreamException

Writes an empty element tag to the output

Parameters
prefix:String

the prefix of the tag, may not be null

localName:String

local name of the tag, may not be null

namespaceURI:String

the uri to bind the tag to, may not be null

Exceptions
XMLStreamException:
if an error occurs
writeEmptyElementback to summary
public void writeEmptyElement(String localName) throws XMLStreamException

Writes an empty element tag to the output

Parameters
localName:String

local name of the tag, may not be null

Exceptions
XMLStreamException:
if an error occurs
writeEndDocumentback to summary
public void writeEndDocument() throws XMLStreamException

Closes any start tags and writes corresponding end tags.

Exceptions
XMLStreamException:
if an error occurs
writeEndElementback to summary
public void writeEndElement() 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.

Exceptions
XMLStreamException:
if an error occurs
writeEntityRefback to summary
public void writeEntityRef(String name) throws XMLStreamException

Writes an entity reference

Parameters
name:String

the name of the entity

Exceptions
XMLStreamException:
if an error occurs
writeNamespaceback to summary
public void writeNamespace(String prefix, String namespaceURI) 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

Parameters
prefix:String

the prefix to bind this namespace to

namespaceURI:String

the uri to bind the prefix to

Exceptions
XMLStreamException:
if an error occurs
IllegalStateException:
if the current state does not allow Namespace writing
writeProcessingInstructionback to summary
public void writeProcessingInstruction(String target) throws XMLStreamException

Writes a processing instruction

Parameters
target:String

the target of the processing instruction, may not be null

Exceptions
XMLStreamException:
if an error occurs
writeProcessingInstructionback to summary
public void writeProcessingInstruction(String target, String data) throws XMLStreamException

Writes a processing instruction

Parameters
target:String

the target of the processing instruction, may not be null

data:String

the data contained in the processing instruction, may not be null

Exceptions
XMLStreamException:
if an error occurs
writeStartDocumentback to summary
public void writeStartDocument() throws XMLStreamException

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

Exceptions
XMLStreamException:
if an error occurs
writeStartDocumentback to summary
public void writeStartDocument(String version) throws XMLStreamException

Write the XML Declaration. Defaults the XML version to 1.0

Parameters
version:String

version of the xml document

Exceptions
XMLStreamException:
if an error occurs
writeStartDocumentback to summary
public void writeStartDocument(String encoding, 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

Parameters
encoding:String

encoding of the xml declaration

version:String

version of the xml document

Exceptions
XMLStreamException:
If given encoding does not match encoding of the underlying stream
writeStartElementback to summary
public void writeStartElement(String localName) throws XMLStreamException

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:String

local name of the tag, may not be null

Exceptions
XMLStreamException:
if an error occurs
writeStartElementback to summary
public void writeStartElement(String namespaceURI, String localName) throws XMLStreamException

Writes a start tag to the output

Parameters
namespaceURI:String

the namespaceURI of the prefix to use, may not be null

localName:String

local name of the tag, may not be null

Exceptions
XMLStreamException:
if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true
writeStartElementback to summary
public void writeStartElement(String prefix, String localName, String namespaceURI) throws XMLStreamException

Writes a start tag to the output

Parameters
prefix:String

the prefix of the tag, may not be null

localName:String

local name of the tag, may not be null

namespaceURI:String

the uri to bind the prefix to, may not be null

Exceptions
XMLStreamException:
if an error occurs