info.bioinfweb.jphyloio.utils

## Class JPhyloIOReadingUtils

- java.lang.Object
- - info.bioinfweb.jphyloio.utils.JPhyloIOReadingUtils

-     public class JPhyloIOReadingUtils
      extends java.lang.Object

  Provides tool methods to be used by application developers when implementing a reader class that processes events from an implementations of `JPhyloIOEventReader` and stores relevant content in the application business model.
  Since:
    0.0.0
  Author:
    Ben Stöver

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JPhyloIOReadingUtils()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.util.List<JPhyloIOEvent>` | `collectEvents(JPhyloIOEventReader reader, java.util.Set<EventType> types)` Reads all (remaining) events from the specified reader and adds events that have a type that is contained in the # specified set to the returned list.
    `static <E extends JPhyloIOEvent> java.util.List<E>` | `collectEvents(JPhyloIOEventReader reader, java.util.Set<EventType> types, java.lang.Class<E> instanceClass)` Reads all (remaining) events from the specified reader and adds events that implement the specified class and have a type that is contained in the specified set to the returned list.
    `static void` | `reachElementEnd(JPhyloIOEventReader reader)` Reads all events from the reader until one more end element than start elements is found.
    `static <O> O` | `readLiteralMetadataContentAsObject(JPhyloIOEventReader reader, java.lang.Class<O> objectClass)` Reads a subsequence from an JPhyloIO event stream modeling contents of a literal metadata element into an object of the specified class.
    `static java.lang.String` | `readLiteralMetadataContentAsString(JPhyloIOEventReader reader)` This convenience method calls `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)` internally and converts its content to a `String` if the builder is not `null`.
    `static java.lang.StringBuilder` | `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader reader)` Reads a subsequence from an JPhyloIO event stream modeling contents of a literal metadata element into a string builder.

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

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

- - ### Constructor Detail

    - #### JPhyloIOReadingUtils

          public JPhyloIOReadingUtils()

  - ### Method Detail

    - #### reachElementEnd

          public static void reachElementEnd(JPhyloIOEventReader reader)
                                      throws java.io.IOException

      Reads all events from the reader until one more end element than start elements is found.
      Parameters:
        `reader` - the JPhyloIO event reader providing the event stream
      Throws:
        `java.io.IOException` - if an I/O error occurs while reading from `reader`

    - #### readLiteralMetadataContentAsStringBuilder

          public static java.lang.StringBuilder readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader reader)
                                                                                   throws java.io.IOException

      Reads a subsequence from an JPhyloIO event stream modeling contents of a literal metadata element into a string builder. The string representation of the modeled object is returned, even if it is not an instance of `CharSequence`. Encountered comment events are skipped and ignored.

      This tool method can be called after a start event with the content type `EventContentType.LITERAL_META` was read from `reader` and will consume all following events including the respective end event with the type `EventContentType.LITERAL_META`. Note that this method may only be used if the sequence type of the literal metadata start event is `LiteralContentSequenceType.SIMPLE`.

      Large strings maybe split among multiple content events by JPhyloIO readers. (See the documentation of `LiteralMetadataContentEvent` for details.) A sequence of such events is concatenated into a single value returned by this method. Note that sequential reading of large strings that do not need to be in memory as a whole to be processed by the application is more efficient, if the application handles the content events directly. This method should be used with care if such cases are likely.

      Parameters:
        `reader` - the JPhyloIO event reader providing the event stream
      Returns:
        an instance of `StringBuilder` containing the string content or `null` if no content events were encountered before the literal metadata end event
      Throws:
        `java.io.IOException` - if an I/O error occurs while reading from `reader` or if another content event was encountered although sequence was declared to be terminated by the last event (The latter case would indicate an invalid event sequence produced by `reader`, which is not to expect from a well-tested reader. If you encounter such problems with a built-in reader from JPhyloIO, inform the developers.)
        `java.util.NoSuchElementException` - if the event stream ends before a literal metadata end event is encountered (This should not happen, if `reader` produces an event stream according to the grammar defined in the documentation of `JPhyloIOEventReader`.)
      See Also:
        `LiteralMetadataContentEvent`, `ObjectTranslator`, `readLiteralMetadataContentAsString(JPhyloIOEventReader)`, `readLiteralMetadataContentAsObject(JPhyloIOEventReader, Class)`

    - #### readLiteralMetadataContentAsString

          public static java.lang.String readLiteralMetadataContentAsString(JPhyloIOEventReader reader)
                                                                     throws java.io.IOException

      This convenience method calls `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)` internally and converts its content to a `String` if the builder is not `null`.
      Parameters:
        `reader` - the JPhyloIO event reader providing the event stream
      Returns:
        the string content or `null` if no content events were encountered before the literal metadata end event
      Throws:
        `java.io.IOException` - if an I/O error occurs while reading from `reader` or if another content event was encountered although sequence was declared to be terminated by the last event (See the documentation of `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)` for details.)
        `java.util.NoSuchElementException` - if the event stream ends before a literal metadata end event is encountered (See the documentation of `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)` for details.)
      See Also:
        `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)`

    - #### readLiteralMetadataContentAsObject

          public static <O> O readLiteralMetadataContentAsObject(JPhyloIOEventReader reader,
                                                                 java.lang.Class<O> objectClass)
                                                          throws java.io.IOException,
                                                                 java.lang.ClassCastException

      Reads a subsequence from an JPhyloIO event stream modeling contents of a literal metadata element into an object of the specified class. This is only possible if a single metadata content event containing an object value implementing the specified type is nested. Encountered comment events are skipped and ignored.

      This tool method can be called after a start event with the content type `EventContentType.LITERAL_META` was read from `reader` and will consume all following events including the respective end event with the type `EventContentType.LITERAL_META`. Note that this method may only be used if the sequence type of the literal metadata start event is `LiteralContentSequenceType.SIMPLE` and the specified type of the object value is expected.

      Note that this method is not able to read strings that are separated among multiple content events. `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)` or `readLiteralMetadataContentAsString(JPhyloIOEventReader)` should be used instead to read strings.

      It is beneficial in many cases to use a value for `objectClass` that is as general as possible. If e.g. a double value is expected, the expression

          double d = JPhyloIOReadingUtils.readLiteralMetadataContentAsObject(reader, Number.class).doubleValue();

      should be used instead of

          double d = JPhyloIOReadingUtils.readLiteralMetadataContentAsObject(reader, Double.class);

      This allows to read metadata declaring different numeric types into the `double`. Otherwise processing of metadata of e.g. the type `Float` or `Integer` would cause a `ClassCastException`. The same applies for all classes that have commons supertypes that would be sufficient for reading.

      Note that JPhyloIO readers will only produce content events with Java objects for which an appropriate `ObjectTranslator` instance is available. Custom object translators can be provided using the parameter `ReadWriteParameterNames.KEY_OBJECT_TRANSLATOR_FACTORY`.

      Parameters:
        `reader` - the JPhyloIO event reader providing the event stream
        `objectClass` - the type of object value to be read
      Returns:
        the object value or `null` if no content events were encountered before the literal metadata end event
      Throws:
        `java.io.IOException` - if an I/O error occurs while reading from `reader` or if more then one content event was encountered or if the encountered content event did not have an object value
        `java.lang.ClassCastException` - if the encountered object values does not implement `objectClass`
      See Also:
        `readLiteralMetadataContentAsStringBuilder(JPhyloIOEventReader)`, `ObjectTranslator`

    - #### collectEvents

          public static <E extends JPhyloIOEvent> java.util.List<E> collectEvents(JPhyloIOEventReader reader,
                                                                                  java.util.Set<EventType> types,
                                                                                  java.lang.Class<E> instanceClass)
                                                                           throws java.io.IOException

      Reads all (remaining) events from the specified reader and adds events that implement the specified class and have a type that is contained in the specified set to the returned list.

      Possible use cases could e.g. be to collect all alignment start events from a document to display a list of alignments contained in a file.

      Parameters:
        `reader` - the reader to read the events from
        `types` - a set of types to be collected
        `instanceClass` - the type that needs to be implemented by the collected event instances
      Returns:
        a list of collected events
      Throws:
        `java.io.IOException` - if an I/O error occurs while reading events from `reader`

    - #### collectEvents

          public static java.util.List<JPhyloIOEvent> collectEvents(JPhyloIOEventReader reader,
                                                                    java.util.Set<EventType> types)
                                                             throws java.io.IOException

      Reads all (remaining) events from the specified reader and adds events that have a type that is contained in the # specified set to the returned list.
      Parameters:
        `reader` - the reader to read the events from
        `types` - a set of types to be collected
      Returns:
        a list of collected events
      Throws:
        `java.io.IOException` - if an I/O error occurs while reading events from `reader`