info.bioinfweb.jphyloio.formats.xml

## Class AbstractXMLEventReader<P extends XMLReaderStreamDataProvider<? extends AbstractXMLEventReader<P>>>

- java.lang.Object
- - info.bioinfweb.jphyloio.AbstractEventReader<P>
  - - info.bioinfweb.jphyloio.formats.xml.AbstractXMLEventReader<P>

- All Implemented Interfaces:
    JPhyloIOXMLEventReader, JPhyloIOEventReader, JPhyloIOFormatSpecificObject, ReadWriteConstants
  Direct Known Subclasses:
    NeXMLEventReader, PDEEventReader, PhyloXMLEventReader, XTGEventReader

      public abstract class AbstractXMLEventReader<P extends XMLReaderStreamDataProvider<? extends AbstractXMLEventReader<P>>>
      extends AbstractEventReader<P>
      implements JPhyloIOXMLEventReader

  Implements shared functionality for reading XML formats.
  Since:
    0.0.0
  Author:
    Ben Stöver, Sarah Wiechers

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `INTERNAL_USE_NAMESPACE`
    `static javax.xml.namespace.QName` | `TAG_PARENT_OF_ROOT`

    - ### Fields inherited from interface info.bioinfweb.jphyloio.ReadWriteConstants

      `ATTRIBUTE_STRING_KEY, ATTRIBUTES_NAMESPACE_FOLDER, DATA_TYPE_NAMESPACE_FOLDER, DATA_TYPE_SIMPLE_VALUE_LIST, DEFAULT_CHAR_SET_ID_PREFIX, DEFAULT_CHARACTER_DEFINITION_ID_PREFIX, DEFAULT_EDGE_ID_PREFIX, DEFAULT_GENERAL_ID_PREFIX, DEFAULT_MATRIX_ID_PREFIX, DEFAULT_MAX_COMMENT_LENGTH, DEFAULT_MAX_TOKENS_TO_READ, DEFAULT_META_ID_PREFIX, DEFAULT_NETWORK_ID_PREFIX, DEFAULT_NODE_EDGE_SET_ID_PREFIX, DEFAULT_NODE_ID_PREFIX, DEFAULT_OTU_ID_PREFIX, DEFAULT_OTU_LIST_ID_PREFIX, DEFAULT_OTU_SET_ID_PREFIX, DEFAULT_SEQUENCE_ID_PREFIX, DEFAULT_SEQUENCE_SET_ID_PREFIX, DEFAULT_TOKEN_DEFINITION_ID_PREFIX, DEFAULT_TOKEN_SET_ID_PREFIX, DEFAULT_TREE_ID_PREFIX, DEFAULT_TREE_NETWORK_GROUP_ID_PREFIX, DEFAULT_TREE_NETWORK_SET_ID_PREFIX, JPHYLOIO_ATTRIBUTES_NAMESPACE, JPHYLOIO_ATTRIBUTES_PREFIX, JPHYLOIO_DATA_TYPE_NAMESPACE, JPHYLOIO_DATA_TYPE_PREFIX, JPHYLOIO_FORMATS_NAMESPACE_PREFIX, JPHYLOIO_GENERAL_NAMESPACE, JPHYLOIO_NAMESPACE_PREFIX, JPHYLOIO_PREDICATE_NAMESPACE, JPHYLOIO_PREDICATE_PREFIX, PREDICATE_CHARACTER_COUNT, PREDICATE_EDGE_LENGTH, PREDICATE_EDGE_SOURCE_NODE, PREDICATE_EDGE_TARGET_NODE, PREDICATE_HAS_CUSTOM_XML, PREDICATE_HAS_LITERAL_METADATA, PREDICATE_HAS_RESOURCE_METADATA, PREDICATE_IS_CROSSLINK, PREDICATE_NAMESPACE_FOLDER, PREDICATE_PART_SEPERATOR, PREDICATE_SEQUENCE_COUNT, RESERVED_ID_PREFIX`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractXMLEventReader(java.io.File file, ReadWriteParameterMap parameters)`
    `AbstractXMLEventReader(java.io.InputStream stream, ReadWriteParameterMap parameters)`
    `AbstractXMLEventReader(java.io.Reader reader, ReadWriteParameterMap parameters)`
    `AbstractXMLEventReader(javax.xml.stream.XMLEventReader xmlReader, ReadWriteParameterMap parameters)`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the underlying document source (usually a stream).
    `MetaXMLEventReader` | `createMetaXMLEventReader()` Creates a new `XMLEventReader` that allows to read events of XML content of literal metadata from this JPhyloIO event reader instance through that interface.
    `MetaXMLStreamReader` | `createMetaXMLStreamReader()` Creates a `XMLStreamReader` that allows to read events of XML content of literal metadata from this JPhyloIO event reader instance through that interface.
    `protected P` | `createStreamDataProvider()` This method is called in the constructor of `AbstractEventReader` to initialize the stream data provider that will be returned by `AbstractEventReader.getStreamDataProvider()`.
    `protected abstract void` | `fillMap()`
    `protected XMLElementReader<P>` | `getElementReader(javax.xml.namespace.QName parentTag, javax.xml.namespace.QName elementTag, int eventType)`
    `protected java.util.Map<XMLElementReaderKey,XMLElementReader<P>>` | `getElementReaderMap()`
    `protected java.util.Stack<javax.xml.namespace.QName>` | `getEncounteredTags()`
    `javax.xml.namespace.NamespaceContext` | `getNamespaceContext()` Returns the currently valid namespace context object or `null`, if the root element was not yet read.
    `javax.xml.stream.XMLEventReader` | `getXMLReader()`
    `protected boolean` | `isAllowDefaultNamespace()`
    `javax.xml.namespace.QName` | `parseQName(java.lang.String curie, javax.xml.stream.events.StartElement element)`
    `protected void` | `putElementReader(XMLElementReaderKey key, XMLElementReader<P> reader)`
    `protected void` | `readNextEvent()` Method to be implemented be inherited classes that adds at least one additional event (determined from the underlying data source) to the event queue.

    - ### Methods inherited from class info.bioinfweb.jphyloio.AbstractEventReader

      `addEventListener, fireEvent, getCurrentEventCollection, getIDManager, getLastNonCommentEvent, getParameters, getParentInformation, getPreviousEvent, getSequenceTokensEventManager, getStreamDataProvider, getUpcomingEvents, hasNextEvent, hasSpecialEventCollection, isBeforeFirstAccess, next, nextOfType, peek, removeEventListener, resetCurrentEventCollection, setCurrentEventCollection`

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

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

    - ### Methods inherited from interface info.bioinfweb.jphyloio.JPhyloIOEventReader

      `addEventListener, getLastNonCommentEvent, getParentInformation, getPreviousEvent, hasNextEvent, next, nextOfType, peek, removeEventListener`

    - ### Methods inherited from interface info.bioinfweb.jphyloio.JPhyloIOFormatSpecificObject

      `getFormatID`

- - ### Field Detail

    - #### INTERNAL_USE_NAMESPACE

          public static final java.lang.String INTERNAL_USE_NAMESPACE

      See Also:
        Constant Field Values

    - #### TAG_PARENT_OF_ROOT

          public static final javax.xml.namespace.QName TAG_PARENT_OF_ROOT

  - ### Constructor Detail

    - #### AbstractXMLEventReader

          public AbstractXMLEventReader(java.io.File file,
                                        ReadWriteParameterMap parameters)
                                 throws java.io.IOException,
                                        javax.xml.stream.XMLStreamException

      Throws:
        `java.io.IOException`
        `javax.xml.stream.XMLStreamException`

    - #### AbstractXMLEventReader

          public AbstractXMLEventReader(java.io.InputStream stream,
                                        ReadWriteParameterMap parameters)
                                 throws java.io.IOException,
                                        javax.xml.stream.XMLStreamException

      Throws:
        `java.io.IOException`
        `javax.xml.stream.XMLStreamException`

    - #### AbstractXMLEventReader

          public AbstractXMLEventReader(javax.xml.stream.XMLEventReader xmlReader,
                                        ReadWriteParameterMap parameters)

    - #### AbstractXMLEventReader

          public AbstractXMLEventReader(java.io.Reader reader,
                                        ReadWriteParameterMap parameters)
                                 throws java.io.IOException,
                                        javax.xml.stream.XMLStreamException

      Throws:
        `java.io.IOException`
        `javax.xml.stream.XMLStreamException`

  - ### Method Detail

    - #### isAllowDefaultNamespace

          protected boolean isAllowDefaultNamespace()

    - #### putElementReader

          protected void putElementReader(XMLElementReaderKey key,
                                          XMLElementReader<P> reader)

    - #### fillMap

          protected abstract void fillMap()

    - #### readNextEvent

          protected void readNextEvent()
                                throws java.io.IOException

      Description copied from class: `AbstractEventReader`
      Method to be implemented be inherited classes that adds at least one additional event (determined from the underlying data source) to the event queue.
      Specified by:
        `readNextEvent` in class `AbstractEventReader<P extends XMLReaderStreamDataProvider<? extends AbstractXMLEventReader<P>>>`
      Throws:
        `java.io.IOException`

    - #### getElementReader

          protected XMLElementReader<P> getElementReader(javax.xml.namespace.QName parentTag,
                                                         javax.xml.namespace.QName elementTag,
                                                         int eventType)

    - #### parseQName

          public javax.xml.namespace.QName parseQName(java.lang.String curie,
                                                      javax.xml.stream.events.StartElement element)
                                               throws JPhyloIOReaderException

      Throws:
        `JPhyloIOReaderException`

    - #### createStreamDataProvider

          protected P createStreamDataProvider()

      Description copied from class: `AbstractEventReader`
      This method is called in the constructor of `AbstractEventReader` to initialize the stream data provider that will be returned by `AbstractEventReader.getStreamDataProvider()`. Inherit classes that use their own stream data provider implementation should overwrite this method.

      This default implementation creates a new instance of `ReaderStreamDataProvider`.

      Overrides:
        `createStreamDataProvider` in class `AbstractEventReader<P extends XMLReaderStreamDataProvider<? extends AbstractXMLEventReader<P>>>`
      Returns:
        the stream data provider to be used with this instance

    - #### getXMLReader

          public javax.xml.stream.XMLEventReader getXMLReader()

    - #### getEncounteredTags

          protected java.util.Stack<javax.xml.namespace.QName> getEncounteredTags()

    - #### getElementReaderMap

          protected java.util.Map<XMLElementReaderKey,XMLElementReader<P>> getElementReaderMap()

    - #### getNamespaceContext

          public javax.xml.namespace.NamespaceContext getNamespaceContext()

      Returns the currently valid namespace context object or `null`, if the root element was not yet read.
      Specified by:
        `getNamespaceContext` in interface `JPhyloIOXMLEventReader`
      Returns:
        the currently valid namespace context or `null`

    - #### createMetaXMLEventReader

          public MetaXMLEventReader createMetaXMLEventReader()
                                                      throws java.lang.IllegalStateException

      Description copied from interface: `JPhyloIOXMLEventReader`
      Creates a new `XMLEventReader` that allows to read events of XML content of literal metadata from this JPhyloIO event reader instance through that interface. Instances can be created any time, while this instance is located inside a literal metadata subsequence with the `LiteralContentSequenceType.XML`, but not outside of such a sequence.

      In principle this method may be called multiple times within the same literal metadata event subsequence, which would result in having multiple XML event reader instances delegating to the same JPhyloIO reader, although that is not recommended for performance reasons.

      Specified by:
        `createMetaXMLEventReader` in interface `JPhyloIOXMLEventReader`
      Returns:
        the new reader instance
      Throws:
        `java.lang.IllegalStateException` - if no reader can be created at the current position (outside of a literal metadata event subsequence with type `LiteralContentSequenceType.XML`)

    - #### createMetaXMLStreamReader

          public MetaXMLStreamReader createMetaXMLStreamReader()
                                                        throws java.lang.IllegalStateException

      Description copied from interface: `JPhyloIOXMLEventReader`
      Creates a `XMLStreamReader` that allows to read events of XML content of literal metadata from this JPhyloIO event reader instance through that interface. Instances can be created any time, while this instance is located inside a literal metadata subsequence with the `LiteralContentSequenceType.XML`, but not outside of such a sequence.

      In principle this method may be called multiple times within the same literal metadata event subsequence, which would result in having multiple XML event reader instances delegating to the same JPhyloIO reader, although that is not recommended for performance reasons.

      Specified by:
        `createMetaXMLStreamReader` in interface `JPhyloIOXMLEventReader`
      Returns:
        the new reader instance
      Throws:
        `java.lang.IllegalStateException` - if no reader can be created at the current position (outside of a literal metadata event subsequence with type `LiteralContentSequenceType.XML`)

    - #### close

          public void close()
                     throws java.io.IOException

      Description copied from interface: `JPhyloIOEventReader`
      Closes the underlying document source (usually a stream).
      Specified by:
        `close` in interface `JPhyloIOEventReader`
      Overrides:
        `close` in class `AbstractEventReader<P extends XMLReaderStreamDataProvider<? extends AbstractXMLEventReader<P>>>`
      Throws:
        `java.io.IOException` - Implementing classes might throw different types of exceptions if the stream cannot be closed properly