info.bioinfweb.jphyloio.factory

## Class JPhyloIOReaderWriterFactory

- java.lang.Object
- - info.bioinfweb.jphyloio.factory.JPhyloIOReaderWriterFactory

- All Implemented Interfaces:
    JPhyloIOFormatIDs

      public class JPhyloIOReaderWriterFactory
      extends java.lang.Object
      implements JPhyloIOFormatIDs

  Factory to create instances of JPhyloIO event readers and writers as well as `JPhyloIOFormatInfo` instances.

  It provides methods to create instances for a specific format, which is identified by its format ID, such as `getFormatInfo(String)`, `getWriter(String)` and different versions of `getReader()`. Format IDs are defined in `JPhyloIOFormatIDs`.

  Additionally this class allows to guess a format from the data using the available `guessFormat()` or `guessFormat()` methods. This is useful if an application user shall be able to load a file in any supported format without explicitly specifying the format.

  To be able to guess the format, a certain amount of the data to be read needs to be buffered. The buffer size may be specified using `setReadAheadLimit(int)`. The default value (`DEFAULT_READ_AHEAD_LIMIT``=` 8192 bytes) should be sufficient in most cases. An increase maybe necessary if unusual files (e.g. XML files with very long header information - such as `ENTITY` declarations - in front of the root tag) are expected.

  The following examples shows how to obtain a reader for a file with an unknown format:

       JPhyloIOEventReader reader = factory.guessReader(new File("path/to/file"), new ReadWriteParameterMap());
       if (reader != null) {
         // read file
       }
       else {
         System.out.println("The format of the specified file is not supported.");
       }

  Internally this instance uses a map from the format IDs to instances of `SingleReaderWriterFactory` to create reader and writer instances or guess formats. Third party readers and writers can be handled by this factory, if according single format factory instances are specified using `addFactory(SingleReaderWriterFactory)`.
  Since:
    0.0.0
  Author:
    Ben Stöver
  See Also:
    `JPhyloIOEventReader`, `JPhyloIOEventWriter`, `JPhyloIOFormatIDs`, `JPhyloIOFormatInfo`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_READ_AHEAD_LIMIT` The number of bytes that are buffered by methods of this factory to determine the format from an input stream.

    - ### Fields inherited from interface info.bioinfweb.jphyloio.formats.JPhyloIOFormatIDs

      `FASTA_FORMAT_ID, FORMAT_ID_PREFIX, MEGA_FORMAT_ID, NEWICK_FORMAT_ID, NEXML_FORMAT_ID, NEXUS_FORMAT_ID, PDE_FORMAT_ID, PHYLIP_FORMAT_ID, PHYLOXML_FORMAT_ID, SEQUENTIAL_PHYLIP_FORMAT_ID, XTG_FORMAT_ID`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JPhyloIOReaderWriterFactory()` Returns a new instance of this class, which supports all build-in readers and writers of JPhyloIO with a buffer size as defined by `DEFAULT_READ_AHEAD_LIMIT`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `SingleReaderWriterFactory` | `addFactory(SingleReaderWriterFactory factory)` Allows to add additional or replace existing single format factories to be used by this instance.
    `java.util.Set<java.lang.String>` | `getFormatIDsSet()` Returns the set of IDs of formats that are currently supported by this factory.
    `JPhyloIOFormatInfo` | `getFormatInfo(java.lang.String formatID)` Returns an information object for the specified format.
    `int` | `getReadAheadLimit()` Returns the maximal number of bytes this factory will read to determine the format of an input in the `#guess*()` methods.
    `JPhyloIOEventReader` | `getReader(java.lang.String formatID, java.io.File file, ReadWriteParameterMap parameters)`
    `JPhyloIOEventReader` | `getReader(java.lang.String formatID, java.io.InputStream stream, ReadWriteParameterMap parameters)`
    `JPhyloIOEventReader` | `getReader(java.lang.String formatID, java.io.Reader reader, ReadWriteParameterMap parameters)`
    `JPhyloIOEventWriter` | `getWriter(java.lang.String formatID)`
    `java.lang.String` | `guessFormat(java.io.File file)` Tries to determine the format of the contents of the specified file by examining at its beginning (e.g.
    `java.lang.String` | `guessFormat(java.io.File file, ReadWriteParameterMap parameters)` Tries to determine the format of the contents of the specified file by examining at its beginning (e.g.
    `java.lang.String` | `guessFormat(java.io.InputStream stream)` Tries to determine the format of the contents of the specified reader by examining at its beginning (e.g.
    `java.lang.String` | `guessFormat(java.io.InputStream stream, ReadWriteParameterMap parameters)` Tries to determine the format of the contents of the specified input stream by examining at its beginning (e.g.
    `java.lang.String` | `guessFormat(java.io.Reader reader)` Tries to determine the format of the contents of the specified reader by examining at its beginning (e.g.
    `java.lang.String` | `guessFormat(java.io.Reader reader, ReadWriteParameterMap parameters)` Tries to determine the format of the contents of the specified reader by examining at its beginning (e.g.
    `JPhyloIOEventReader` | `guessReader(java.io.File file, ReadWriteParameterMap parameters)` Tries to determine the format of the contents of the specified file as described in the documentation of `guessFormat(File)` and than creates a reader for the according format from that stream.
    `JPhyloIOEventReader` | `guessReader(java.io.InputStream stream, ReadWriteParameterMap parameters)` Tries to determine the format of the contents of the specified input stream as described in the documentation of `guessFormat(InputStream)`, resets the input stream and than creates a reader for the according format from that stream.
    `void` | `removeAllFactories()` Removes all single format factories from the internal map of this instance.
    `void` | `setReadAheadLimit(int readAheadLimit)` Allows to specify the maximal number of bytes this factory will read to determine the format of an input in the `#guess*()` methods.

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

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

- - ### Field Detail

    - #### DEFAULT_READ_AHEAD_LIMIT

          public static final int DEFAULT_READ_AHEAD_LIMIT

      The number of bytes that are buffered by methods of this factory to determine the format from an input stream.
      See Also:
        `setReadAheadLimit(int)`, Constant Field Values

  - ### Constructor Detail

    - #### JPhyloIOReaderWriterFactory

          public JPhyloIOReaderWriterFactory()

      Returns a new instance of this class, which supports all build-in readers and writers of JPhyloIO with a buffer size as defined by `DEFAULT_READ_AHEAD_LIMIT`.

  - ### Method Detail

    - #### addFactory

          public SingleReaderWriterFactory addFactory(SingleReaderWriterFactory factory)

      Allows to add additional or replace existing single format factories to be used by this instance. Using this method will only be necessary, if third party readers or writers shall be created by this instance.
      Parameters:
        `factory` - the single format factory object to be add to the internal map of this factory instance
      Returns:
        the previous value associated with the format ID of the specified factory, or `null` if there was no mapping for that format ID
      Since:
        0.1.0

    - #### removeAllFactories

          public void removeAllFactories()

      Removes all single format factories from the internal map of this instance. After calling this method, no format will be supported anymore by this instance until `addFactory(SingleReaderWriterFactory)` is called. If all build-in readers and writers of JPhyloIO shall be supported, using this method will be unnecessary.
      Since:
        0.1.0

    - #### getReadAheadLimit

          public int getReadAheadLimit()

      Returns the maximal number of bytes this factory will read to determine the format of an input in the `#guess*()` methods.

      This method is thread save a secured with an `ReadWriteLock` together with `setReadAheadLimit(int)`.

      Returns:
        the current read ahead limit

    - #### setReadAheadLimit

          public void setReadAheadLimit(int readAheadLimit)

      Allows to specify the maximal number of bytes this factory will read to determine the format of an input in the `#guess*()` methods.

      This method is thread save a secured with an `ReadWriteLock` together with `getReadAheadLimit()`.

      Parameters:
        `readAheadLimit` - the new read ahead limit

    - #### getFormatIDsSet

          public java.util.Set<java.lang.String> getFormatIDsSet()

      Returns the set of IDs of formats that are currently supported by this factory.
      Returns:
        an unmodifiable set of format IDs
      Since:
        0.1.0

    - #### guessFormat

          public java.lang.String guessFormat(java.io.File file,
                                              ReadWriteParameterMap parameters)
                                       throws java.lang.Exception

      Tries to determine the format of the contents of the specified file by examining at its beginning (e.g. the root tag in XML formats). The format is determined by subsequent calls of `SingleReaderWriterFactory.checkFormat(Reader, ReadWriteParameterMap)` until a matching factory is found.

      The parameter map is only necessary for formats that are so variable that parameter values are needed to determine how a valid input would look like. That is currently not the case for any format supported in JPhyloIO, but may be necessary for third parts format-specific factories used in this instance. (Refer to the documentation of third party format-specific factories for details.) In most cases the convenience method `guessFormat(File)` will be sufficient.

      Note that in contrast to `guessReader(File, ReadWriteParameterMap)`, this method does not support GZIPed inputs.

      Parameters:
        `reader` - the reader providing the contents
        `parameters` - the parameter map containing parameters for the JPhyloIO event reader that would be used with `reader`
      Returns:
        the ID of the determined format or `null` if no supported format seems to be matching the contents
      Throws:
        `java.lang.Exception` - if the underlying format specific factory throws an exception when testing the stream (e.g. because of an IO error)
      See Also:
        `JPhyloIOFormatIDs`, `guessReader(File, ReadWriteParameterMap)`

    - #### guessFormat

          public java.lang.String guessFormat(java.io.File file)
                                       throws java.lang.Exception

      Tries to determine the format of the contents of the specified file by examining at its beginning (e.g. the root tag in XML formats). The format is determined by subsequent calls of `SingleReaderWriterFactory.checkFormat(Reader, ReadWriteParameterMap)` until a matching factory is found.

      It uses an empty parameter map that is passed to the internal calls of `SingleReaderWriterFactory.checkFormat(Reader, ReadWriteParameterMap)`. Use `guessFormat(File, ReadWriteParameterMap)` if parameters are necessary to determine the format correctly.

      Note that in contrast to `guessReader(File, ReadWriteParameterMap)`, this method does not support GZIPed inputs.

      Parameters:
        `reader` - the reader providing the contents
      Returns:
        the ID of the determined format or `null` if no supported format seems to be matching the contents
      Throws:
        `java.lang.Exception` - if the underlying format specific factory throws an exception when testing the stream (e.g. because of an IO error)
      See Also:
        `JPhyloIOFormatIDs`, `guessReader(File, ReadWriteParameterMap)`

    - #### guessFormat

          public java.lang.String guessFormat(java.io.Reader reader,
                                              ReadWriteParameterMap parameters)
                                       throws java.lang.Exception

      Tries to determine the format of the contents of the specified reader by examining at its beginning (e.g. the root tag in XML formats). The format is determined by subsequent calls of `SingleReaderWriterFactory.checkFormat(Reader, ReadWriteParameterMap)` until a matching factory is found.

      The parameter map is only necessary for formats that are so variable that parameter values are needed to determine how a valid input would look like. That is currently not the case for any format supported in JPhyloIO, but may be necessary for third parts format-specific factories used in this instance. (Refer to the documentation of third party format-specific factories for details.) In most cases the convenience method `guessFormat(Reader)` will be sufficient.

      Note that in contrast to `guessReader(InputStream, ReadWriteParameterMap)`, this method does not support GZIPed inputs.

      Parameters:
        `reader` - the reader providing the contents
        `parameters` - the parameter map containing parameters for the JPhyloIO event reader that would be used with `reader`
      Returns:
        the ID of the determined format or `null` if no supported format seems to be matching the contents
      Throws:
        `java.lang.Exception` - if the underlying format specific factory throws an exception when testing the stream (e.g. because of an IO error)
      See Also:
        `JPhyloIOFormatIDs`, `guessReader(InputStream, ReadWriteParameterMap)`

    - #### guessFormat

          public java.lang.String guessFormat(java.io.Reader reader)
                                       throws java.lang.Exception

      Tries to determine the format of the contents of the specified reader by examining at its beginning (e.g. the root tag in XML formats). The format is determined by subsequent calls of `SingleReaderWriterFactory.checkFormat(Reader, ReadWriteParameterMap)` until a matching factory is found.

      It uses an empty parameter map that is passed to the internal calls of `SingleReaderWriterFactory.checkFormat(Reader, ReadWriteParameterMap)`. Use `guessFormat(Reader, ReadWriteParameterMap)` if parameters are necessary to determine the format correctly.

      Note that in contrast to `guessReader(InputStream, ReadWriteParameterMap)`, this method does not support GZIPed inputs.

      Parameters:
        `reader` - the reader providing the contents
      Returns:
        the ID of the determined format or `null` if no supported format seems to be matching the contents
      Throws:
        `java.lang.Exception` - if the underlying format specific factory throws an exception when testing the stream (e.g. because of an IO error)
      See Also:
        `JPhyloIOFormatIDs`, `guessReader(InputStream, ReadWriteParameterMap)`

    - #### guessFormat

          public java.lang.String guessFormat(java.io.InputStream stream,
                                              ReadWriteParameterMap parameters)
                                       throws java.lang.Exception

      Tries to determine the format of the contents of the specified input stream by examining at its beginning (e.g. the root tag in XML formats). The format is determined by subsequent calls of `SingleReaderWriterFactory.checkFormat(InputStream, ReadWriteParameterMap)` until a matching factory is found.

      The parameter map is only necessary for formats that are so variable that parameter values are needed to determine how a valid input would look like. That is currently not the case for any format supported in JPhyloIO, but may be necessary for third parts format-specific factories used in this instance. (Refer to the documentation of third party format-specific factories for details.) In most cases the convenience method `guessFormat(InputStream)` will be sufficient.

      Note that in contrast to `guessReader(InputStream, ReadWriteParameterMap)`, this method does not support GZIPed inputs.

      Parameters:
        `reader` - the reader providing the contents
        `parameters` - the parameter map containing parameters for the JPhyloIO event reader that would be used with `reader`
      Returns:
        the ID of the determined format or `null` if no supported format seems to be matching the contents
      Throws:
        `java.lang.Exception` - if the underlying format specific factory throws an exception when testing the stream (e.g. because of an IO error)
      See Also:
        `JPhyloIOFormatIDs`, `guessReader(InputStream, ReadWriteParameterMap)`

    - #### guessFormat

          public java.lang.String guessFormat(java.io.InputStream stream)
                                       throws java.lang.Exception

      Tries to determine the format of the contents of the specified reader by examining at its beginning (e.g. the root tag in XML formats). The format is determined by subsequent calls of `SingleReaderWriterFactory.checkFormat(InputStream, ReadWriteParameterMap)` until a matching factory is found.

      It uses an empty parameter map that is passed to the internal calls of `SingleReaderWriterFactory.checkFormat(InputStream, ReadWriteParameterMap)`. Use `guessFormat(InputStream, ReadWriteParameterMap)` if parameters are necessary to determine the format correctly.

      Note that in contrast to `guessReader(InputStream, ReadWriteParameterMap)`, this method does not support GZIPed inputs.

      Parameters:
        `reader` - the reader providing the contents
      Returns:
        the ID of the determined format or `null` if no supported format seems to be matching the contents
      Throws:
        `java.lang.Exception` - if the underlying format specific factory throws an exception when testing the stream (e.g. because of an IO error)
      See Also:
        `JPhyloIOFormatIDs`, `guessReader(InputStream, ReadWriteParameterMap)`

    - #### getFormatInfo

          public JPhyloIOFormatInfo getFormatInfo(java.lang.String formatID)

      Returns an information object for the specified format.
      Parameters:
        `formatID` - the unique format ID specifying the format
      Returns:
        the information object

    - #### guessReader

          public JPhyloIOEventReader guessReader(java.io.InputStream stream,
                                                 ReadWriteParameterMap parameters)
                                          throws java.lang.Exception

      Tries to determine the format of the contents of the specified input stream as described in the documentation of `guessFormat(InputStream)`, resets the input stream and than creates a reader for the according format from that stream. Additionally this method checks, if the input data is GZIPed and then returns a reader instance that unpacks the stream data while reading.

      In other words, this method is able to return a functional reader for input streams in all formats supported by this factory, as well as GZIPed streams providing data in any of these formats.

      Note that bytes of `stream` will be consumed by this method to determine the format, even if no according reader is found. If an event reader is returned, no events of this reader will have been consumed.

      Note that there is no version of this method accepting a `Reader` instead of an `InputStream`, because uncompressing data from a reader is not directly possible.

      Parameters:
        `stream` - the stream to read the data from
        `parameters` - the parameter map optionally containing parameters for the returned reader
      Returns:
        the new reader instance or `null` if no reader fitting the format of the stream could be found
      Throws:
        `java.lang.Exception` - if an exception occurs while determining the format from the stream or creating the returned reader instance (Depending on the type of reader that is returned, this will mostly be `IOException`s.)
      See Also:
        `guessFormat(InputStream)`, `getReader(String, InputStream, ReadWriteParameterMap)`

    - #### guessReader

          public JPhyloIOEventReader guessReader(java.io.File file,
                                                 ReadWriteParameterMap parameters)
                                          throws java.lang.Exception

      Tries to determine the format of the contents of the specified file as described in the documentation of `guessFormat(File)` and than creates a reader for the according format from that stream. Additionally this method checks, if the input data is GZIPed and then returns a reader instance that unpacks the stream data while reading.

      In other words, this method is able to return a functional reader for files in all formats supported by this factory, as well as GZIPed files in any of these formats.

      Note that there is no version of this method accepting a `Reader` instead of an `InputStream`, because uncompressing data from a reader is not directly possible.

      Parameters:
        `stream` - the stream to read the data from
        `parameters` - the parameter map optionally containing parameters for the returned reader
      Returns:
        the new reader instance or `null` if no reader fitting the format of the stream could be found
      Throws:
        `java.lang.Exception` - if an exception occurs while determining the format from the stream or creating the returned reader instance (Depending on the type of reader that is returned, this will mostly be `IOException`s.)
      See Also:
        `guessFormat(File)`, `getReader(String, File, ReadWriteParameterMap)`

    - #### getReader

          public JPhyloIOEventReader getReader(java.lang.String formatID,
                                               java.io.InputStream stream,
                                               ReadWriteParameterMap parameters)
                                        throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### getReader

          public JPhyloIOEventReader getReader(java.lang.String formatID,
                                               java.io.File file,
                                               ReadWriteParameterMap parameters)
                                        throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### getReader

          public JPhyloIOEventReader getReader(java.lang.String formatID,
                                               java.io.Reader reader,
                                               ReadWriteParameterMap parameters)
                                        throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### getWriter

          public JPhyloIOEventWriter getWriter(java.lang.String formatID)