org.aksw.gerbil.database

Interface ExperimentDAO

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractExperimentDAO, ExperimentDAOImpl

public interface ExperimentDAO
extends Closeable

This interface defines the methods a class has to implement for making the results of the framework persistent.

Author:

m.roeder

Field Summary

Fields

Modifier and Type	Field and Description
static int	CACHED_EXPERIMENT_TASK_CAN_BE_USED Sentinel value indicating that the database already contains a result for an experiment task which can be reused by an experiment.
static int	TASK_FINISHED Sentinel value stored as state in the database indicating that a task has been finished.
static int	TASK_NOT_FOUND Sentinel value returned if the task with the given id couldn't be found.
static int	TASK_STARTED_BUT_NOT_FINISHED_YET Sentinel value stored as state in the database indicating that a task has been started but there weren't stored any results until now.

Method Summary

Modifier and Type	Method and Description
int	connectCachedResultOrCreateTask(String annotatorName, String datasetName, String experimentType, String matching, String experimentId) This method is called with the description of an experiment task and an experiment id.
int	createTask(String annotatorName, String datasetName, String experimentType, String matching, String experimentId) Creates a new experiment task with the given preferences, sets its GERBIL version value using the current version, sets the task to unfinished by setting its state to TASK_STARTED_BUT_NOT_FINISHED_YET and connects it to the experiment with the given experiment id.
List<ExperimentTaskResult>	getAllRunningExperimentTasks() Returns a list of all running experiment tasks.
int	getExperimentState(int experimentTaskId) Returns the state of the existing experiment task, identified by the given id.
String	getHighestExperimentId() Returns the highest experiment ID that is known by the system or null if there are no experiments.
List<ExperimentTaskResult>	getLatestResultsOfExperiments(String experimentType, String matching) Deprecated.
List<ExperimentTaskResult>	getLatestResultsOfExperiments(String experimentType, String matching, String[] annotatorNames, String[] datasetNames) Returns the latest results for experiments with the given experiment type and matching type.
ExperimentTaskResult	getResultOfExperimentTask(int experimentTaskId) Returns the result of the experiment task with the given ID or null if this task does not exist.
List<ExperimentTaskResult>	getResultsOfExperiment(String experimentId) Returns the results of the experiment tasks that are connected to the experiment with the given experiment id.
void	initialize() Initializes the database.
void	setExperimentState(int experimentTaskId, int state) Sets the state of the already existing experiment task, identified by the given id.
void	setExperimentTaskResult(int experimentTaskId, ExperimentTaskResult result) This method updates the result of the already existing experiment task, identified by the given id.
void	setResultDurability(long milliseconds) Sets the durability of a experiment task result.

Methods inherited from interface java.io.Closeable

close

Field Detail

CACHED_EXPERIMENT_TASK_CAN_BE_USED

static final int CACHED_EXPERIMENT_TASK_CAN_BE_USED

Sentinel value indicating that the database already contains a result for an experiment task which can be reused by an experiment.

See Also:

Constant Field Values

TASK_FINISHED

static final int TASK_FINISHED

Sentinel value stored as state in the database indicating that a task has been finished.

See Also:

Constant Field Values

TASK_STARTED_BUT_NOT_FINISHED_YET

static final int TASK_STARTED_BUT_NOT_FINISHED_YET

Sentinel value stored as state in the database indicating that a task has been started but there weren't stored any results until now.

See Also:

Constant Field Values

TASK_NOT_FOUND

static final int TASK_NOT_FOUND

Sentinel value returned if the task with the given id couldn't be found.

See Also:

Constant Field Values

Method Detail

initialize

void initialize()

Initializes the database. Searches the database for experiment tasks that have been started but not ended yet (their status equals TASK_STARTED_BUT_NOT_FINISHED_YET ) and set their status to ErrorTypes.SERVER_STOPPED_WHILE_PROCESSING. This method should only be called directly after the initialization of the database. It makes sure that "old" experiment tasks which have been started but never finished are set to an error state and can't be used inside the caching mechanism.

setResultDurability

void setResultDurability(long milliseconds)

Sets the durability of a experiment task result.

Parameters:

milliseconds -

getResultsOfExperiment

List<ExperimentTaskResult> getResultsOfExperiment(String experimentId)

Returns the results of the experiment tasks that are connected to the experiment with the given experiment id. Note that before retrieving the results of an experiment its state should be checked.

Parameters:

experimentId - if of the experiment

Returns:

a list of experiment task results that are connected to the experiment

getResultOfExperimentTask

ExperimentTaskResult getResultOfExperimentTask(int experimentTaskId)

Returns the result of the experiment task with the given ID or null if this task does not exist.

Parameters:

experimentTaskId - the id of the experiment task

Returns:

the experiment task or null if this task does not exist.

connectCachedResultOrCreateTask

int connectCachedResultOrCreateTask(String annotatorName,
                                    String datasetName,
                                    String experimentType,
                                    String matching,
                                    String experimentId)

This method is called with the description of an experiment task and an experiment id. The method checks whether there is already such an experiment task inside the database that does not have an error code as state. If such a task exists and if it is not to old regarding the durability of experiment task results, the experiment id is connected to the already existing task and CACHED_EXPERIMENT_TASK_CAN_BE_USED = -1 is returned. Otherwise, a new experiment task is created, set to unfinished by setting its state to TASK_STARTED_BUT_NOT_FINISHED_YET, connected to the given experiment and the id of the newly created experiment task is returned. NOTE: this method MUST be synchronized since it should only be called by a single thread at once.

Parameters:

annotatorName - the name with which the annotator can be identified

datasetName - the name of the dataset

experimentType - the name of the experiment type

matching - the name of the matching used

experimentId - the id of the experiment

Returns:

CACHED_EXPERIMENT_TASK_CAN_BE_USED= -1 if there is already an experiment task with the given preferences or the id of the newly created experiment task.

createTask

int createTask(String annotatorName,
               String datasetName,
               String experimentType,
               String matching,
               String experimentId)

Creates a new experiment task with the given preferences, sets its GERBIL version value using the current version, sets the task to unfinished by setting its state to TASK_STARTED_BUT_NOT_FINISHED_YET and connects it to the experiment with the given experiment id.

Parameters:

annotatorName - the name with which the annotator can be identified

datasetName - the name of the dataset

experimentType - the name of the experiment type

matching - the name of the matching used

experimentId - the id of the experiment

Returns:

the id of the newly created experiment task.

setExperimentTaskResult

void setExperimentTaskResult(int experimentTaskId,
                             ExperimentTaskResult result)

This method updates the result of the already existing experiment task, identified by the given id. Additionally it should update the timestamp of the task and set its state to the state countained inside the given result object.

Parameters:

experimentTaskId - the id of the experiment task to which the result has been calculated

result - the result of this experiment task

setExperimentState

void setExperimentState(int experimentTaskId,
                        int state)

Sets the state of the already existing experiment task, identified by the given id.

Parameters:

experimentTaskId - the id of the experiment task for which the state should be set

state - the state of this experiment task

getExperimentState

int getExperimentState(int experimentTaskId)

Returns the state of the existing experiment task, identified by the given id.

Parameters:

experimentTaskId - the id of the experiment task for which the state should be retrieved

Returns:

the state of the experiment task or TASK_NOT_FOUND= -2 if such a task couldn't be found.

getHighestExperimentId

String getHighestExperimentId()

Returns the highest experiment ID that is known by the system or null if there are no experiments.

Returns:

the highest experiment ID or null if there is no experiment

getLatestResultsOfExperiments

@Deprecated
List<ExperimentTaskResult> getLatestResultsOfExperiments(String experimentType,
                                                                     String matching)

Deprecated.

Returns the latest results for experiments with the given experiment type and matching type. Note that the experiment tasks of which the results are returned should be finished.

Parameters:

experimentType - the name of the experiment type

matching - the name of the matching used

Returns:

a list of the latest results available in the database.

getLatestResultsOfExperiments

List<ExperimentTaskResult> getLatestResultsOfExperiments(String experimentType,
                                                         String matching,
                                                         String[] annotatorNames,
                                                         String[] datasetNames)

Returns the latest results for experiments with the given experiment type and matching type. Note that the experiment tasks of which the results are returned should be finished.

Parameters:

experimentType - the name of the experiment type

matching - the name of the matching used

annotatorNames - the names of annotators for which the data should be collected

datasetNames - the names of datasets for which the data should be collected

Returns:

a list of the latest results available in the database.

getAllRunningExperimentTasks

List<ExperimentTaskResult> getAllRunningExperimentTasks()

Returns a list of all running experiment tasks.

Returns:

a list of all running experiment tasks.