info.bioinfweb.jphyloio.formats.nexml

## Class NeXMLEventReader

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

- All Implemented Interfaces:
    NeXMLConstants, JPhyloIOXMLEventReader, JPhyloIOEventReader, JPhyloIOFormatSpecificObject, ReadWriteConstants

      public class NeXMLEventReader
      extends AbstractXMLEventReader<NeXMLReaderStreamDataProvider>
      implements NeXMLConstants

  An event reader for the NeXML format. The majority of NeXML elements are supported by this reader, since the data model of JPhyloIO is heavily influenced by the data model of NeXML.

  Element IDs found in NeXML documents are directly used as IDs of JPhyloIO events. All `meta` tags of NeXML are represented by according `ResourceMetadataEvent`s or `LiteralMetadataEvent`s. Since there are no equivalent JPhyloIO events for the `format` or `matrix` tags of NeXML, metadata nested under these tags is translated into meta-events between the start and end events of the type `EventContentType.ALIGNMENT`. To distinguish them from meta-events generated from `meta` tags nested directly under the `characters` tag (which are are also fired at this position), these meta-events are grouped by resource meta start and end events with the predicates `NeXMLConstants.PREDICATE_FORMAT` or `NeXMLConstants.PREDICATE_MATRIX` around them. (Note that these events are generated by the reader only to group according metadata and do not have any equivalent `meta` tag in the document. `NeXMLEventWriter` can handle such metadata structures accordingly.) NeXML specific tags found nested under a literal `meta` tag are processed in the same manner as custom XML elements in this position.

  NeXML can store different types of sequence data. While DNA, RNA, amino acid and continuous data is processed straightforwardly, restriction and standard data is both processed as `CharacterStateSetType.DISCRETE`. Standard data represented by integers is translated according to the specified, either to the ID or label specified in the token definition or not at all. `SingleSequenceTokenEvent`s generated from tokens in `cell` tags are fired in the order of the alignment columns the tokens belong to. If they are not in the correct order in the file, some buffering is necessary to sort them.

  Most of the sets modeled in NeXML are supported by JPhyloIO as well, however sets of cells and sets of character states are currently not. These sets will be ignored while reading a NeXML document.

  ### Recognized parameters

  - `ReadWriteParameterNames.KEY_LOGGER`
  - `ReadWriteParameterNames.KEY_OBJECT_TRANSLATOR_FACTORY`
  - `ReadWriteParameterNames.KEY_ALLOW_DEFAULT_NAMESPACE`
  - `ReadWriteParameterNames.KEY_NEXML_TOKEN_TRANSLATION_STRATEGY`
  - `ReadWriteParameterNames.KEY_USE_OTU_LABEL`
  Since:
    0.0.0
  Author:
    Sarah Wiechers, Ben Stöver
  See Also:
    Metadata demo application

- - ### Field Summary

    - ### Fields inherited from class info.bioinfweb.jphyloio.formats.xml.AbstractXMLEventReader

      `INTERNAL_USE_NAMESPACE, TAG_PARENT_OF_ROOT`

    - ### Fields inherited from interface info.bioinfweb.jphyloio.formats.nexml.NeXMLConstants

      `ATTR_ABOUT, ATTR_CELL_SET_LINKED_IDS, ATTR_CHAR_SET_LINKED_IDS, ATTR_CODON_POSITION, ATTR_CONTENT, ATTR_DATATYPE, ATTR_GENERATOR, ATTR_HREF, ATTR_ID, ATTR_LABEL, ATTR_LENGTH, ATTR_NODE_EDGE_SET_LINKED_EDGE_IDS, ATTR_NODE_EDGE_SET_LINKED_NODE_IDS, ATTR_NODE_EDGE_SET_LINKED_ROOTEDGE_IDS, ATTR_OTU_SET_LINKED_IDS, ATTR_OTUS, ATTR_PROPERTY, ATTR_REL, ATTR_ROOT, ATTR_SEQUENCE_SET_LINKED_IDS, ATTR_SINGLE_CHAR_LINK, ATTR_SINGLE_OTU_LINK, ATTR_SINGLE_STATE_LINK, ATTR_SOURCE, ATTR_STATE_SET_LINKED_IDS, ATTR_STATES, ATTR_SYMBOL, ATTR_TARGET, ATTR_TOKENS, ATTR_TREE_SET_LINKED_NETWORK_IDS, ATTR_TREE_SET_LINKED_TREE_IDS, ATTR_VERSION, ATTR_XSI_TYPE, DEFAULT_TOKEN_DEFINITION_SET_ID_PREFIX, NEXML_DEFAULT_NAMESPACE_PREFIX, NEXML_FORMAT_NAME, NEXML_NAMESPACE, NEXML_NAMESPACE_PREFIX, NEXML_PREDICATE_NAMESPACE, NEXML_VERSION, PREDICATE_CHAR_ATTR_CODON_POSITION, PREDICATE_CHAR_ATTR_TOKENS, PREDICATE_FORMAT, PREDICATE_MATRIX, PREDICATE_ORIGINAL_LABEL, PREDICATE_ORIGINAL_TOKEN_NAME, TAG_CELL, TAG_CHAR, TAG_CHARACTERS, TAG_EDGE, TAG_FORMAT, TAG_MATRIX, TAG_MEMBER, TAG_META, TAG_NETWORK, TAG_NODE, TAG_OTU, TAG_OTUS, TAG_POLYMORPHIC, TAG_ROOT, TAG_ROOTEDGE, TAG_ROW, TAG_SEQ, TAG_SET, TAG_STATE, TAG_STATES, TAG_TREE, TAG_TREES, TAG_UNCERTAIN, TYPE_CONTIN_CELLS, TYPE_CONTIN_SEQ, TYPE_DNA_CELLS, TYPE_DNA_SEQS, TYPE_FLOAT_NETWORK, TYPE_FLOAT_TREE, TYPE_INT_NETWORK, TYPE_INT_TREE, TYPE_LITERAL_META, TYPE_PROTEIN_CELLS, TYPE_PROTEIN_SEQS, TYPE_RESOURCE_META, TYPE_RESTRICTION_CELLS, TYPE_RESTRICTION_SEQS, TYPE_RNA_CELLS, TYPE_RNA_SEQS, TYPE_STANDARD_CELLS, TYPE_STANDARD_SEQ, UNDEFINED_OTU_ID_PREFIX, UNDEFINED_OTU_LABEL, UNDEFINED_OTUS_ID_PREFIX, UNDEFINED_OTUS_LABEL`

    - ### 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
    `NeXMLEventReader(java.io.File file, ReadWriteParameterMap parameters)`
    `NeXMLEventReader(java.io.InputStream stream, ReadWriteParameterMap parameters)`
    `NeXMLEventReader(java.io.Reader reader, ReadWriteParameterMap parameters)`
    `NeXMLEventReader(javax.xml.stream.XMLEventReader xmlReader, ReadWriteParameterMap parameters)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected NeXMLReaderStreamDataProvider` | `createStreamDataProvider()` This method is called in the constructor of `AbstractEventReader` to initialize the stream data provider that will be returned by `AbstractEventReader.getStreamDataProvider()`.
    `protected void` | `fillMap()`
    `protected XMLElementReader<NeXMLReaderStreamDataProvider>` | `getElementReader(javax.xml.namespace.QName parentTag, javax.xml.namespace.QName elementTag, int eventType)`
    `java.lang.String` | `getFormatID()` Returns a string ID uniquely identifying the target format of this instance.
    `TokenTranslationStrategy` | `getTranslateTokens()`

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

      `close, createMetaXMLEventReader, createMetaXMLStreamReader, getElementReaderMap, getEncounteredTags, getNamespaceContext, getXMLReader, isAllowDefaultNamespace, parseQName, putElementReader, readNextEvent`

    - ### 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`

- - ### Constructor Detail

    - #### NeXMLEventReader

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

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

    - #### NeXMLEventReader

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

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

    - #### NeXMLEventReader

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

    - #### NeXMLEventReader

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

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

  - ### Method Detail

    - #### getFormatID

          public java.lang.String getFormatID()

      Description copied from interface: `JPhyloIOFormatSpecificObject`
      Returns a string ID uniquely identifying the target format of this instance. Additional information on the format can be retrieved by passing the returned ID to `JPhyloIOReaderWriterFactory.getFormatInfo(String)`.

      Third party developers that create readers or writers for additional formats must make sure to use a globally unique format ID. It is strongly recommended to use owned reverse domain names for this (e.g. `org.example.additionalformat`).

      Specified by:
        `getFormatID` in interface `JPhyloIOFormatSpecificObject`
      Returns:
        the ID of the target format of this instance
      See Also:
        `JPhyloIOReaderWriterFactory.getFormatInfo(String)`

    - #### createStreamDataProvider

          protected NeXMLReaderStreamDataProvider 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 `AbstractXMLEventReader<NeXMLReaderStreamDataProvider>`
      Returns:
        the stream data provider to be used with this instance

    - #### getTranslateTokens

          public TokenTranslationStrategy getTranslateTokens()

    - #### fillMap

          protected void fillMap()

      Specified by:
        `fillMap` in class `AbstractXMLEventReader<NeXMLReaderStreamDataProvider>`

    - #### getElementReader

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

      Overrides:
        `getElementReader` in class `AbstractXMLEventReader<NeXMLReaderStreamDataProvider>`