uk.ac.ebi.arrayexpress2.magetab.parser

Class MAGETABParser<O>

java.lang.Object

uk.ac.ebi.arrayexpress2.magetab.parser.AbstractParser<MAGETABInvestigation>

uk.ac.ebi.arrayexpress2.magetab.parser.MAGETABParser<O>

Type Parameters:

O - an optional type parameter if you are utilising convert functions, this describes the type of object you wish to convert output to

All Implemented Interfaces:

Parser<MAGETABInvestigation>

public class MAGETABParser<O>
extends AbstractParser<MAGETABInvestigation>

Imports MAGETAB documents into a MAGETABInvestigation. The MAGETABParser implements logic to discover the IDF and SDRF components from the URL supplied. The URL supplied should match the location of the IDF, and the SDRF should be referenced within. This parser then distributes tasks to IDFParser and SDRFParser components. Alternatively, you can invoke these classes separately - you will just need to instantiate a new MAGETABInvestigation to read into yourself. Ultimately, this results in a set of objects that can be obtained from a MAGETABInvestigation using public fields or getters.

Author:

Tony Burdett

See Also:

IDFParser, SDRFParser, MAGETABInvestigation

Nested Class Summary

Nested classes/interfaces inherited from class uk.ac.ebi.arrayexpress2.magetab.parser.AbstractParser

AbstractParser.DefaultHandlerListener

Field Summary

Fields inherited from interface uk.ac.ebi.arrayexpress2.magetab.parser.Parser

DEFAULT_ENCODING

Constructor Summary

Constructors

Constructor and Description
MAGETABParser() Create a default parser.
MAGETABParser(Converter<MAGETABInvestigation,O> converter, O... outputResources) Create a parser that performs conversion using the supplied Converter to convert the MAGETABInvestigation that results from the parse into objects in the given object model.
MAGETABParser(O... outputResources) Create a default parser.
MAGETABParser(Validator<MAGETABInvestigation> validator) Create a parser that performs validation using the supplied Validator.
MAGETABParser(Validator<MAGETABInvestigation> validator, Converter<MAGETABInvestigation,O> converter, O... outputResources) Create a parser that performs validation using the supplied Validator and conversion using the supplied Converter.

Method Summary

Methods

Modifier and Type	Method and Description
void	addErrorItemListener(ErrorItemListener listener) Register an ErrorItemListener with this parser.
Converter<MAGETABInvestigation,O>	getConverter() Get the currently configured converter for this parser.
Validator<MAGETABInvestigation>	getValidator() Get the currently configured validator for this parser.
MAGETABInvestigation	parse(File idfFile)
MAGETABInvestigation	parse(InputStream idfIn) Perform parsing from the supplied input stream to a new data model instance.
MAGETABInvestigation	parse(InputStream idfIn, MAGETABInvestigation investigation) Perform parsing from the supplied input stream to a new data model instance.
MAGETABInvestigation	parse(InputStream idfIn, MAGETABInvestigation investigation, 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.
MAGETABInvestigation	parse(URL idfURL)
protected void	readIDF(InputStream idfIn, MAGETABInvestigation investigation, boolean isMerged, ExecutorService service, uk.ac.ebi.arrayexpress2.magetab.parser.MAGETABParser.ProgressFlag flag)
protected void	readSDRF(InputStream sdrfIn, SDRF sdrf, ExecutorService service, uk.ac.ebi.arrayexpress2.magetab.parser.MAGETABParser.ProgressFlag flag)
void	removeErrorItemListener(ErrorItemListener listener) Deregister an ErrorItemListener with this parser.
void	setStripEscaping(boolean stripEscaping)

Methods inherited from class uk.ac.ebi.arrayexpress2.magetab.parser.AbstractParser

addProgressListener, fireErrorItemEvent, fireParseEvent, fireParsingCompletedEvent, fireParsingFailedEvent, fireParsingStartedEvent, getEncoding, getErrorItemListeners, getLog, getProgressListeners, isStrippingEscaping, removeProgressListener, setEncoding

Methods inherited from class java.lang.Object

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

Constructor Detail

MAGETABParser

public MAGETABParser()

Create a default parser. This will parse MAGE-TAB documents using the core set of parse handlers, plus any other handlers present on the classpath.

To extend this default parser to perform validation and/or conversion activities, you can simply add ValidateHandler and ConversionHandler implementations to the classpath (appropriately annotated). The set of handlers located on the classpath will then be used to validate and convert MAGE-TAB.

Note that validation happens after parsing is complete, and conversion happens after validation as long as an appropriate output resource has been set on the parser.

MAGETABParser

public MAGETABParser(O... outputResources)

Create a default parser. This will parse MAGE-TAB documents using the core set of parse handlers, plus any other handlers present on the classpath.

To extend this default parser to perform validation and/or conversion activities, you can simply add ValidateHandler and ConversionHandler implementations to the classpath (appropriately annotated). The set of handlers located on the classpath will then be used to validate and convert MAGE-TAB.

Note that validation happens after parsing is complete, and conversion happens after validation as long as an appropriate output resource has been set on the parser.

Parameters:

outputResources - any output resources to convert into

MAGETABParser

public MAGETABParser(Validator<MAGETABInvestigation> validator)

Create a parser that performs validation using the supplied Validator. Normally, the validate() method on the Validator will be called once reading has completed.

Parameters:

validator - the validator this parser should use to validate once parsing has completed.

MAGETABParser

public MAGETABParser(Converter<MAGETABInvestigation,O> converter,
             O... outputResources)

Create a parser that performs conversion using the supplied Converter to convert the MAGETABInvestigation that results from the parse into objects in the given object model. The convert() method on the Converter will be called once reading and validation (if any) has completed).

Parameters:

converter - the converter this parser should use to do the conversion once parsing (and any validation) has completed

outputResources - the output resources to convert into

MAGETABParser

public MAGETABParser(Validator<MAGETABInvestigation> validator,
             Converter<MAGETABInvestigation,O> converter,
             O... outputResources)

Create a parser that performs validation using the supplied Validator and conversion using the supplied Converter. Any escaping in the MAGE-TAB documentation is removed during the parse by default - use setStripEscaping(boolean) to change this. If converters are available on the classpath when parsing, you should set an output resource on this parser to utilise them.

Parameters:

validator - the validator to use to validate the resulting MAGETABInvestigation

converter - the converter to use to convert the resulting MAGETABInvestigation

outputResources - the output resources to convert into

Method Detail

setStripEscaping

public void setStripEscaping(boolean stripEscaping)

Overrides:

setStripEscaping in class AbstractParser<MAGETABInvestigation>

getValidator

public Validator<MAGETABInvestigation> getValidator()

Get the currently configured validator for this parser.

Returns:

the validator for this parser, or null if there has not been one set.

getConverter

public Converter<MAGETABInvestigation,O> getConverter()

Get the currently configured converter for this parser.

Returns:

the converter for this parser, or null if there has not been one set.

addErrorItemListener

public void addErrorItemListener(ErrorItemListener listener)

Description copied from interface: Parser

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

Specified by:

addErrorItemListener in interface Parser<MAGETABInvestigation>

Overrides:

addErrorItemListener in class AbstractParser<MAGETABInvestigation>

Parameters:

listener - the listener to register

removeErrorItemListener

public void removeErrorItemListener(ErrorItemListener listener)

Description copied from interface: Parser

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

Specified by:

removeErrorItemListener in interface Parser<MAGETABInvestigation>

Overrides:

removeErrorItemListener in class AbstractParser<MAGETABInvestigation>

Parameters:

listener - the listener to register

parse

public MAGETABInvestigation parse(File idfFile)
                           throws ParseException

Throws:

ParseException

parse

public MAGETABInvestigation parse(URL idfURL)
                           throws ParseException

Throws:

ParseException

parse

public MAGETABInvestigation parse(InputStream idfIn)
                           throws ParseException

Description copied from interface: Parser

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:

idfIn - 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

public MAGETABInvestigation parse(InputStream idfIn,
                         MAGETABInvestigation investigation)
                           throws ParseException

Description copied from interface: Parser

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:

idfIn - the input stream to parse from

investigation - 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

public MAGETABInvestigation parse(InputStream idfIn,
                         MAGETABInvestigation investigation,
                         ExecutorService service)
                           throws ParseException,
                                  InterruptedException

Description copied from interface: Parser

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:

idfIn - the input stream to parse from

investigation - 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

readIDF

protected void readIDF(InputStream idfIn,
           MAGETABInvestigation investigation,
           boolean isMerged,
           ExecutorService service,
           uk.ac.ebi.arrayexpress2.magetab.parser.MAGETABParser.ProgressFlag flag)

readSDRF

protected void readSDRF(InputStream sdrfIn,
            SDRF sdrf,
            ExecutorService service,
            uk.ac.ebi.arrayexpress2.magetab.parser.MAGETABParser.ProgressFlag flag)