info.bioinfweb.jphyloio.dataadapters.implementations.receivers

## Class BasicEventReceiver<P extends WriterStreamDataProvider<? extends AbstractEventWriter<P>>>

- java.lang.Object
- - info.bioinfweb.jphyloio.dataadapters.implementations.receivers.BasicEventReceiver<P>

- Type Parameters:
    `W` - the type of writer to write the data to (usually `Writer` or `XMLStreamWriter`)
  All Implemented Interfaces:
    JPhyloIOEventReceiver
  Direct Known Subclasses:
    AbstractSequenceContentReceiver, AbstractXMLDataReceiver, BasicTextCommentEventReceiver, NewickNodeEdgeEventReceiver

      public class BasicEventReceiver<P extends WriterStreamDataProvider<? extends AbstractEventWriter<P>>>
      extends java.lang.Object
      implements JPhyloIOEventReceiver

  Most event receivers will be inherited from this class. It implements basic shared functionalities mainly for handling metadata and comments. The default behavior of some methods may need to be overwritten by inherited classes.
  Author:
    Ben Stöver

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BasicEventReceiver(P streamDataProvider, ReadWriteParameterMap parameterMap)` Creates a new instance of this class.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(JPhyloIOEvent event)` Adds a new event to the sequence written to this receiver.
    `protected void` | `addIgnoredComments(long addend)`
    `protected void` | `addIgnoredLiteralMetadata(long addend)`
    `protected void` | `addIgnoredResourceMetadata(long addend)`
    `void` | `addIgnoreLogMessage(ApplicationLogger logger, java.lang.String objectName, java.lang.String formatName)`
    `boolean` | `didIgnoreComments()`
    `boolean` | `didIgnoreLiteralMetadata()`
    `boolean` | `didIgnoreMetadata()`
    `boolean` | `didIgnoreResourceMetadata()`
    `protected boolean` | `doAdd(JPhyloIOEvent event)` This method is called internally by `add(JPhyloIOEvent)` to process events that do not model metadata or comments.
    `long` | `getIgnoredComments()`
    `long` | `getIgnoredLiteralMetadata()`
    `long` | `getIgnoredMetadata()`
    `long` | `getIgnoredResourceMetadata()`
    `ApplicationLogger` | `getLogger()`
    `ReadWriteParameterMap` | `getParameterMap()`
    `JPhyloIOEvent` | `getParentEvent()`
    `java.util.Stack<JPhyloIOEvent>` | `getParentEvents()`
    `P` | `getStreamDataProvider()`
    `protected void` | `handleComment(CommentEvent event)`
    `protected void` | `handleLiteralContentMeta(LiteralMetadataContentEvent event)`
    `protected void` | `handleLiteralMetaStart(LiteralMetadataEvent event)`
    `protected void` | `handleMetaEndEvent(JPhyloIOEvent event)`
    `protected void` | `handleResourceMetaStart(ResourceMetadataEvent event)`
    `boolean` | `isInComment()` Determines whether the last event was a continued comment event and the next event is expected to be the continuing comment event.

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

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

- - ### Constructor Detail

    - #### BasicEventReceiver

          public BasicEventReceiver(P streamDataProvider,
                                    ReadWriteParameterMap parameterMap)

      Creates a new instance of this class.
      Parameters:
        `writer` - the writer to write data to (e.g. an instance of `Writer` or `XMLStreamWriter`)
        `parameterMap` - the parameter map of the event writer that will be using this receiver instance

  - ### Method Detail

    - #### getParameterMap

          public ReadWriteParameterMap getParameterMap()

    - #### getStreamDataProvider

          public P getStreamDataProvider()

    - #### getLogger

          public ApplicationLogger getLogger()

    - #### getParentEvents

          public java.util.Stack<JPhyloIOEvent> getParentEvents()

    - #### getParentEvent

          public JPhyloIOEvent getParentEvent()

    - #### isInComment

          public boolean isInComment()

      Determines whether the last event was a continued comment event and the next event is expected to be the continuing comment event. This property is updated after `handleComment(CommentEvent)` was called.
      Returns:
        `true` if the last event was a continued comment event, `false` otherwise

    - #### getIgnoredComments

          public long getIgnoredComments()

    - #### didIgnoreComments

          public boolean didIgnoreComments()

    - #### addIgnoredComments

          protected void addIgnoredComments(long addend)

    - #### getIgnoredLiteralMetadata

          public long getIgnoredLiteralMetadata()

    - #### didIgnoreLiteralMetadata

          public boolean didIgnoreLiteralMetadata()

    - #### addIgnoredLiteralMetadata

          protected void addIgnoredLiteralMetadata(long addend)

    - #### getIgnoredResourceMetadata

          public long getIgnoredResourceMetadata()

    - #### didIgnoreResourceMetadata

          public boolean didIgnoreResourceMetadata()

    - #### didIgnoreMetadata

          public boolean didIgnoreMetadata()

    - #### getIgnoredMetadata

          public long getIgnoredMetadata()

    - #### addIgnoredResourceMetadata

          protected void addIgnoredResourceMetadata(long addend)

    - #### handleLiteralMetaStart

          protected void handleLiteralMetaStart(LiteralMetadataEvent event)
                                         throws java.io.IOException,
                                                javax.xml.stream.XMLStreamException

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

    - #### handleLiteralContentMeta

          protected void handleLiteralContentMeta(LiteralMetadataContentEvent event)
                                           throws java.io.IOException,
                                                  javax.xml.stream.XMLStreamException

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

    - #### handleResourceMetaStart

          protected void handleResourceMetaStart(ResourceMetadataEvent event)
                                          throws java.io.IOException,
                                                 javax.xml.stream.XMLStreamException

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

    - #### handleComment

          protected void handleComment(CommentEvent event)
                                throws java.io.IOException,
                                       javax.xml.stream.XMLStreamException

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

    - #### handleMetaEndEvent

          protected void handleMetaEndEvent(JPhyloIOEvent event)
                                     throws java.io.IOException,
                                            javax.xml.stream.XMLStreamException

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

    - #### doAdd

          protected boolean doAdd(JPhyloIOEvent event)
                           throws java.io.IOException,
                                  javax.xml.stream.XMLStreamException

      This method is called internally by `add(JPhyloIOEvent)` to process events that do not model metadata or comments. (Such events are treated by the according special methods of this class).

      This default implementation just throws an `IllegalEventException`. Inherited classes that need to support other events then these modeling metadata or comments, must overwrite this method.

      Parameters:
        `event` - the event to be processed
      Returns:
        `true` if more events can be written to this acceptor or `false` if writing should be aborted
      Throws:
        `IllegalEventException` - if the specified event is illegal in this acceptor in general or at the current position in the sequence
        `java.lang.ClassCastException` - if an event object was specified that is not an instance of a class associated with its type as document in `EventContentType`
        `java.io.IOException` - if an I/O error occurs when writing to the underlying stream
        `javax.xml.stream.XMLStreamException` - if an XML stream error occurs when writing to the underlying stream

    - #### add

          public boolean add(JPhyloIOEvent event)
                      throws java.io.IOException

      Description copied from interface: `JPhyloIOEventReceiver`
      Adds a new event to the sequence written to this receiver.

      Note that this acceptor indicates whether writing events shall be aborted by its return value. This maybe the case, if the writer providing this acceptor was seeking for a specific piece of information and is (currently) not interested in the remaining events. Data adapter implemented by applications should consider the return value to allow saving runtime. If event writing goes on after `false` was returned, subsequent events will be ignored but no exception will be thrown.

      Conversely, a return value of `true` does not necessarily mean that more events are expected in order to complete the expected information.

      Exceptions thrown by this instance should not be caught within any of the `write*()` methods in application implementations of any data adapter (e.g. `MatrixDataAdapter.writeSequencePartContentData(ReadWriteParameterMap, JPhyloIOEventReceiver, String, long, long)`. They will be forwarded by the calling writer and can be handled by the application when `JPhyloIOEventWriter.writeDocument(DocumentDataAdapter, Writer, ReadWriteParameterMap)` (or one of the other overloaded versions) are called.

      Specified by:
        `add` in interface `JPhyloIOEventReceiver`
      Parameters:
        `event` - the event to be add
      Returns:
        `true` if more events can be written to this acceptor or `false` if writing should be aborted
      Throws:
        `java.io.IOException` - if an I/O error occurs when writing to the underlying stream

    - #### addIgnoreLogMessage

          public void addIgnoreLogMessage(ApplicationLogger logger,
                                          java.lang.String objectName,
                                          java.lang.String formatName)