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

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

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

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)