Module java.xml

Interface 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 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
      • 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
      • 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
      • 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
      • 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​(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
      • 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