public interface XMLStreamWriter
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.
Notes:
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>
|
- [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
- Since:
- 1.6
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Close this writer and free any resources associated with the writer.void
flush()
Write any cached data to the underlying output mechanism.Returns the current namespace context.Gets the prefix the uri is bound to.getProperty
(String name) Get the value of a feature/property from the underlying implementationvoid
Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.void
setNamespaceContext
(NamespaceContext context) Sets the current namespace context for prefix and uri bindings.void
Sets the prefix the uri is bound to.void
writeAttribute
(String localName, String value) Writes an attribute to the output stream without a prefix.void
writeAttribute
(String namespaceURI, String localName, String value) Writes an attribute to the output streamvoid
writeAttribute
(String prefix, String namespaceURI, String localName, String value) Writes an attribute to the output streamvoid
writeCData
(String data) Writes a CData sectionvoid
writeCharacters
(char[] text, int start, int len) Write text to the outputvoid
writeCharacters
(String text) Write text to the outputvoid
writeComment
(String data) Writes an xml comment with the data enclosedvoid
writeDefaultNamespace
(String namespaceURI) Writes the default namespace to the streamvoid
Write a DTD section.void
writeEmptyElement
(String localName) Writes an empty element tag to the outputvoid
writeEmptyElement
(String namespaceURI, String localName) Writes an empty element tag to the outputvoid
writeEmptyElement
(String prefix, String localName, String namespaceURI) Writes an empty element tag to the outputvoid
Closes any start tags and writes corresponding end tags.void
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.void
writeEntityRef
(String name) Writes an entity referencevoid
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 writeDefaultNamespacevoid
writeProcessingInstruction
(String target) Writes a processing instructionvoid
writeProcessingInstruction
(String target, String data) Writes a processing instructionvoid
Write the XML Declaration.void
writeStartDocument
(String version) Write the XML Declaration.void
writeStartDocument
(String encoding, String version) Write the XML Declaration.void
writeStartElement
(String localName) Writes a start tag to the output.void
writeStartElement
(String namespaceURI, String localName) Writes a start tag to the outputvoid
writeStartElement
(String prefix, String localName, String namespaceURI) Writes a start tag to the output
-
Method Details
-
writeStartElement
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
- if an error occurs
-
writeStartElement
Writes a start tag to the output- Parameters:
namespaceURI
- the namespaceURI of the prefix to use, may not be nulllocalName
- 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
-
writeStartElement
void writeStartElement(String prefix, String localName, String namespaceURI) throws XMLStreamException Writes a start tag to the output- Parameters:
prefix
- the prefix of the tag, may not be nulllocalName
- local name of the tag, may not be nullnamespaceURI
- the uri to bind the prefix to, may not be null- Throws:
XMLStreamException
- if an error occurs
-
writeEmptyElement
Writes an empty element tag to the output- Parameters:
namespaceURI
- the uri to bind the tag to, may not be nulllocalName
- 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
-
writeEmptyElement
void writeEmptyElement(String prefix, String localName, String namespaceURI) throws XMLStreamException Writes an empty element tag to the output- Parameters:
prefix
- the prefix of the tag, may not be nulllocalName
- local name of the tag, may not be nullnamespaceURI
- the uri to bind the tag to, may not be null- Throws:
XMLStreamException
- if an error occurs
-
writeEmptyElement
Writes an empty element tag to the output- Parameters:
localName
- local name of the tag, may not be null- Throws:
XMLStreamException
- if an error occurs
-
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
- if an error occurs
-
writeEndDocument
Closes any start tags and writes corresponding end tags.- Throws:
XMLStreamException
- if an error occurs
-
close
Close this writer and free any resources associated with the writer. This must not close the underlying output stream.- Throws:
XMLStreamException
- if an error occurs
-
flush
Write any cached data to the underlying output mechanism.- Throws:
XMLStreamException
- if an error occurs
-
writeAttribute
Writes an attribute to the output stream without a prefix.- Parameters:
localName
- the local name of the attributevalue
- the value of the attribute- Throws:
IllegalStateException
- if the current state does not allow Attribute writingXMLStreamException
- if an error occurs
-
writeAttribute
void writeAttribute(String prefix, String namespaceURI, String localName, String value) throws XMLStreamException Writes an attribute to the output stream- Parameters:
prefix
- the prefix for this attributenamespaceURI
- the uri of the prefix for this attributelocalName
- the local name of the attributevalue
- the value of the attribute- Throws:
IllegalStateException
- if the current state does not allow Attribute writingXMLStreamException
- if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true
-
writeAttribute
Writes an attribute to the output stream- Parameters:
namespaceURI
- the uri of the prefix for this attributelocalName
- the local name of the attributevalue
- the value of the attribute- Throws:
IllegalStateException
- if the current state does not allow Attribute writingXMLStreamException
- if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true
-
writeNamespace
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 tonamespaceURI
- the uri to bind the prefix to- Throws:
IllegalStateException
- if the current state does not allow Namespace writingXMLStreamException
- if an error occurs
-
writeDefaultNamespace
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 writingXMLStreamException
- if an error occurs
-
writeComment
Writes an xml comment with the data enclosed- Parameters:
data
- the data contained in the comment, may be null- Throws:
XMLStreamException
- if an error occurs
-
writeProcessingInstruction
Writes a processing instruction- Parameters:
target
- the target of the processing instruction, may not be null- Throws:
XMLStreamException
- if an error occurs
-
writeProcessingInstruction
Writes a processing instruction- Parameters:
target
- the target of the processing instruction, may not be nulldata
- the data contained in the processing instruction, may not be null- Throws:
XMLStreamException
- if an error occurs
-
writeCData
Writes a CData section- Parameters:
data
- the data contained in the CData Section, may not be null- Throws:
XMLStreamException
- if an error occurs
-
writeDTD
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
- if an error occurs
-
writeEntityRef
Writes an entity reference- Parameters:
name
- the name of the entity- Throws:
XMLStreamException
- if an error occurs
-
writeStartDocument
Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8- Throws:
XMLStreamException
- if an error occurs
-
writeStartDocument
Write the XML Declaration. Defaults the XML version to 1.0- Parameters:
version
- version of the xml document- Throws:
XMLStreamException
- if an error occurs
-
writeStartDocument
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 declarationversion
- version of the xml document- Throws:
XMLStreamException
- If given encoding does not match encoding of the underlying stream
-
writeCharacters
Write text to the output- Parameters:
text
- the value to write- Throws:
XMLStreamException
- if an error occurs
-
writeCharacters
Write text to the output- Parameters:
text
- the value to writestart
- the starting position in the arraylen
- the number of characters to write- Throws:
XMLStreamException
- if an error occurs
-
getPrefix
Gets the prefix the uri is bound to.- Parameters:
uri
- the uri the prefix is bound to- Returns:
- the prefix or null
- Throws:
XMLStreamException
- if an error occurs
-
setPrefix
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 nulluri
- the uri to bind to the prefix, may be null- Throws:
XMLStreamException
- if an error occurs
-
setDefaultNamespace
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
- if an error occurs
-
setNamespaceContext
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
- if an error occurs
-
getNamespaceContext
NamespaceContext getNamespaceContext()Returns the current namespace context.- Returns:
- the current NamespaceContext
-
getProperty
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 supportedNullPointerException
- if the name is null
-