uk.ac.ebi.arrayexpress2.magetab.parser

Interface Parser<T>

Type Parameters:

T - the type of data model to parse into

All Known Implementing Classes:

AbstractParser, ADFParser, IDFParser, MAGETABArrayParser, MAGETABParser, SDRFParser

public interface Parser<T>

A parser that reads from a given URL and populates a data model. The data model is of a generic type specified by the parameter on implementing classes.

Author:

Tony Burdett

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_ENCODING The default encoding of the files being parsed.

Method Summary

Methods

Modifier and Type	Method and Description
void	addErrorItemListener(ErrorItemListener listener) Register an ErrorItemListener with this parser.
void	addProgressListener(ProgressListener listener) Register a ProgressListener with this parser.
String	getEncoding() Gets current encoding for the parser.
Collection<ErrorItemListener>	getErrorItemListeners() Get the collection of ErrorItemListeners registered to this parser
Collection<ProgressListener>	getProgressListeners() Get the collection of ProgressListeners that are currently registered to this parser.
T	parse(InputStream dataIn) Perform parsing from the supplied input stream to a new data model instance.
T	parse(InputStream dataIn, T target) Perform parsing from the supplied input stream to a new data model instance.
T	parse(InputStream dataIn, T target, ExecutorService service) Perform parsing from the supplied input stream to a new data model instance, delegating all work to the supplied Executor Service to enable parsing in parallel.
void	removeErrorItemListener(ErrorItemListener listener) Deregister an ErrorItemListener with this parser.
void	removeProgressListener(ProgressListener listener) Deregister a ProgressListener from this parser.
void	setEncoding(String encoding) Sets an alternative encoding for the parser.

Field Detail

DEFAULT_ENCODING

static final String DEFAULT_ENCODING

The default encoding of the files being parsed. You can override this if you wish, if you know you are reading from files encoded as something different to this default. The encoding specified currently is ISO-8859-1, but this may change depending on the forthcoming MAGE-TAB 1.1 specification. ISO-8859-1 was chosen because a) this is a web standard, and will make for better web service visualisations and b) because it will introduce fewest encoding issues - occasionally there will be mistranslations (e.g. from cp1525) - but for most characters in the latin-1 character sets this will always work, except where UTF-8 or UTF-16 encoding is used, but in these cases most of the time it will be possible to "get back" to the original text by stripping out additional bytes where variable encodings are used.

If required, you can set this to an alternative encoding prior to invoking a parse operation. Standard java character set names are recognised.

As part of the parse lifecycle, read, validate and convert operations are supported. Read operations are always triggered provided ReadHandlers are available. Validate operations are triggered if this parser has a validator set and if ValidateHandlers are available, and convert operations are triggered if this parser has an output resource set and if ConversionHandlers are available. Read operations are always performed first, followed by validate operations, followed finally by convert operations.

See Also:

Constant Field Values

Method Detail

getEncoding

String getEncoding()

Gets current encoding for the parser.

Returns:

input encoding of the stream

setEncoding

void setEncoding(String encoding)

Sets an alternative encoding for the parser.

Parameters:

encoding - input encoding of the stream

addErrorItemListener

void addErrorItemListener(ErrorItemListener listener)

Register an ErrorItemListener with this parser. Whenever an error is encountered when parsing from the a parserSource, this listener should be notified.

Parameters:

listener - the listener to register

removeErrorItemListener

void removeErrorItemListener(ErrorItemListener listener)

Deregister an ErrorItemListener with this parser. This listener will no longer be notified when error items are generated.

Parameters:

listener - the listener to register

getErrorItemListeners

Collection<ErrorItemListener> getErrorItemListeners()

Get the collection of ErrorItemListeners registered to this parser

Returns:

the current set of listeners registered

addProgressListener

void addProgressListener(ProgressListener listener)

Register a ProgressListener with this parser. Whenever the parser has more progress to report, this listener will be notified.

Parameters:

listener - the listener to register

removeProgressListener

void removeProgressListener(ProgressListener listener)

Deregister a ProgressListener from this parser. Progress events will no longer be reported through this parser

Parameters:

listener - a listener to monitor progress of the parsing operation

getProgressListeners

Collection<ProgressListener> getProgressListeners()

Get the collection of ProgressListeners that are currently registered to this parser.

Returns:

all currently registered progress listeners

parse

T parse(InputStream dataIn)
        throws ParseException

Perform parsing from the supplied input stream to a new data model instance.

A ParseException will be thrown if data could not be read from the supplied stream. You should not rely on an exception being thrown to determine whether the supplied MAGE-TAB is valid or complete, as parser implementations may ignore invalid or unreadable sections. Instead you should register an ErrorItem listener and check that there are no critical error events fired during the parse operation.

Parameters:

dataIn - the input stream to parse from

Returns:

the data model that has been populated by this parse operation

Throws:

ParseException - if the source format was invalid, or the URL could not be read.

parse

T parse(InputStream dataIn,
      T target)
        throws ParseException

Perform parsing from the supplied input stream to a new data model instance. The supplied target will be populated with data - the result of this method will be simply a reference to the passed parameter.

A ParseException will be thrown if data could not be read from the supplied stream. You should not rely on an exception being thrown to determine whether the supplied MAGE-TAB is valid or complete, as parser implementations may ignore invalid or unreadable sections. Instead you should register an ErrorItem listener and check that there are no critical error events fired during the parse operation.

Parameters:

dataIn - the input stream to parse from

target - the data model to populate with data during this parse operation

Returns:

the data model that has been populated by this import operation

Throws:

ParseException - if the source format was invalid, or the URL could not be read.

parse

T parse(InputStream dataIn,
      T target,
      ExecutorService service)
        throws ParseException,
               InterruptedException

Perform parsing from the supplied input stream to a new data model instance, delegating all work to the supplied Executor Service to enable parsing in parallel.

A ParseException will be thrown if data could not be read from the supplied stream. You should not rely on an exception being thrown to determine whether the supplied MAGE-TAB is valid or complete, as parser implementations may ignore invalid or unreadable sections. Instead you should register an ErrorItem listener and check that there are no critical error events fired during the parse operation.

Parameters:

dataIn - the input stream to parse from

target - the data model to populate with data during this parse operation

service - the service to use to execute parsing tasks

Returns:

the data model that has been populated by this import operation

Throws:

ParseException - if the source format was invalid, or the URL could not be read.

InterruptedException - if execution of a task sent to the Executor Service was interrrupted