uk.ac.ebi.arrayexpress2.magetab.handler.sdrf

Class SDRFReadInContextHandler

java.lang.Object

uk.ac.ebi.arrayexpress2.magetab.handler.AbstractHandler

uk.ac.ebi.arrayexpress2.magetab.handler.sdrf.SDRFReadHandler

uk.ac.ebi.arrayexpress2.magetab.handler.sdrf.SDRFReadInContextHandler

All Implemented Interfaces:

Handler, ReadHandler<String[],String[],SDRF>

Direct Known Subclasses:

FactorValueNodeHandler, ProtocolHandler

public abstract class SDRFReadInContextHandler
extends SDRFReadHandler

An implementation of an SDRFReadHandler that defines two extra methods that allow extra contextual data to be passed to concrete implementations. In places in the SDRF spec, nodes cannot be read entirely in isolation: examples of this are Factor Values and Protocols. Neither of these things are true "nodes" but do, in fact, behave like nodes in the spreadsheet rendering. Factor values are attributes that should be attached to the last Hybridization, assay or scan node but can move downstream of this in the graph. Protocols are edges but are modelled as protocol applications, where a protocol application node is a unique node described by the node upstream of it, the protocol references and any parameter values supplied.

For these reasons, both Protocol handlers and Factor Value handlers require additional context information: the columns prior to the FV or Hyb column must also be passed. This class exists to provide a common mechanism for passing this extra context information by defining a readFrom(String[], String[], uk.ac.ebi.arrayexpress2.magetab.datamodel.SDRF, int, int) method that behaves in the same manner as ReadHandler.read(Object, Object, Object, int, int) but allows a starting index to be passed. Implementations should start from the supplied index (this will be the factor value/protocol column) and read backwards or forwards as necessary.

Author:

Tony Burdett

Field Summary

Fields inherited from class uk.ac.ebi.arrayexpress2.magetab.handler.sdrf.SDRFReadHandler

PROTOCOL_DELIMITER

Fields inherited from class uk.ac.ebi.arrayexpress2.magetab.handler.AbstractHandler

listeners

Constructor Summary

Constructors

Constructor and Description
SDRFReadInContextHandler()

Method Summary

Methods

Modifier and Type	Method and Description
abstract int	assessFrom(String[] header, int columnNumber) Return the index of the last header this handler can read from in the supplied header, starting from the given start index.
abstract boolean	canReadFrom(String[] header, int startIndex) Determine whether this handler can read the data referenced by this header, starting from the supplied start index.
boolean	canReadHeader(String[] header) Determine whether this handler can read the data referenced by this header.
protected <T extends SDRFNode> T	fetchUpstreamNode(SDRF sdrf, String nodeName, Class<T> nodeClass) Used for adding nodes that are upstream of the current node in the SDRF graph.
protected SDRFNode	handleUpstreamNode(SDRF sdrf, String nodeName, String nodeType, int lineNumber, int columnNumber) Used for adding nodes that are upstream of the current node in the SDRF graph.
void	read(String[] header, String[] data, SDRF sdrf, int lineNumber, int columnNumber) Cause the handler to read the supplied data into the supplied target object.
abstract void	readDataFrom(String[] header, String[] data, SDRF sdrf, int lineNumber, int columnNumber) Performs the unit of work to read the data into the internal datamodel.
void	readFrom(String[] header, String[] data, SDRF sdrf, int lineNumber, int columnNumber) Cause the handler to read some of the supplied data (usually starting from startIndex) into the supplied target object, using additional context information where appropriate.

Methods inherited from class uk.ac.ebi.arrayexpress2.magetab.handler.sdrf.SDRFReadHandler

assess, assessAttribute, canRead, readAttribute, readData, updateChildNode

Methods inherited from class uk.ac.ebi.arrayexpress2.magetab.handler.AbstractHandler

accept, addListener, fireHandlingFailedEvent, fireHandlingStartedEvent, fireHandlingSucceededEvent, getListeners, getLog, removeListener

Methods inherited from class java.lang.Object

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

Methods inherited from interface uk.ac.ebi.arrayexpress2.magetab.handler.Handler

accept, addListener, getListeners, removeListener

Constructor Detail

SDRFReadInContextHandler

public SDRFReadInContextHandler()

Method Detail

canReadHeader

public boolean canReadHeader(String[] header)

Description copied from class: SDRFReadHandler

Determine whether this handler can read the data referenced by this header. Typically, the header in an IDF file (or ADF header) is the first token on any given line, and the header in an SDRF file (or ADF graph part) is the column heading for each tab-separated column. Other types of data referencing can be supplied - for example, an XML type reader might pass the tag qname as the header.

The header should be passed to the handler prior to reading to determine whether this handler can handle this line.

Specified by:

canReadHeader in class SDRFReadHandler

Parameters:

header - the first token on a line, or the column heading, which is the string describing this line contents

Returns:

true if this handler can handle this tag, false otherwise

read

public void read(String[] header,
        String[] data,
        SDRF sdrf,
        int lineNumber,
        int columnNumber)
          throws ParseException

Description copied from interface: ReadHandler

Cause the handler to read the supplied data into the supplied target object.

Specified by:

read in interface ReadHandler<String[],String[],SDRF>

Overrides:

read in class SDRFReadHandler

Parameters:

header - the header identifying the type of the data

data - the data to be read

sdrf - the object that the data will be read into

lineNumber - the line number of the field this data was read from

columnNumber - the column number of the field this data was read from

Throws:

ParseException - if parsing failed

readFrom

public void readFrom(String[] header,
            String[] data,
            SDRF sdrf,
            int lineNumber,
            int columnNumber)
              throws ParseException

Cause the handler to read some of the supplied data (usually starting from startIndex) into the supplied target object, using additional context information where appropriate.

Parameters:

header - the header identifying the type of the data

data - the data to be read

sdrf - the object that the data will be read into

lineNumber - the line number this data was read from

columnNumber - the index at which we want to commence reading from

Throws:

ParseException - if parsing failed

canReadFrom

public abstract boolean canReadFrom(String[] header,
                  int startIndex)

Determine whether this handler can read the data referenced by this header, starting from the supplied start index. The header in an SDRF file is the column heading for each tab-separated column. This specialised form of canReadHeader(String[]) is designed for handlers that require additional context information (handlers for Factor Values and Protocols, usually).

The header should be passed to the handler prior to reading to determine whether this handler can handle this line.

Parameters:

header - the first token on a line, or the column heading, which is the string describing this line contents

startIndex - the index that designates where the data starts

Returns:

true if this handler can handle this tag, false otherwise

assessFrom

public abstract int assessFrom(String[] header,
             int columnNumber)

Return the index of the last header this handler can read from in the supplied header, starting from the given start index. This can be used to determine the start and finish indices that a handler can read from/to.

Parameters:

header - the header to assess

columnNumber - the index of the first column where this data starts

Returns:

the last column index that can be read

readDataFrom

public abstract void readDataFrom(String[] header,
                String[] data,
                SDRF sdrf,
                int lineNumber,
                int columnNumber)
                           throws ParseException

Performs the unit of work to read the data into the internal datamodel. Override this method in implementations, so that you don't need to implement status updating and checking code. Implementations should determine how much data should be read from the data queue - access the data that still needs to be read by calling

Parameters:

header - the header identifying the data to read

data - the data to read

sdrf - the SDRF to add data to

lineNumber - the line number this data was read from

columnNumber - the first column of the data being read

Throws:

ParseException - if the header cannot be parsed or there was an error reading the value

handleUpstreamNode

protected SDRFNode handleUpstreamNode(SDRF sdrf,
                          String nodeName,
                          String nodeType,
                          int lineNumber,
                          int columnNumber)
                               throws ParseException

Used for adding nodes that are upstream of the current node in the SDRF graph. This is only required when handlers need to read backwards in the SDRF graph to resolve their parents. Special node types that extend SDRFReadInContextHandler to provide the ability to read-back should use this method if they discover a node reference to a parent node that has not yet been added to the SDRF graph.

This method actually creates a nested handler for generating the part of the SDRF that is described by this header and data.

Parameters:

sdrf - the sdrf to query

nodeName - the name of the node

nodeType - the entry in the header

lineNumber - the line being read

columnNumber - the column being read

Returns:

the node that was fetched or created if absent

Throws:

ParseException - if the node could not be created or retrieved

fetchUpstreamNode

protected <T extends SDRFNode> T fetchUpstreamNode(SDRF sdrf,
                                       String nodeName,
                                       Class<T> nodeClass)
                                        throws ParseException

Used for adding nodes that are upstream of the current node in the SDRF graph. This is only required when handlers need to read backwards in the SDRF graph to resolve their parents. Special node types that extend SDRFReadInContextHandler to provide the ability to read-back should use this method if they discover a node reference to a parent node that has not yet been added to the SDRF graph.

Parameters:

sdrf - the sdrf to query

nodeName - the name of the node

nodeClass - the class of the node required

Returns:

the node that was fetched or created if absent

Throws:

ParseException - if the node could not be created or retrieved