info.bioinfweb.jphyloio.formats.xml.stax

## Class MetaXMLStreamWriter

- java.lang.Object
- - info.bioinfweb.jphyloio.formats.xml.stax.AbstractMetaXMLWriter
  - - info.bioinfweb.jphyloio.formats.xml.stax.MetaXMLStreamWriter

- All Implemented Interfaces:
    javax.xml.stream.XMLStreamWriter

      public class MetaXMLStreamWriter
      extends AbstractMetaXMLWriter
      implements javax.xml.stream.XMLStreamWriter

  This writer can be used by applications already implementing cursor-based StAX-writing of metadata as an adapter to a `JPhyloIOEventWriter`. Instances of this class should not (and cannot) be created directly in application code, but `JPhyloIOXMLEventWriter.createMetaXMLStreamWriter(JPhyloIOEventReceiver)` should be used instead.

  This writer does not manage namespaces of custom XML elements. The application needs to ensure that all used prefixes (either in any elements, attributes or character data) are properly declared within the custom XML (e.g. by adding `Namespace` events). Any methods of this writer changing the namespace mapping or obtaining information about it refer to the underlying writer. Note that if the default namespace is changed (either by setting a new default namespace or a completely new namespace context object) while this reader is on the top level of custom XML, it is possible that the literal meta end tag is written with the wrong default namespace (it would be written with a prefix then).

  No end elements can be written by this writer, if the according start element was not written with this instance as well.

  Author:
    Sarah Wiechers, Ben Stöver

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MetaXMLStreamWriter(JPhyloIOEventReceiver receiver, javax.xml.stream.XMLStreamWriter underlyingXMLWriter)` Creates a new instance of this class.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` This method has no effect in this writer.
    `void` | `flush()` This method has no effect in this writer, since the underlying `JPhyloIOEventWriter` does not implement a flush() method.
    `javax.xml.namespace.NamespaceContext` | `getNamespaceContext()`
    `java.lang.String` | `getPrefix(java.lang.String uri)`
    `java.lang.Object` | `getProperty(java.lang.String name)`
    `void` | `setDefaultNamespace(java.lang.String uri)`
    `void` | `setNamespaceContext(javax.xml.namespace.NamespaceContext context)`
    `void` | `setPrefix(java.lang.String prefix, java.lang.String uri)`
    `void` | `writeAttribute(java.lang.String localName, java.lang.String value)`
    `void` | `writeAttribute(java.lang.String namespaceURI, java.lang.String localName, java.lang.String value)`
    `void` | `writeAttribute(java.lang.String prefix, java.lang.String namespaceURI, java.lang.String localName, java.lang.String value)`
    `void` | `writeCData(java.lang.String data)`
    `void` | `writeCharacters(char[] text, int start, int len)`
    `void` | `writeCharacters(java.lang.String text)`
    `void` | `writeComment(java.lang.String data)`
    `void` | `writeDefaultNamespace(java.lang.String namespaceURI)`
    `void` | `writeDTD(java.lang.String dtd)`
    `void` | `writeEmptyElement(java.lang.String localName)` It depends on the implementation of XMLStreamWriter returned by `XMLOutputFactory.createXMLStreamWriter(java.io.Writer)` if a self-closing tag or a separate start and end tag is written by this method.
    `void` | `writeEmptyElement(java.lang.String namespaceURI, java.lang.String localName)` It depends on the implementation of XMLStreamWriter returned by `XMLOutputFactory.createXMLStreamWriter(java.io.Writer)` if a self-closing tag or a separate start and end tag is written by this method.
    `void` | `writeEmptyElement(java.lang.String prefix, java.lang.String localName, java.lang.String namespaceURI)` It depends on the implementation of XMLStreamWriter returned by `XMLOutputFactory.createXMLStreamWriter(java.io.Writer)` if a self-closing tag or a separate start and end tag is written by this method.
    `void` | `writeEndDocument()`
    `void` | `writeEndElement()`
    `void` | `writeEntityRef(java.lang.String name)`
    `void` | `writeNamespace(java.lang.String prefix, java.lang.String namespaceURI)`
    `void` | `writeProcessingInstruction(java.lang.String target)`
    `void` | `writeProcessingInstruction(java.lang.String target, java.lang.String data)`
    `void` | `writeStartDocument()`
    `void` | `writeStartDocument(java.lang.String version)`
    `void` | `writeStartDocument(java.lang.String encoding, java.lang.String version)`
    `void` | `writeStartElement(java.lang.String localName)`
    `void` | `writeStartElement(java.lang.String namespaceURI, java.lang.String localName)`
    `void` | `writeStartElement(java.lang.String prefix, java.lang.String localName, java.lang.String namespaceURI)`

    - ### Methods inherited from class info.bioinfweb.jphyloio.formats.xml.stax.AbstractMetaXMLWriter

      `getReceiver, getUnderlyingXMLWriter`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MetaXMLStreamWriter

          public MetaXMLStreamWriter(JPhyloIOEventReceiver receiver,
                                     javax.xml.stream.XMLStreamWriter underlyingXMLWriter)

      Creates a new instance of this class.
      Parameters:
        `receiver` - the event receiver to write the JPhyloIO events created by this writer to
        `underlyingXMLWriter` - the XML writer used by the associated JPhyloIO event writer

  - ### Method Detail

    - #### close

          public void close()
                     throws javax.xml.stream.XMLStreamException

      This method has no effect in this writer. Freeing resources of this writer is not necessary, since it just delegates to another writer.
      Specified by:
        `close` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### flush

          public void flush()
                     throws javax.xml.stream.XMLStreamException

      This method has no effect in this writer, since the underlying `JPhyloIOEventWriter` does not implement a flush() method.
      Specified by:
        `flush` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getNamespaceContext

          public javax.xml.namespace.NamespaceContext getNamespaceContext()

      Specified by:
        `getNamespaceContext` in interface `javax.xml.stream.XMLStreamWriter`

    - #### getPrefix

          public java.lang.String getPrefix(java.lang.String uri)
                                     throws javax.xml.stream.XMLStreamException

      Specified by:
        `getPrefix` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getProperty

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

      Specified by:
        `getProperty` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `java.lang.IllegalArgumentException`

    - #### setDefaultNamespace

          public void setDefaultNamespace(java.lang.String uri)
                                   throws javax.xml.stream.XMLStreamException

      Specified by:
        `setDefaultNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### setNamespaceContext

          public void setNamespaceContext(javax.xml.namespace.NamespaceContext context)
                                   throws javax.xml.stream.XMLStreamException

      Specified by:
        `setNamespaceContext` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### setPrefix

          public void setPrefix(java.lang.String prefix,
                                java.lang.String uri)
                         throws javax.xml.stream.XMLStreamException

      Specified by:
        `setPrefix` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeAttribute

          public void writeAttribute(java.lang.String prefix,
                                     java.lang.String namespaceURI,
                                     java.lang.String localName,
                                     java.lang.String value)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeAttribute

          public void writeAttribute(java.lang.String namespaceURI,
                                     java.lang.String localName,
                                     java.lang.String value)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeAttribute

          public void writeAttribute(java.lang.String localName,
                                     java.lang.String value)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCData

          public void writeCData(java.lang.String data)
                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCData` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCharacters

          public void writeCharacters(char[] text,
                                      int start,
                                      int len)
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCharacters` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCharacters

          public void writeCharacters(java.lang.String text)
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCharacters` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeComment

          public void writeComment(java.lang.String data)
                            throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeComment` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeDTD

          public void writeDTD(java.lang.String dtd)
                        throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeDTD` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeDefaultNamespace

          public void writeDefaultNamespace(java.lang.String namespaceURI)
                                     throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeDefaultNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement(java.lang.String prefix,
                                        java.lang.String localName,
                                        java.lang.String namespaceURI)
                                 throws javax.xml.stream.XMLStreamException

      It depends on the implementation of XMLStreamWriter returned by `XMLOutputFactory.createXMLStreamWriter(java.io.Writer)` if a self-closing tag or a separate start and end tag is written by this method.
      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement(java.lang.String namespaceURI,
                                        java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      It depends on the implementation of XMLStreamWriter returned by `XMLOutputFactory.createXMLStreamWriter(java.io.Writer)` if a self-closing tag or a separate start and end tag is written by this method.
      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement(java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      It depends on the implementation of XMLStreamWriter returned by `XMLOutputFactory.createXMLStreamWriter(java.io.Writer)` if a self-closing tag or a separate start and end tag is written by this method.
      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEndDocument

          public void writeEndDocument()
                                throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEndDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEndElement

          public void writeEndElement()
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEndElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEntityRef

          public void writeEntityRef(java.lang.String name)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEntityRef` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeNamespace

          public void writeNamespace(java.lang.String prefix,
                                     java.lang.String namespaceURI)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeProcessingInstruction

          public void writeProcessingInstruction(java.lang.String target,
                                                 java.lang.String data)
                                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeProcessingInstruction` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeProcessingInstruction

          public void writeProcessingInstruction(java.lang.String target)
                                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeProcessingInstruction` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument()
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument(java.lang.String encoding,
                                         java.lang.String version)
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument(java.lang.String version)
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartElement

          public void writeStartElement(java.lang.String prefix,
                                        java.lang.String localName,
                                        java.lang.String namespaceURI)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartElement

          public void writeStartElement(java.lang.String namespaceURI,
                                        java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartElement

          public void writeStartElement(java.lang.String localName)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`