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 CommentEvents ("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

Interface JPhyloIOEventReader

Event grammar

Method Summary

Methods inherited from interface info.bioinfweb.jphyloio.JPhyloIOFormatSpecificObject

Method Detail

getParentInformation

hasNextEvent

next

nextOfType

peek

getPreviousEvent

getLastNonCommentEvent

close

addEventListener

removeEventListener