Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javolution.xml.stream
Interface XMLStreamWriter

All Known Implementing Classes:
  XMLStreamWriterImpl

    public interface XMLStreamWriter

This interface is similar to `javax.xml.stream.XMLStreamWriter`; but it does not forces dynamic allocation when formatting (any `CharSequence` can be used instead of `String`).

Except for the speed (faster) and the added flexibility, the usage/behavior is about the same as its StAX counterpart.

This writer does not require creating new `String` objects during XML formatting. Attributes values can be held by a single/reusable `TextBuilder` (or `StringBuilder`) instance to avoid adverse effects on memory footprint (heap), garbage collection and performance. For example:``

         // Creates a new writer (potentially recycled).
         XMLOutputFactory factory = XMLOutputFactory.newInstance();
         XMLStreamWriter writer = factory.createXMLStreamWriter(outputStream);

         TextBuilder tmp = new TextBuilder();
         writer.writeStartDocument();
         ...
         writer.writeStartElement("Time");
         // Writes primitive types (int) attributes (no memory allocation).
         writer.writeAttribute("hour", tmp.clear().append(time.hour);
         writer.writeAttribute("minute", tmp.clear().append(time.minute);
         writer.writeAttribute("second", tmp.clear().append(time.second);
         writer.writeEndElement();
         ...

         writer.close(); // Recycles this writer.
         outputStream.close(); // Underlying stream has to be closed explicitly.

Note: As always, `null` parameters are not allowed unless explicitly authorized.

Version:
  4.0, June 16, 2006
Author:
  Jean-Marie Dautelle

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.
`java.lang.CharSequence` | `getPrefix(java.lang.CharSequence uri)` Gets the prefix the specified uri is bound to.
`java.lang.Object` | `getProperty(java.lang.String name)` Gets the value of a feature/property from the underlying implementation.
`void` | `setDefaultNamespace(java.lang.CharSequence uri)` Binds a URI to the default namespace.
`void` | `setPrefix(java.lang.CharSequence prefix, java.lang.CharSequence uri)` Sets the prefix the uri is bound to.
`void` | `writeAttribute(java.lang.CharSequence localName, java.lang.CharSequence value)` Writes an attribute to the output stream without a prefix.
`void` | `writeAttribute(java.lang.CharSequence namespaceURI, java.lang.CharSequence localName, java.lang.CharSequence value)` Writes an attribute to the output stream.
`void` | `writeAttribute(java.lang.CharSequence prefix, java.lang.CharSequence namespaceURI, java.lang.CharSequence localName, java.lang.CharSequence value)` Writes an attribute to the output stream.
`void` | `writeCData(java.lang.CharSequence data)` Writes a CData section.
`void` | `writeCharacters(char[] text, int start, int length)` Writes text to the output.
`void` | `writeCharacters(java.lang.CharSequence text)` Writes text to the output.
`void` | `writeComment(java.lang.CharSequence data)` Writes an xml comment with the data enclosed.
`void` | `writeDefaultNamespace(java.lang.CharSequence namespaceURI)` Writes the default namespace to the stream.
`void` | `writeDTD(java.lang.CharSequence dtd)` Writes a DTD section (representing the entire doctypedecl production from the XML 1.0 specification).
`void` | `writeEmptyElement(java.lang.CharSequence localName)` Writes an empty element tag to the output.
`void` | `writeEmptyElement(java.lang.CharSequence namespaceURI, java.lang.CharSequence localName)` Writes an empty element tag to the output.
`void` | `writeEmptyElement(java.lang.CharSequence prefix, java.lang.CharSequence localName, java.lang.CharSequence 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(java.lang.CharSequence name)` Writes an entity reference
`void` | `writeNamespace(java.lang.CharSequence prefix, java.lang.CharSequence namespaceURI)` Writes a namespace to the output stream.
`void` | `writeProcessingInstruction(java.lang.CharSequence target)` Writes a processing instruction.
`void` | `writeProcessingInstruction(java.lang.CharSequence target, java.lang.CharSequence data)` Writes a processing instruction
`void` | `writeStartDocument()` Writes the XML Declaration.
`void` | `writeStartDocument(java.lang.CharSequence version)` Writes the XML Declaration.
`void` | `writeStartDocument(java.lang.CharSequence encoding, java.lang.CharSequence version)` Writes the XML Declaration.
`void` | `writeStartElement(java.lang.CharSequence localName)` Writes a start tag to the output.
`void` | `writeStartElement(java.lang.CharSequence namespaceURI, java.lang.CharSequence localName)` Writes a start tag to the output.
`void` | `writeStartElement(java.lang.CharSequence prefix, java.lang.CharSequence localName, java.lang.CharSequence namespaceURI)` Writes a start tag to the output.

Method Detail

### writeStartElement

    void writeStartElement(java.lang.CharSequence 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.
  Throws:
    `XMLStreamException`

### writeStartElement

    void writeStartElement(java.lang.CharSequence namespaceURI,
                           java.lang.CharSequence localName)
                           throws XMLStreamException

  Writes a start tag to the output.

  Parameters:
    `namespaceURI` - the namespaceURI of the prefix to use.
    `localName` - local name of the tag.
  Throws:
    `XMLStreamException` - if the namespace URI has not been bound to a prefix and this writer does not `repair namespaces`.

### writeStartElement

    void writeStartElement(java.lang.CharSequence prefix,
                           java.lang.CharSequence localName,
                           java.lang.CharSequence namespaceURI)
                           throws XMLStreamException

  Writes a start tag to the output.

  Parameters:
    `localName` - local name of the tag.
    `prefix` - the prefix of the tag.
    `namespaceURI` - the uri to bind the prefix to.
  Throws:
    `XMLStreamException` - if the namespace URI has not been bound to a prefix and this writer does not `repair namespaces`.

### writeEmptyElement

    void writeEmptyElement(java.lang.CharSequence namespaceURI,
                           java.lang.CharSequence localName)
                           throws XMLStreamException

  Writes an empty element tag to the output.

  Parameters:
    `namespaceURI` - the uri to bind the tag to.
    `localName` - local name of the tag.
  Throws:
    `XMLStreamException` - if the namespace URI has not been bound to a prefix and this writer does not `repair namespaces`.

### writeEmptyElement

    void writeEmptyElement(java.lang.CharSequence prefix,
                           java.lang.CharSequence localName,
                           java.lang.CharSequence namespaceURI)
                           throws XMLStreamException

  Writes an empty element tag to the output.

  Parameters:
    `prefix` - the prefix of the tag.
    `localName` - local name of the tag.
    `namespaceURI` - the uri to bind the tag to.
  Throws:
    `XMLStreamException` - if the namespace URI has not been bound to a prefix and this writer does not `repair namespaces`.

### writeEmptyElement

    void writeEmptyElement(java.lang.CharSequence localName)
                           throws XMLStreamException

  Writes an empty element tag to the output.

  Parameters:
    `localName` - local name of the tag.
  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(java.lang.CharSequence localName,
                        java.lang.CharSequence 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:
    `java.lang.IllegalStateException` - if the current state does not allow attribute writing.
    `XMLStreamException`

### writeAttribute

    void writeAttribute(java.lang.CharSequence prefix,
                        java.lang.CharSequence namespaceURI,
                        java.lang.CharSequence localName,
                        java.lang.CharSequence 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:
    `java.lang.IllegalStateException` - if the current state does not allow attribute writing.
    `XMLStreamException` - if the namespace URI has not been bound to a prefix and this writer does not `repair namespaces`.

### writeAttribute

    void writeAttribute(java.lang.CharSequence namespaceURI,
                        java.lang.CharSequence localName,
                        java.lang.CharSequence 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:
    `java.lang.IllegalStateException` - if the current state does not allow attribute writing.
    `XMLStreamException` - if the namespace URI has not been bound to a prefix and this writer does not `repair namespaces`.

### writeNamespace

    void writeNamespace(java.lang.CharSequence prefix,
                        java.lang.CharSequence 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 or `null`
    `namespaceURI` - the uri to bind the prefix.
  Throws:
    `java.lang.IllegalStateException` - if the current state does not allow namespace writing.
    `XMLStreamException`

### writeDefaultNamespace

    void writeDefaultNamespace(java.lang.CharSequence namespaceURI)
                               throws XMLStreamException

  Writes the default namespace to the stream.

  Parameters:
    `namespaceURI` - the uri to bind the default namespace to or `null` (to map the prefix to `""` URI)
  Throws:
    `java.lang.IllegalStateException` - if the current state does not allow namespace writing.
    `XMLStreamException`

### writeComment

    void writeComment(java.lang.CharSequence data)
                      throws XMLStreamException

  Writes an xml comment with the data enclosed.

  Parameters:
    `data` - the data contained in the comment or `null`
  Throws:
    `XMLStreamException`

### writeProcessingInstruction

    void writeProcessingInstruction(java.lang.CharSequence target)
                                    throws XMLStreamException

  Writes a processing instruction.

  Parameters:
    `target` - the target of the processing instruction.
  Throws:
    `XMLStreamException`

### writeProcessingInstruction

    void writeProcessingInstruction(java.lang.CharSequence target,
                                    java.lang.CharSequence data)
                                    throws XMLStreamException

  Writes a processing instruction

  Parameters:
    `target` - the target of the processing instruction.
    `data` - the data contained in the processing instruction.
  Throws:
    `XMLStreamException`

### writeCData

    void writeCData(java.lang.CharSequence data)
                    throws XMLStreamException

  Writes a CData section.

  Parameters:
    `data` - the data contained in the CData Section.
  Throws:
    `XMLStreamException`

### writeDTD

    void writeDTD(java.lang.CharSequence dtd)
                  throws XMLStreamException

  Writes a DTD section (representing the entire doctypedecl production from the XML 1.0 specification).

  Parameters:
    `dtd` - the DTD to be written.
  Throws:
    `XMLStreamException`

### writeEntityRef

    void writeEntityRef(java.lang.CharSequence name)
                        throws XMLStreamException

  Writes an entity reference

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

### writeStartDocument

    void writeStartDocument()
                            throws XMLStreamException

  Writes the XML Declaration. Defaults the XML version to 1.0 and the encoding (if any) to the one specified when the instance is created using `XMLOutputFactory`.

  Throws:
    `XMLStreamException`

### writeStartDocument

    void writeStartDocument(java.lang.CharSequence version)
                            throws XMLStreamException

  Writes the XML Declaration. Default the encoding (if any) to the one specified when the instance is created using `XMLOutputFactory`.

  Parameters:
    `version` - the version of the xml document or `null`.
  Throws:
    `XMLStreamException`

### writeStartDocument

    void writeStartDocument(java.lang.CharSequence encoding,
                            java.lang.CharSequence version)
                            throws XMLStreamException

  Writes 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 when the instance is created using `XMLOutputFactory`.

  Parameters:
    `encoding` - the encoding of the xml declaration or `null`.
    `version` - the version of the xml document or `null`.
  Throws:
    `XMLStreamException`

### writeCharacters

    void writeCharacters(java.lang.CharSequence text)
                         throws XMLStreamException

  Writes text to the output.

  Parameters:
    `text` - the value to write or `null`.
  Throws:
    `XMLStreamException`

### writeCharacters

    void writeCharacters(char[] text,
                         int start,
                         int length)
                         throws XMLStreamException

  Writes text to the output.

  Parameters:
    `text` - the value to write
    `start` - the starting position in the array.
    `length` - the number of characters to write.
  Throws:
    `XMLStreamException`

### getPrefix

    java.lang.CharSequence getPrefix(java.lang.CharSequence uri)
                                     throws XMLStreamException

  Gets the prefix the specified uri is bound to.

  Parameters:
    `uri` - namespace URI
  Returns:
    the prefix for the URI or `null`
  Throws:
    `XMLStreamException`

### setPrefix

    void setPrefix(java.lang.CharSequence prefix,
                   java.lang.CharSequence 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.
    `uri` - the uri to bind to the prefix or `null`
  Throws:
    `XMLStreamException`

### setDefaultNamespace

    void setDefaultNamespace(java.lang.CharSequence 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 or `null`.
  Throws:
    `XMLStreamException`

### getProperty

    java.lang.Object getProperty(java.lang.String name)
                                 throws java.lang.IllegalArgumentException

  Gets the value of a feature/property from the underlying implementation.

  Parameters:
    `name` - the name of the property.
  Returns:
    the value of the property.
  Throws:
    `java.lang.IllegalArgumentException` - if the property is not supported.

Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2005 - 2007 Javolution.