Save This Page
Home » openjdk-7 » javax » xml » stream » [javadoc | source]
javax.xml.stream
public interface: XMLStreamWriter [javadoc | source] 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 from javax.xml.stream.XMLStreamWriter Summary:
close,   flush,   getNamespaceContext,   getPrefix,   getProperty,   setDefaultNamespace,   setNamespaceContext,   setPrefix,   writeAttribute,   writeAttribute,   writeAttribute,   writeCData,   writeCharacters,   writeCharacters,   writeComment,   writeDTD,   writeDefaultNamespace,   writeEmptyElement,   writeEmptyElement,   writeEmptyElement,   writeEndDocument,   writeEndElement,   writeEntityRef,   writeNamespace,   writeProcessingInstruction,   writeProcessingInstruction,   writeStartDocument,   writeStartDocument,   writeStartDocument,   writeStartElement,   writeStartElement,   writeStartElement
Method from javax.xml.stream.XMLStreamWriter Detail:
 public  void close() throws XMLStreamException
    Close this writer and free any resources associated with the writer. This must not close the underlying output stream.
 public  void flush() throws XMLStreamException
    Write any cached data to the underlying output mechanism.
 public NamespaceContext getNamespaceContext()
    Returns the current namespace context.
 public String getPrefix(String uri) throws XMLStreamException
    Gets the prefix the uri is bound to
 public Object getProperty(String name) throws IllegalArgumentException
    Get the value of a feature/property from the underlying implementation
 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.
 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.
 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.
 public  void writeAttribute(String localName,
    String value) throws XMLStreamException
    Writes an attribute to the output stream without a prefix.
 public  void writeAttribute(String namespaceURI,
    String localName,
    String value) throws XMLStreamException
    Writes an attribute to the output stream
 public  void writeAttribute(String prefix,
    String namespaceURI,
    String localName,
    String value) throws XMLStreamException
    Writes an attribute to the output stream
 public  void writeCData(String data) throws XMLStreamException
    Writes a CData section
 public  void writeCharacters(String text) throws XMLStreamException
    Write text to the output
 public  void writeCharacters(char[] text,
    int start,
    int len) throws XMLStreamException
    Write text to the output
 public  void writeComment(String data) throws XMLStreamException
    Writes an xml comment with the data enclosed
 public  void writeDTD(String dtd) throws XMLStreamException
    Write a DTD section. This string represents the entire doctypedecl production from the XML 1.0 specification.
 public  void writeDefaultNamespace(String namespaceURI) throws XMLStreamException
    Writes the default namespace to the stream
 public  void writeEmptyElement(String localName) throws XMLStreamException
    Writes an empty element tag to the output
 public  void writeEmptyElement(String namespaceURI,
    String localName) throws XMLStreamException
    Writes an empty element tag to the output
 public  void writeEmptyElement(String prefix,
    String localName,
    String namespaceURI) throws XMLStreamException
    Writes an empty element tag to the output
 public  void writeEndDocument() throws XMLStreamException
    Closes any start tags and writes corresponding end tags.
 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.
 public  void writeEntityRef(String name) throws XMLStreamException
    Writes an entity reference
 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
 public  void writeProcessingInstruction(String target) throws XMLStreamException
    Writes a processing instruction
 public  void writeProcessingInstruction(String target,
    String data) throws XMLStreamException
    Writes a processing instruction
 public  void writeStartDocument() throws XMLStreamException
    Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
 public  void writeStartDocument(String version) throws XMLStreamException
    Write the XML Declaration. Defaults the XML version to 1.0
 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
 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.
 public  void writeStartElement(String namespaceURI,
    String localName) throws XMLStreamException
    Writes a start tag to the output
 public  void writeStartElement(String prefix,
    String localName,
    String namespaceURI) throws XMLStreamException
    Writes a start tag to the output