jezuch.utils.starmapper3.model
Interface DataModel<N extends Node,R extends Region,I extends NodeInfo<N,R,I>>

All Known Implementing Classes:

AbstractDataModel, InterpolatingModel, StarsDataModel, TParsecDataModel, TParsecDumpDataModel

public interface DataModel<N extends Node,R extends Region,I extends NodeInfo<N,R,I>>

An interface describing Starmapper's Data Model. The Data Model consists of implementations of three interfaces: Node, Region and NodeInfo. Implementation of this interface is a "glue" that sticks relevant parts of Data Model together; it provides Class instances for concrete implementations of interfaces mentioned above and serves as a factory for several additional model-specific objects, such as Regions and Producers to produce Nodes and NodeInfos.

Producers are used instead of iterators because to implement the iterator's Iterator.hasNext(), the iterator has to look ahead for next element to see if it exists and this can block the Starmapper if the producer has to wait for next reports to arrive. Producers, on the other hand, signal the end of stream by returning a "poison" value, the null, and the values can be returned and processed immediately without waiting to see if the next element exists.

The other responsibility of DataModel is implementation of a double dispatch for applications. See Application for details. The startApplication(Application, Config) method is (usually) very simple and thus is implemented by AbstractDataModel, which implementations of DataModel are encouraged to extend.

Author:

ksobolewski

See Also:

Application, Node, Region, NodeInfo

Method Summary

R	createRegion(int regionNumber) Creates this Data Model's concrete implementation of Region, described by the given Config and this region's number (identifier).
void	endSession() Ends a session with this Data Model.
Producer<Pair<Integer,List<ReportDescriptor<N,R,I>>>>	getAvailableReports() Lists reports available to this Data Model by returning a Producer with reports from the same time grouped in Lists.
LongRectangle	getMapBounds() Returns a LongRectangle discribing dimensions of the "universe" of current session; Starmapper expects that the map has a fixed size and it will not change during the session (so that the consecutive images are using the same reference system).
List<Converter<?>>	getModelConverters() Returns a List of settings accepted by this data model.
List<Setting>	getModelSettings() Returns a List of settings accepted by this data model.
Class<N>	getNodeClass() Returns this Data Model's concrete Node's Class.
Class<I>	getNodeInfoClass() Returns this Data Model's concrete NodeInfo's Class.
Class<R>	getRegionClass() Returns this Data Model's concrete Region's Class.
boolean	isInSession() Tells the caller if this model is in session, i.e. the startSession(Config, URI, String, EventListener) method was called, but not endSession().
void	startApplication(Application app, Config settings) Implements a double dispatch bridge between non-generified and generified application code; see Application for details.
void	startSession(Config config, URI pathBase, String baseName, EventListener eventListener) Starts an application session with this model - the model is allowed (but discouraged) to modify the given Config for the duration of the session and the model should guarantee that the config will not change during this time.

Method Detail

getNodeClass

Class<N> getNodeClass()

Returns this Data Model's concrete Node's Class.

Returns:

this Data Model's concrete Node's Class.

getRegionClass

Class<R> getRegionClass()

Returns this Data Model's concrete Region's Class.

Returns:

this Data Model's concrete Region's Class.

getNodeInfoClass

Class<I> getNodeInfoClass()

Returns this Data Model's concrete NodeInfo's Class.

Returns:

this Data Model's concrete NodeInfo's Class.

getModelSettings

List<Setting> getModelSettings()

Returns a List of settings accepted by this data model.

Returns:

this model's settings

getModelConverters

List<Converter<?>> getModelConverters()

Returns a List of settings accepted by this data model.

Returns:

this model's settings

startSession

void startSession(Config config,
                  URI pathBase,
                  String baseName,
                  EventListener eventListener)
                  throws ParametersException,
                         IOException,
                         ProducerException

Starts an application session with this model - the model is allowed (but discouraged) to modify the given Config for the duration of the session and the model should guarantee that the config will not change during this time. The data model can send events to a given EventListener; this listener is installed in the model for the duration of this session and is removed when endSession() is called.

Parameters:

config - the Config for the session

pathBase - a base URI that can be used to resolve relative paths (see URI.resolve(URI))

baseName - the session's "base name" (AKA "signature"), usually used to name and/or find data files

eventListener - a EventListener to which this model can send events

Throws:

ParametersException - if the session Config complains about reconfiguration

IOException - if an IO error occurs

ProducerException - on any producer-related error

isInSession

boolean isInSession()

Tells the caller if this model is in session, i.e. the startSession(Config, URI, String, EventListener) method was called, but not endSession().

Returns:

true if this model is in session

endSession

void endSession()
                throws ParametersException,
                       IOException,
                       ProducerException

Ends a session with this Data Model.

Throws:

ParametersException - if the session Config complains about reconfiguration

IOException - if an IO error occurs

ProducerException - on any producer-related error

getMapBounds

LongRectangle getMapBounds()
                           throws ParametersException,
                                  IOException,
                                  ProducerException

Returns a LongRectangle discribing dimensions of the "universe" of current session; Starmapper expects that the map has a fixed size and it will not change during the session (so that the consecutive images are using the same reference system). It is safe to return a mutable object here, Starmapper will not modify it.

Returns:

map bounds for the current session

Throws:

ParametersException - if any of the Config values is invalid

IOException - if an IO error occurs

ProducerException - on any producer-related error

createRegion

R createRegion(int regionNumber)
                              throws ParametersException,
                                     IOException,
                                     ProducerException

Creates this Data Model's concrete implementation of Region, described by the given Config and this region's number (identifier).

Parameters:

regionNumber - the number (identifier) of the region to construct

Returns:

this Data Model's concrete implementation of Region

Throws:

ParametersException - if any of the Config values is invalid

IOException - if an IO error occurs

ProducerException - on any producer-related error

getAvailableReports

Producer<Pair<Integer,List<ReportDescriptor<N,R,I>>>> getAvailableReports()
                                                                                                                              throws ParametersException,
                                                                                                                                     IOException,
                                                                                                                                     ProducerException

Lists reports available to this Data Model by returning a Producer with reports from the same time grouped in Lists. The elements returned are Pairs in which the left component is the time from which those reorts are and the right component is the list of reports (the reports' time is duplicated in a separate value, because it is allowed to return empty list of reports for a given time).

The place where those reports are to be sought is usually specified in model-specific Config values.

Returns:

an Producer of available reports as ReportDescriptors grouped by time

Throws:

ParametersException - if any of the Config values is invalid

IOException - if an IO error occurs

ProducerException - on any producer-related error

startApplication

void startApplication(Application app,
                      Config settings)
                      throws ParametersException,
                             IOException,
                             ProducerException

Implements a double dispatch bridge between non-generified and generified application code; see Application for details.

Parameters:

app - the Application to call back

settings - the Config used by the application

Throws:

ParametersException - if the Config complains about reconfiguration

IOException - if an IO error occurs

ProducerException - on any producer-related error

See Also:

Application, AbstractDataModel