XMLStreamWriter

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.

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

Since:: 1.6
See Also:: XMLOutputFactory, XMLStreamReader

Method Summary

All Methods

Instance Methods

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

- Method Detail
  - writeStartElement
```
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 - local name of the tag, may not be null
    
    Throws:
    
    XMLStreamException -
  - writeStartElement
```
void writeStartElement(String namespaceURI,
                       String localName)
                throws XMLStreamException
```
    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
  - writeStartElement
```
void writeStartElement(String prefix,
                       String localName,
                       String namespaceURI)
                throws XMLStreamException
```
    Writes a start tag to the output
    
    Parameters:
    
    localName - local name of the tag, may not be null
    
    prefix - the prefix of the tag, may not be null
    
    namespaceURI - the uri to bind the prefix to, may not be null
    
    Throws:
    
    XMLStreamException -
  - writeEmptyElement
```
void writeEmptyElement(String namespaceURI,
                       String localName)
                throws XMLStreamException
```
    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
  - 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 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 -
  - writeEmptyElement
```
void writeEmptyElement(String localName)
                throws XMLStreamException
```
    Writes an empty element tag to the output
    
    Parameters:
    
    localName - local name of the tag, may not be null
    
    Throws:
    
    XMLStreamException -
  - writeEndElement
```
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.
    
    Throws:
    
    XMLStreamException -
  - writeEndDocument
```
void writeEndDocument()
               throws XMLStreamException
```
    Closes any start tags and writes corresponding end tags.
    
    Throws:
    
    XMLStreamException -
  - close
```
void close()
    throws XMLStreamException
```
    Close this writer and free any resources associated with the writer. This must not close the underlying output stream.
    
    Throws:
    
    XMLStreamException -
  - flush
```
void flush()
    throws XMLStreamException
```
    Write any cached data to the underlying output mechanism.
    
    Throws:
    
    XMLStreamException -
  - writeAttribute
```
void writeAttribute(String localName,
                    String value)
             throws XMLStreamException
```
    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 -
  - 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 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
  - writeAttribute
```
void writeAttribute(String namespaceURI,
                    String localName,
                    String value)
             throws XMLStreamException
```
    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
  - writeNamespace
```
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 - 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 -
  - writeDefaultNamespace
```
void writeDefaultNamespace(String namespaceURI)
                    throws XMLStreamException
```
    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 -
  - writeComment
```
void writeComment(String data)
           throws XMLStreamException
```
    Writes an xml comment with the data enclosed
    
    Parameters:
    
    data - the data contained in the comment, may be null
    
    Throws:
    
    XMLStreamException -
  - writeProcessingInstruction
```
void writeProcessingInstruction(String target)
                         throws XMLStreamException
```
    Writes a processing instruction
    
    Parameters:
    
    target - the target of the processing instruction, may not be null
    
    Throws:
    
    XMLStreamException -
  - writeProcessingInstruction
```
void writeProcessingInstruction(String target,
                                String data)
                         throws XMLStreamException
```
    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 -
  - writeCData
```
void writeCData(String data)
         throws XMLStreamException
```
    Writes a CData section
    
    Parameters:
    
    data - the data contained in the CData Section, may not be null
    
    Throws:
    
    XMLStreamException -
  - writeDTD
```
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 - the DTD to be written
    
    Throws:
    
    XMLStreamException -
  - writeEntityRef
```
void writeEntityRef(String name)
             throws XMLStreamException
```
    Writes an entity reference
    
    Parameters:
    
    name - the name of the entity
    
    Throws:
    
    XMLStreamException -
  - writeStartDocument
```
void writeStartDocument()
                 throws XMLStreamException
```
    Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
    
    Throws:
    
    XMLStreamException -
  - writeStartDocument
```
void writeStartDocument(String version)
                 throws XMLStreamException
```
    Write the XML Declaration. Defaults the XML version to 1.0
    
    Parameters:
    
    version - version of the xml document
    
    Throws:
    
    XMLStreamException -
  - writeStartDocument
```
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 - encoding of the xml declaration
    
    version - version of the xml document
    
    Throws:
    
    XMLStreamException - If given encoding does not match encoding of the underlying stream
  - writeCharacters
```
void writeCharacters(String text)
              throws XMLStreamException
```
    Write text to the output
    
    Parameters:
    
    text - the value to write
    
    Throws:
    
    XMLStreamException -
  - writeCharacters
```
void writeCharacters(char[] text,
                     int start,
                     int len)
              throws XMLStreamException
```
    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 -
  - getPrefix
```
String getPrefix(String uri)
          throws XMLStreamException
```
    Gets the prefix the uri is bound to
    
    Returns:
    
    the prefix or null
    
    Throws:
    
    XMLStreamException -
  - setPrefix
```
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 - the prefix to bind to the uri, may not be null
    
    uri - the uri to bind to the prefix, may be null
    
    Throws:
    
    XMLStreamException -
  - setDefaultNamespace
```
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 - the uri to bind to the default namespace, may be null
    
    Throws:
    
    XMLStreamException -
  - setNamespaceContext
```
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 - the namespace context to use for this writer, may not be null
    
    Throws:
    
    XMLStreamException -
  - getNamespaceContext
```
NamespaceContext getNamespaceContext()
```
    Returns the current namespace context.
    
    Returns:
    
    the current NamespaceContext
  - getProperty
```
Object getProperty(String name)
            throws IllegalArgumentException
```
    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

Interface XMLStreamWriter

Method Summary

Method Detail

writeStartElement

writeStartElement

writeStartElement

writeEmptyElement

writeEmptyElement

writeEmptyElement

writeEndElement

writeEndDocument

close

flush

writeAttribute

writeAttribute

writeAttribute

writeNamespace

writeDefaultNamespace

writeComment

writeProcessingInstruction

writeProcessingInstruction

writeCData

writeDTD

writeEntityRef

writeStartDocument

writeStartDocument

writeStartDocument

writeCharacters

writeCharacters

getPrefix

setPrefix

setDefaultNamespace

setNamespaceContext

getNamespaceContext

getProperty