Package ai.libs.jaicore.experiments

Interface IExperimentDatabaseHandle

All Known Implementing Classes:

AExperimenterSQLHandle, ExperimenterMySQLHandle, ExperimenterRestSQLHandle

public interface IExperimentDatabaseHandle

This interface is used by the ExperimentRunner to get, create, and update experiment entries.

Method Summary

Modifier and Type	Method	Description
ExperimentDBEntry	createAndGetExperiment(Experiment experiment)	Creates a new experiment entry and returns it.
java.util.List<ExperimentDBEntry>	createOrGetExperiments(java.util.List<Experiment> experiments)	Creates or fetches the experiment entries from the database.
void	deleteDatabase()	Deletes everything known to the experiment database.
void	deleteExperiment(ExperimentDBEntry exp)	Deletes an experiment from the database
void	finishExperiment(ExperimentDBEntry exp)	Signals that an experiment has been finished successfully.
void	finishExperiment(ExperimentDBEntry exp, java.lang.Throwable errror)	Signals that an experiment has failed with an exception.
java.util.List<ExperimentDBEntry>	getAllExperiments()	Returns a list of all experiments contained in the database
java.util.List<ExperimentDBEntry>	getConductedExperiments()	Returns a list of all experiments contained in the database marked as being conducted.
java.util.List<ExperimentDBEntry>	getConductedExperiments(java.util.Map<java.lang.String,java.lang.Object> fieldFilter)	Returns a list of all experiments contained in the database marked as being conducted and with the attribute values specified as in the map.
java.util.Collection<java.lang.String>	getConsideredValuesForKey(java.lang.String key)
ExperimentDBEntry	getExperimentWithId(int id)	Gets the experiment with the given id.
java.util.List<ExperimentDBEntry>	getFailedExperiments()	Returns a list of all experiments contained in the database marked as being conducted and with an exception.
java.util.List<ExperimentDBEntry>	getFailedExperiments(java.util.Map<java.lang.String,java.lang.Object> fieldFilter)	Returns a list of all experiments contained in the database marked as being conducted and with an exception and with the attribute values specified as in the map.
int	getNumberOfAllExperiments()	Returns the number of all experiments contained in the database
java.util.List<ExperimentDBEntry>	getOpenExperiments()	Returns a list of all experiments contained in the database that have not been started yet.
java.util.List<ExperimentDBEntry>	getRandomOpenExperiments(int limit)	Returns a list of all experiments contained in the database that have not been started yet.
java.util.List<ExperimentDBEntry>	getRunningExperiments()	Returns a list of all experiments that are currently being conducted.
boolean	hasExperimentStarted(ExperimentDBEntry exp)	Checks if the given experiment has been started already.
void	setup(IExperimentSetConfig config)	Prepares everything so that upcoming calls for create and update will be managed according to the specified configuration.
void	startExperiment(ExperimentDBEntry exp, java.lang.String executorInfo)	Starts the given experiment
java.util.Optional<ExperimentDBEntry>	startNextExperiment(java.lang.String executorInfo)	Picks an unstarted experiment, marks it as started and returns it.
void	updateExperiment(ExperimentDBEntry exp, java.util.Map<java.lang.String,? extends java.lang.Object> values)	Updates non-keyfield values of the experiment.
boolean	updateExperimentConditionally(ExperimentDBEntry exp, java.util.Map<java.lang.String,java.lang.String> conditions, java.util.Map<java.lang.String,? extends java.lang.Object> values)

Method Detail

setup

void setup(IExperimentSetConfig config)
    throws ExperimentDBInteractionFailedException

Prepares everything so that upcoming calls for create and update will be managed according to the specified configuration.

Parameters:

config - Description of the experiment setup

Throws:

ExperimentDBInteractionFailedException

getConsideredValuesForKey

java.util.Collection<java.lang.String> getConsideredValuesForKey(java.lang.String key)
                                                          throws ExperimentDBInteractionFailedException

Parameters:

key - The key attribute

Throws:

ExperimentDBInteractionFailedException

getAllExperiments

java.util.List<ExperimentDBEntry> getAllExperiments()
                                             throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database

Returns:

List of all experiments

Throws:

ExperimentDBInteractionFailedException

getNumberOfAllExperiments

int getNumberOfAllExperiments()
                       throws ExperimentDBInteractionFailedException

Returns the number of all experiments contained in the database

Throws:

ExperimentDBInteractionFailedException

getConductedExperiments

java.util.List<ExperimentDBEntry> getConductedExperiments()
                                                   throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database marked as being conducted.

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

getConductedExperiments

java.util.List<ExperimentDBEntry> getConductedExperiments(java.util.Map<java.lang.String,java.lang.Object> fieldFilter)
                                                   throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database marked as being conducted and with the attribute values specified as in the map.

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

getFailedExperiments

java.util.List<ExperimentDBEntry> getFailedExperiments()
                                                throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database marked as being conducted and with an exception.

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

getFailedExperiments

java.util.List<ExperimentDBEntry> getFailedExperiments(java.util.Map<java.lang.String,java.lang.Object> fieldFilter)
                                                throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database marked as being conducted and with an exception and with the attribute values specified as in the map.

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

getOpenExperiments

java.util.List<ExperimentDBEntry> getOpenExperiments()
                                              throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database that have not been started yet.

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

getRandomOpenExperiments

java.util.List<ExperimentDBEntry> getRandomOpenExperiments(int limit)
                                                    throws ExperimentDBInteractionFailedException

Returns a list of all experiments contained in the database that have not been started yet.

Parameters:

limit - Maximum number of open experiments that should be returned

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

startNextExperiment

java.util.Optional<ExperimentDBEntry> startNextExperiment(java.lang.String executorInfo)
                                                   throws ExperimentDBInteractionFailedException

Picks an unstarted experiment, marks it as started and returns it. These operations happen atomically, so if a experiment is returned, then ownership on it can be assumed. If no experiment is returned, i.e. an empty optional, then no experiment is remaining.

Parameters:

executorInfo - The identifier of the executor who evaluates this experiment; important for tracking of experiments in compute centers

Returns:

A started experiment if there are any left, or else an empty optional.

Throws:

ExperimentDBInteractionFailedException

getRunningExperiments

java.util.List<ExperimentDBEntry> getRunningExperiments()
                                                 throws ExperimentDBInteractionFailedException

Returns a list of all experiments that are currently being conducted.

Returns:

List of all experiments conducted so far

Throws:

ExperimentDBInteractionFailedException

getExperimentWithId

ExperimentDBEntry getExperimentWithId(int id)
                               throws ExperimentDBInteractionFailedException

Gets the experiment with the given id.

Parameters:

id -

Returns:

Throws:

ExperimentDBInteractionFailedException

createAndGetExperiment

ExperimentDBEntry createAndGetExperiment(Experiment experiment)
                                  throws ExperimentDBInteractionFailedException,
                                         ExperimentAlreadyExistsInDatabaseException

Creates a new experiment entry and returns it.

Parameters:

experiment -

Returns:

The id of the created experiment

Throws:

ExperimentDBInteractionFailedException

ExperimentAlreadyExistsInDatabaseException

createOrGetExperiments

java.util.List<ExperimentDBEntry> createOrGetExperiments(java.util.List<Experiment> experiments)
                                                  throws ExperimentDBInteractionFailedException,
                                                         ExperimentAlreadyExistsInDatabaseException

Creates or fetches the experiment entries from the database. The "or" is exclusive, i.e. that if any entry exist it won't be created. In comparison to other createAndGet methods, this doesn't throw a ExperimentAlreadyExistsInDatabaseException.

Parameters:

experiments - the experiments to be created

Returns:

The id of the created experiment

Throws:

ExperimentDBInteractionFailedException

ExperimentAlreadyExistsInDatabaseException

startExperiment

void startExperiment(ExperimentDBEntry exp,
                     java.lang.String executorInfo)
              throws ExperimentAlreadyStartedException,
                     ExperimentUpdateFailedException

Starts the given experiment

Parameters:

exp - The experiment that is started on the current machine

executorInfo - The identifier of the executor who evaluates this experiment; important for tracking of experiments in compute centers

Throws:

ExperimentUpdateFailedException

ExperimentAlreadyStartedException

updateExperiment

void updateExperiment(ExperimentDBEntry exp,
                      java.util.Map<java.lang.String,? extends java.lang.Object> values)
               throws ExperimentUpdateFailedException

Updates non-keyfield values of the experiment.

Parameters:

exp - The experiment entry in the database

values - A key-value store where keys are names of result fields. The values will be associated to each key in the database.

Throws:

ExperimentUpdateFailedException

updateExperimentConditionally

boolean updateExperimentConditionally(ExperimentDBEntry exp,
                                      java.util.Map<java.lang.String,java.lang.String> conditions,
                                      java.util.Map<java.lang.String,? extends java.lang.Object> values)
                               throws ExperimentUpdateFailedException

Throws:

ExperimentUpdateFailedException

finishExperiment

void finishExperiment(ExperimentDBEntry exp)
               throws ExperimentDBInteractionFailedException

Signals that an experiment has been finished successfully. A corresponding timestamp will be attached to the experiment entry.

Parameters:

exp -

Throws:

ExperimentDBInteractionFailedException

finishExperiment

void finishExperiment(ExperimentDBEntry exp,
                      java.lang.Throwable errror)
               throws ExperimentDBInteractionFailedException

Signals that an experiment has failed with an exception. The timestamp and the exception will be stored with the experiment.

Parameters:

exp - Experiment to be marked as finished

errror - If not null, the experiment

Throws:

ExperimentDBInteractionFailedException

deleteExperiment

void deleteExperiment(ExperimentDBEntry exp)
               throws ExperimentDBInteractionFailedException

Deletes an experiment from the database

Parameters:

exp - Experiment to be deleted

Throws:

ExperimentDBInteractionFailedException

deleteDatabase

void deleteDatabase()
             throws ExperimentDBInteractionFailedException

Deletes everything known to the experiment database. Note that database is understood as an abstract term. In a true database, this could just be a table.

Throws:

ExperimentDBInteractionFailedException

hasExperimentStarted

boolean hasExperimentStarted(ExperimentDBEntry exp)
                      throws ExperimentDBInteractionFailedException

Checks if the given experiment has been started already.

Parameters:

exp - Experiment used for the query.

Returns:

true iff experiment has been marked as started.

Throws:

ExperimentDBInteractionFailedException