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

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