info.bioinfweb.jphyloio

## Class AbstractEventReader<P extends ReaderStreamDataProvider<? extends AbstractEventReader<P>>>

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

- All Implemented Interfaces:
    JPhyloIOEventReader, JPhyloIOFormatSpecificObject, ReadWriteConstants
  Direct Known Subclasses:
    AbstractTextEventReader, AbstractXMLEventReader

      public abstract class AbstractEventReader<P extends ReaderStreamDataProvider<? extends AbstractEventReader<P>>>
      extends java.lang.Object
      implements JPhyloIOEventReader, ReadWriteConstants

  Basic implementation for event readers in PhyloIO.
  Author:
    Ben Stöver

- - ### Field Summary

    - ### 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
    `AbstractEventReader(ReadWriteParameterMap parameters, java.lang.String matchToken)`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addEventListener(JPhyloIOEventListener listener)` Adds a `JPhyloIOEventListener` to the reader that will be informed on all events generated by this reader (e.g.
    `void` | `close()` Closes the underlying document source (usually a stream).
    `protected P` | `createStreamDataProvider()` This method is called in the constructor of `AbstractEventReader` to initialize the stream data provider that will be returned by `getStreamDataProvider()`.
    `protected void` | `fireEvent(JPhyloIOEvent event)`
    `protected java.util.Collection<JPhyloIOEvent>` | `getCurrentEventCollection()` Returns the event collection that is currently used to take up new events.
    `protected LongIDManager` | `getIDManager()`
    `JPhyloIOEvent` | `getLastNonCommentEvent()` Returns the last event that has been returned by previous calls of `readNextEvent()` that was not a comment event.
    `protected ReadWriteParameterMap` | `getParameters()`
    `ParentEventInformation` | `getParentInformation()` The returned object provides information on the start events fired by this reader until now.
    `JPhyloIOEvent` | `getPreviousEvent()` Returns the event that has been returned by the previous call of `readNextEvent()`.
    `protected SequenceTokensEventManager` | `getSequenceTokensEventManager()` Returns the manager object used by this instance to create `SequenceTokensEvent`s.
    `protected P` | `getStreamDataProvider()`
    `protected java.util.Queue<JPhyloIOEvent>` | `getUpcomingEvents()` Returns the queue to store events in, that shall be returned by upcoming calls of `next()`.
    `boolean` | `hasNextEvent()` Checks if another event could be parsed from the underlying document.
    `protected boolean` | `hasSpecialEventCollection()` Determines whether the current event collection is different from the queue of upcoming events.
    `protected boolean` | `isBeforeFirstAccess()` Indicates whether there have been any previous calls of `readNextEvent()` since the last call of `#reset()`.
    `JPhyloIOEvent` | `next()` Returns the next event from the underlying document and moves one step forward.
    `JPhyloIOEvent` | `nextOfType(java.util.Set<EventType> types)` Reads elements from the underlying stream until one of the specified is found or the end of the document is reached.
    `JPhyloIOEvent` | `peek()` Returns the event from the underlying document that will be returned in the next call of `JPhyloIOEventReader.next()` without moving forward.
    `protected abstract 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.
    `void` | `removeEventListener(JPhyloIOEventListener listener)` Removes a `JPhyloIOEventListener` from the reader.
    `protected java.util.Collection<JPhyloIOEvent>` | `resetCurrentEventCollection()` Removes the event collection at the top of the eventCollections stack and returns it.
    `protected java.util.Collection<JPhyloIOEvent>` | `setCurrentEventCollection(java.util.Collection<JPhyloIOEvent> newCollection)` Adds a new current event collection to the stack.

    - ### 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.JPhyloIOFormatSpecificObject

      `getFormatID`

- - ### Constructor Detail

    - #### AbstractEventReader

          public AbstractEventReader(ReadWriteParameterMap parameters,
                                     java.lang.String matchToken)

  - ### Method Detail

    - #### getParentInformation

          public ParentEventInformation getParentInformation()

      The returned object provides information on the start events fired by this reader until now. It allows applications to determine information on the nesting of the current event.
      Specified by:
        `getParentInformation` in interface `JPhyloIOEventReader`
      Returns:
        the parent information object

    - #### createStreamDataProvider

          protected P createStreamDataProvider()

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

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

      Returns:
        the stream data provider to be used with this instance

    - #### getStreamDataProvider

          protected P getStreamDataProvider()

    - #### getParameters

          protected ReadWriteParameterMap getParameters()

    - #### resetCurrentEventCollection

          protected java.util.Collection<JPhyloIOEvent> resetCurrentEventCollection()

      Removes the event collection at the top of the eventCollections stack and returns it.
      Returns:
        the removed event collection

    - #### setCurrentEventCollection

          protected java.util.Collection<JPhyloIOEvent> setCurrentEventCollection(java.util.Collection<JPhyloIOEvent> newCollection)

      Adds a new current event collection to the stack.
      Parameters:
        `newCollection` - the new collection to take up new events from now on
      Returns:
        the event collection that was previously at the top of the stack
      Throws:
        `java.lang.NullPointerException` - if `newCollection` is `null`

    - #### getCurrentEventCollection

          protected java.util.Collection<JPhyloIOEvent> getCurrentEventCollection()

      Returns the event collection that is currently used to take up new events.
      Returns:
        the current event collection

    - #### hasSpecialEventCollection

          protected boolean hasSpecialEventCollection()

      Determines whether the current event collection is different from the queue of upcoming events.
      Returns:
        `false` if `getCurrentEventCollection()` returns the same instance as `getUpcomingEvents()` or `true` otherwise

    - #### getUpcomingEvents

          protected java.util.Queue<JPhyloIOEvent> getUpcomingEvents()

      Returns the queue to store events in, that shall be returned by upcoming calls of `next()`.

      Note that new events should generally be added to `getCurrentEventCollection()` instead.

      Returns:
        the queue of upcoming events

    - #### getIDManager

          protected LongIDManager getIDManager()

    - #### getSequenceTokensEventManager

          protected SequenceTokensEventManager getSequenceTokensEventManager()

      Returns the manager object used by this instance to create `SequenceTokensEvent`s. Such events should always be created using the returned object by inherited classes and never directly.
      Returns:
        the character event manager used by this instance (never `null`)

    - #### fireEvent

          protected void fireEvent(JPhyloIOEvent event)
                            throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### getPreviousEvent

          public JPhyloIOEvent getPreviousEvent()

      Returns the event that has been returned by the previous call of `readNextEvent()`.
      Specified by:
        `getPreviousEvent` in interface `JPhyloIOEventReader`
      Returns:
        the previous event or `null` if there was no previous call of `readNextEvent()`
      See Also:
        `JPhyloIOEventReader.getLastNonCommentEvent()`

    - #### getLastNonCommentEvent

          public JPhyloIOEvent getLastNonCommentEvent()

      Returns the last event that has been returned by previous calls of `readNextEvent()` that was not a comment event.
      Specified by:
        `getLastNonCommentEvent` in interface `JPhyloIOEventReader`
      Returns:
        the last non-comment event or `null` if no non-comment event was returned until now
      See Also:
        `JPhyloIOEventReader.getPreviousEvent()`

    - #### isBeforeFirstAccess

          protected boolean isBeforeFirstAccess()

      Indicates whether there have been any previous calls of `readNextEvent()` since the last call of `#reset()`.

      This method in meant for internal use in `readNextEvent()`.

      Returns:
        `true` if there were no previous calls, `false` otherwise

    - #### hasNextEvent

          public boolean hasNextEvent()
                               throws java.io.IOException

      Description copied from interface: `JPhyloIOEventReader`
      Checks if another event could be parsed from the underlying document.
      Specified by:
        `hasNextEvent` in interface `JPhyloIOEventReader`
      Returns:
        `true` if another event is waiting, `false` if the end of the underlying document was reached
      Throws:
        `java.io.IOException`

    - #### next

          public JPhyloIOEvent next()
                             throws java.io.IOException

      Description copied from interface: `JPhyloIOEventReader`
      Returns the next event from the underlying document and moves one step forward.
      Specified by:
        `next` in interface `JPhyloIOEventReader`
      Returns:
        the next event object
      Throws:
        `java.io.IOException` - Implementing classes might throw additional exceptions

    - #### nextOfType

          public JPhyloIOEvent nextOfType(java.util.Set<EventType> types)
                                   throws java.io.IOException

      Description copied from interface: `JPhyloIOEventReader`
      Reads elements from the underlying stream until one of the specified is found or the end of the document is reached. All elements of other types are consumed and ignored.
      Specified by:
        `nextOfType` in interface `JPhyloIOEventReader`
      Parameters:
        `types` - a set of valid types to be returned
      Returns:
        the next element of the specified type or `null` if end of the file was reached before an according element was found
      Throws:
        `java.io.IOException` - Implementing classes might throw additional exceptions

    - #### peek

          public JPhyloIOEvent peek()
                             throws java.io.IOException

      Description copied from interface: `JPhyloIOEventReader`
      Returns the event from the underlying document that will be returned in the next call of `JPhyloIOEventReader.next()` without moving forward.
      Specified by:
        `peek` in interface `JPhyloIOEventReader`
      Returns:
        the next event object
      Throws:
        `java.io.IOException` - Implementing classes might throw additional exceptions

    - #### addEventListener

          public void addEventListener(JPhyloIOEventListener listener)

      Description copied from interface: `JPhyloIOEventReader`
      Adds a `JPhyloIOEventListener` to the reader that will be informed on all events generated by this reader (e.g. when its `#next()` method is called).

      Registering listeners here allows to combine pull- and push-parsing in a single implementation. Note that `EventForwarder` will usually be more useful for sole push-parsing implementations.

      Internal tool classes may also use this method to listen to events.

      Specified by:
        `addEventListener` in interface `JPhyloIOEventReader`
      Parameters:
        `listener` - the listener that shall be added

    - #### removeEventListener

          public void removeEventListener(JPhyloIOEventListener listener)

      Description copied from interface: `JPhyloIOEventReader`
      Removes a `JPhyloIOEventListener` from the reader.
      Specified by:
        `removeEventListener` in interface `JPhyloIOEventReader`
      Parameters:
        `listener` - the listener that shall be removed

    - #### readNextEvent

          protected abstract void readNextEvent()
                                         throws java.io.IOException

      Method to be implemented be inherited classes that adds at least one additional event (determined from the underlying data source) to the event queue.
      Throws:
        `java.io.IOException`

    - #### 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`
      Throws:
        `java.io.IOException` - Implementing classes might throw different types of exceptions if the stream cannot be closed properly