This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
Overview  Package   Class 
 PREV CLASS   NEXT CLASS FRAMES   NO FRAMES 
SUMMARY: NESTED | FIELD | CONSTR | METHOD  DETAIL: FIELD | CONSTR | METHOD 

javax.xml.stream
interface XMLStreamWriter

Most common ways to construct:

XMLOutputFactory ofactory = …;
ByteArrayOutputStream bos = …;

XMLStreamWriter writer = ofactory.createXMLStreamWriter(bos);

Based on 9 examples

 

XMLOutputFactory factory = …;
OutputStream out = …;

XMLStreamWriter writer = factory.createXMLStreamWriter(out);

Based on 9 examples

 

XMLOutputFactory outputFactory = …;
StringWriter writer = …;

XMLStreamWriter streamWriter = outputFactory.createXMLStreamWriter(writer);

Based on 8 examples 

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

Method Summary
 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

close

public 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

public void flush()
           throws XMLStreamException
Write any cached data to the underlying output mechanism.

Throws:
XMLStreamException

getNamespaceContext

public NamespaceContext getNamespaceContext()
Returns the current namespace context.

Returns:
the current NamespaceContext

getPrefix

public String getPrefix(String uri)
                 throws XMLStreamException
Gets the prefix the uri is bound to

Parameters:
uri
Returns:
the prefix or null
Throws:
XMLStreamException

getProperty

public 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

setDefaultNamespace

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 - the uri to bind to the default namespace, may be null
Throws:
XMLStreamException

setNamespaceContext

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 - the namespace context to use for this writer, may not be null
Throws:
XMLStreamException

setPrefix

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 - the prefix to bind to the uri, may not be null
uri - the uri to bind to the prefix, may be null
Throws:
XMLStreamException

writeAttribute

public 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:
XMLStreamException

writeAttribute

public 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:
XMLStreamException - if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

writeAttribute

public 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:
XMLStreamException - if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

writeCData

public 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

writeCharacters

public 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

writeCharacters

public void writeCharacters(String text)
                     throws XMLStreamException
Write text to the output

Parameters:
text - the value to write
Throws:
XMLStreamException

writeComment

public 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

writeDefaultNamespace

public void writeDefaultNamespace(String namespaceURI)
                           throws XMLStreamException
Writes the default namespace to the stream

Parameters:
namespaceURI - the uri to bind the default namespace to
Throws:
XMLStreamException

writeDTD

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 - the DTD to be written
Throws:
XMLStreamException

writeEmptyElement

public 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

writeEmptyElement

public 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

public 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

writeEndDocument

public void writeEndDocument()
                      throws XMLStreamException
Closes any start tags and writes corresponding end tags.

Throws:
XMLStreamException

writeEndElement

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.

Throws:
XMLStreamException

writeEntityRef

public void writeEntityRef(String name)
                    throws XMLStreamException
Writes an entity reference

Parameters:
name - the name of the entity
Throws:
XMLStreamException

writeNamespace

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 - the prefix to bind this namespace to
namespaceURI - the uri to bind the prefix to
Throws:
XMLStreamException

writeProcessingInstruction

public 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

public 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

writeStartDocument

public void writeStartDocument()
                        throws XMLStreamException
Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8

Throws:
XMLStreamException

writeStartDocument

public 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

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 - encoding of the xml declaration
version - version of the xml document
Throws:
XMLStreamException - If given encoding does not match encoding of the underlying stream

writeStartElement

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 - local name of the tag, may not be null
Throws:
XMLStreamException

writeStartElement

public 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

public 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 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
Overview  Package   Class 
 PREV CLASS   NEXT CLASS FRAMES   NO FRAMES 
SUMMARY: NESTED | FIELD | CONSTR | METHOD  DETAIL: FIELD | CONSTR | METHOD 
This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
This page displays the Jadeite version of the documention, which is derived from the offical documentation that contains this copyright notice:
Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
The official Sun™ documentation can be found here at http://java.sun.com/javase/6/docs/api/.