info.bioinfweb.jphyloio

## Interface JPhyloIOEventReader

- All Superinterfaces:
    JPhyloIOFormatSpecificObject
  All Known Subinterfaces:
    JPhyloIOXMLEventReader
  All Known Implementing Classes:
    AbstractEventReader, AbstractPhylipEventReader, AbstractTextEventReader, AbstractXMLEventReader, FASTAEventReader, MEGAEventReader, NewickEventReader, NeXMLEventReader, NexusEventReader, PDEEventReader, PhylipEventReader, PhyloXMLEventReader, SequentialPhylipEventReader, XTGEventReader

      public interface JPhyloIOEventReader
      extends JPhyloIOFormatSpecificObject

  This is main JPhyloIO interface to be implemented by all format specific event readers.

  Events representing the content of a document can be processed by subsequent calls of `next()`. The event sequence generated by implementing event readers must match the following EBNF. All events are objects that implement `JPhyloIOEvent` and the type of data they represent is determined by their `EventContentType`, which is shown in this grammar.

  Some events enclose a subsequence of the event stream and are therefore separated into a `START` and an `END` version. Between such two events other events may be present that model nested content (e.g. sequences between an matrix `START` and `END` event). Other events that may not contain any nested content only occur in a single `SOLE` version. Which is type of event is found is determined by its `EventTopologyType`.

  ### Event grammar

       Document = "DOCUMENT.START", {DocumentContent,} "DOCUMENT.END";
       DocumentContent = OTUList | Matrix | TreeNetworkGroup | OTUSet | CharacterSetPart | TreeNetworkSet | MetaInformation;

       OTUList = "OTUS.START", {OTUListContent,} {OTUSet,} "OTUS.END";
       OTUListContent = OTU | MetaInformation;
       OTU = "OTU.START", {MetaInformation,} "OTU.END";
       OTUSet = "OTU_SET.START", {SetContent,} "OTU_SET.END";

       Matrix = "ALIGNMENT.START", {MatrixContent,} "ALIGNMENT.END";
       MatrixContent = CharacterDefinition | TokenSetDefinition | SequencePart | CharacterSetPart | SequenceSet | MetaInformation;

       CharacterDefinition = "CHARACTER_DEFINITION.START" {MetaInformation,} "CHARACTER_DEFINITION.END";
       SequenceSet = "SEQUENCE_SET.START" {SetContent,} "SEQUENCE_SET.END";

       TokenSetDefinition = "TOKEN_SET_DEFINITION.START", {TokenSetDefinitionContent,} "TOKEN_SET_DEFINITION.END";
       TokenSetDefinitionContent = "CHARACTER_SET_INTERVAL.SOLE" | SingleTokenDefinition | MetaInformation;
       SingleTokenDefinition = "SINGLE_TOKEN_DEFINITION.START", {MetaInformation,} "SINGLE_TOKEN_DEFINITION.END";

       SequencePart = "SEQUENCE.START", {SequencePartContent,} "SEQUENCE.END";
       SequencePartContent = "SEQUENCE_TOKENS.SOLE" | SingleSequenceToken | MetaInformation;
       SingleSequenceToken = "SINGLE_SEQUENCE_TOKEN.START", {MetaInformation,} "SINGLE_SEQUENCE_TOKEN.END";

       CharacterSetPart = "CHARACTER_SET.START", {CharacterSetPartContent,} "CHARACTER_SET.END";
       CharacterSetPartContent = "CHARACTER_SET_INTERVAL.SOLE" | SetContent;  (* In character sets only references to other character sets (and not single character definitions) are using "SET_ELEMENT.SOLE". *)

       TreeNetworkGroup = "TREE_NETWORK_GROUP.START", {TreeNetworkGroupContent,} "TREE_NETWORK_GROUP.END";
       TreeNetworkGroupContent = Tree | Network | TreeNetworkSet;
       Tree = "TREE.START", {TreeOrNetworkContent,} ["ROOT_EDGE.START",] {TreeOrNetworkContent,} {NodeEdgeSet,} "TREE.END";
       Network = "NETWORK.START", {TreeOrNetworkContent,} {NodeEdgeSet,} "NETWORK.END";
       TreeOrNetworkContent = Node | Edge | MetaInformation;
       Node = "NODE.START", {MetaInformation,} "NODE.END";
       Edge = "EDGE.START", {MetaInformation,} "EDGE.END";

       TreeNetworkSet = "TREE_NETWORK_SET.START" {SetContent,} "TREE_NETWORK_SET.END";
       NodeEdgeSet = "NODE_EDGE_SET.START" {SetContent,} "NODE_EDGE_SET.END";

       SetContent = "SET_ELEMENT.SOLE" | MetaInformation;  (* Single elements and other sets of the same type can be linked using "SET_ELEMENT.SOLE". *)

       MetaInformation = ResourceMeta | LiteralMeta;
       ResourceMeta = "RESOURCE_META.START", {MetaInformation,} "RESOURCE_META.END";
       LiteralMeta = "LITERAL_META.START", {"LITERAL_META_CONTENT.SOLE",} "LITERAL_META.END";

  Additionally `CommentEvent`s (`"COMMENT.SOLE"`) may occur at any position in the stream, which is not shown in the grammar for greater clarity.

  Note that one event may only reference other events that have been fired before, although this is not directly expressed by the grammar in all cases. (Examples are edges referencing nodes or sequences referencing OTUs.)

  The documentation of `EventContentType` contains information on which event classes are used for which event type.

  Author:
    Ben Stöver
  See Also:
    `EventContentType`, `EventTopologyType`, `JPhyloIOEvent`, `JPhyloIOEventWriter`

- - ### Method Summary

    All Methods Instance Methods Abstract 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).
    `JPhyloIOEvent` | `getLastNonCommentEvent()` Returns the last event that has been returned by previous calls of `#readNextEvent()` that was not a comment event.
    `ParentEventInformation` | `getParentInformation()` The returned object provides information on the start events fired by this reader until now.
    `JPhyloIOEvent` | `getPreviousEvent()` Returns the event that was returned with the last call of `next()`.
    `boolean` | `hasNextEvent()` Checks if another event could be parsed from the underlying document.
    `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 `next()` without moving forward.
    `void` | `removeEventListener(JPhyloIOEventListener listener)` Removes a `JPhyloIOEventListener` from the reader.

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

      `getFormatID`

- - ### Method Detail

    - #### getParentInformation

          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.
      Returns:
        the parent information object

    - #### hasNextEvent

          boolean hasNextEvent()
                        throws java.io.IOException

      Checks if another event could be parsed from the underlying document.
      Returns:
        `true` if another event is waiting, `false` if the end of the underlying document was reached
      Throws:
        `java.io.IOException`

    - #### next

          JPhyloIOEvent next()
                      throws java.io.IOException

      Returns the next event from the underlying document and moves one step forward.
      Returns:
        the next event object
      Throws:
        `java.util.NoSuchElementException` - if the end of the document has been reached with the previous call of this method
        `java.io.IOException` - Implementing classes might throw additional exceptions

    - #### nextOfType

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

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

          JPhyloIOEvent peek()
                      throws java.io.IOException

      Returns the event from the underlying document that will be returned in the next call of `next()` without moving forward.
      Returns:
        the next event object
      Throws:
        `java.util.NoSuchElementException` - if the end of the document has been reached with the previous call of this method
        `java.io.IOException` - Implementing classes might throw additional exceptions

    - #### getPreviousEvent

          JPhyloIOEvent getPreviousEvent()

      Returns the event that was returned with the last call of `next()`.

      Note that calling this method will not move the cursor, but will only return the last event. Subsequent calls would therefore always return the same event. (This method is different from e.g. `ListIterator.previous()`.)

      Returns:
        the last event or `null` if no event was returned yet
      See Also:
        `getLastNonCommentEvent()`

    - #### getLastNonCommentEvent

          JPhyloIOEvent getLastNonCommentEvent()

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

    - #### close

          void close()
              throws java.io.IOException

      Closes the underlying document source (usually a stream).
      Throws:
        `java.io.IOException` - Implementing classes might throw different types of exceptions if the stream cannot be closed properly

    - #### addEventListener

          void addEventListener(JPhyloIOEventListener listener)

      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.

      Parameters:
        `listener` - the listener that shall be added

    - #### removeEventListener

          void removeEventListener(JPhyloIOEventListener listener)

      Removes a `JPhyloIOEventListener` from the reader.
      Parameters:
        `listener` - the listener that shall be removed