## milk.experiment
Class MIDatabaseUtils

    java.lang.Object
      |
      +--milk.experiment.MIDatabaseUtils

All Implemented Interfaces:
  java.io.Serializable

Direct Known Subclasses:
  MIDatabaseResultListener, MIInstanceQuery

public class MIDatabaseUtils
extends java.lang.Object
implements java.io.Serializable

DatabaseUtils provides utility functions for accessing the experiment database. The jdbc driver and database to be used default to "jdbc.idbDriver" and "jdbc:idb=experiments.prp". These may be changed by creating a java properties file called DatabaseUtils.props in user.home or the current directory. eg:

``

     jdbcDriver=jdbc.idbDriver
     jdbcURL=jdbc:idb=experiments.prp

See Also:
  Serialized Form

Field Summary
`protected static java.util.Vector` `DRIVERS` Holds the jdbc drivers to be used (only to stop them being gc'ed)
`static java.lang.String` `EXP_INDEX_TABLE` The name of the table containing the index to experiments
`static java.lang.String` `EXP_RESULT_COL` The name of the column containing the results table name
`static java.lang.String` `EXP_RESULT_PREFIX` The prefix for result table names
`static java.lang.String` `EXP_SETUP_COL` The name of the column containing the experiment setup (parameters)
`static java.lang.String` `EXP_TYPE_COL` The name of the column containing the experiment type (ResultProducer)
`protected java.sql.Connection` `m_Connection` The database connection
`protected java.lang.String` `m_DatabaseURL` Database URL
`protected boolean` `m_Debug` True if debugging output should be printed
`protected java.sql.Statement` `m_Statement` The statement used for database queries
`protected static java.util.Properties` `PROPERTIES` Properties associated with the database connection
`protected static java.lang.String` `PROPERTY_FILE` The name of the properties file

Constructor Summary
`MIDatabaseUtils()` Sets up the database drivers

Method Summary
`static java.lang.String` `arrayToString(java.lang.Object[] array)` Converts an array of objects to a string by inserting a space between each element.
`void` `connectToDatabase()` Opens a connection to the database
`void` `createExperimentIndex()` Attempts to create the experiment index table
`java.lang.String` `createExperimentIndexEntry(MIResultProducer rp)` Attempts to insert a results entry for the table into the experiment index.
`java.lang.String` `createResultsTable(MIResultProducer rp, java.lang.String tableName)` Creates a results table for the supplied result producer.
`java.lang.String` `databaseURLTipText()` Returns the tip text for this property
`void` `disconnectFromDatabase()` Closes the connection to the database.
`boolean` `execute(java.lang.String query)` Executes a SQL query.
`boolean` `experimentIndexExists()` Returns true if the experiment index exists.
`java.lang.String` `getDatabaseURL()` Get the value of DatabaseURL.
`java.lang.Object[]` `getResultFromTable(java.lang.String tableName, MIResultProducer rp, java.lang.Object[] key)` Executes a database query to extract a result for the supplied key from the database.
`java.sql.ResultSet` `getResultSet()` Gets the results generated by a previous query.
`java.lang.String` `getResultsTableName(MIResultProducer rp)` Gets the name of the experiment table that stores results from a particular ResultProducer.
`boolean` `isConnected()` Returns true if a database connection is active.
`protected boolean` `isKeyInTable(java.lang.String tableName, MIResultProducer rp, java.lang.Object[] key)` Executes a database query to see whether a result for the supplied key is already in the database.
`void` `putResultInTable(java.lang.String tableName, MIResultProducer rp, java.lang.Object[] key, java.lang.Object[] result)` Executes a database query to insert a result for the supplied key into the database.
`void` `setDatabaseURL(java.lang.String newDatabaseURL)` Set the value of DatabaseURL.
`boolean` `tableExists(java.lang.String tableName)` Checks that a given table exists.
`static java.lang.String` `typeName(int type)` Returns the name associated with a SQL type.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### EXP_INDEX_TABLE

    public static final java.lang.String EXP_INDEX_TABLE

  The name of the table containing the index to experiments

  See Also:
    Constant Field Values

### EXP_TYPE_COL

    public static final java.lang.String EXP_TYPE_COL

  The name of the column containing the experiment type (ResultProducer)

  See Also:
    Constant Field Values

### EXP_SETUP_COL

    public static final java.lang.String EXP_SETUP_COL

  The name of the column containing the experiment setup (parameters)

  See Also:
    Constant Field Values

### EXP_RESULT_COL

    public static final java.lang.String EXP_RESULT_COL

  The name of the column containing the results table name

  See Also:
    Constant Field Values

### EXP_RESULT_PREFIX

    public static final java.lang.String EXP_RESULT_PREFIX

  The prefix for result table names

  See Also:
    Constant Field Values

### PROPERTY_FILE

    protected static java.lang.String PROPERTY_FILE

  The name of the properties file

### DRIVERS

    protected static java.util.Vector DRIVERS

  Holds the jdbc drivers to be used (only to stop them being gc'ed)

### PROPERTIES

    protected static java.util.Properties PROPERTIES

  Properties associated with the database connection

### m_DatabaseURL

    protected java.lang.String m_DatabaseURL

  Database URL

### m_Connection

    protected java.sql.Connection m_Connection

  The database connection

### m_Statement

    protected java.sql.Statement m_Statement

  The statement used for database queries

### m_Debug

    protected boolean m_Debug

  True if debugging output should be printed

Constructor Detail

### MIDatabaseUtils

    public MIDatabaseUtils()
                    throws java.lang.Exception

  Sets up the database drivers

Throws:
  `java.lang.Exception` - if an error occurs

Method Detail

### arrayToString

    public static java.lang.String arrayToString(java.lang.Object[] array)

  Converts an array of objects to a string by inserting a space between each element. Null elements are printed as ?

  Parameters:
    `array` - the array of objects
  Returns:
    a value of type 'String'

### typeName

    public static java.lang.String typeName(int type)

  Returns the name associated with a SQL type.

  Parameters:
    `type` - the SQL type
  Returns:
    the name of the type

### databaseURLTipText

    public java.lang.String databaseURLTipText()

  Returns the tip text for this property

  Returns:
    tip text for this property suitable for displaying in the explorer/experimenter gui

### getDatabaseURL

    public java.lang.String getDatabaseURL()

  Get the value of DatabaseURL.

  Returns:
    Value of DatabaseURL.

### setDatabaseURL

    public void setDatabaseURL(java.lang.String newDatabaseURL)

  Set the value of DatabaseURL.

  Parameters:
    `newDatabaseURL` - Value to assign to DatabaseURL.

### connectToDatabase

    public void connectToDatabase()
                           throws java.lang.Exception

  Opens a connection to the database

  Throws:
    `java.lang.Exception` - if an error occurs

### disconnectFromDatabase

    public void disconnectFromDatabase()
                                throws java.lang.Exception

  Closes the connection to the database.

  Throws:
    `java.lang.Exception` - if an error occurs

### isConnected

    public boolean isConnected()

  Returns true if a database connection is active.

  Returns:
    a value of type 'boolean'

### execute

    public boolean execute(java.lang.String query)
                    throws java.sql.SQLException

  Executes a SQL query.

  Parameters:
    `query` - the SQL query
  Returns:
    true if the query generated results
  Throws:
    `java.sql.SQLException` - if an error occurs

### getResultSet

    public java.sql.ResultSet getResultSet()
                                    throws java.sql.SQLException

  Gets the results generated by a previous query.

  Returns:
    the result set.
  Throws:
    `java.sql.SQLException` - if an error occurs

### tableExists

    public boolean tableExists(java.lang.String tableName)
                        throws java.lang.Exception

  Checks that a given table exists.

  Parameters:
    `tableName` - the name of the table to look for.
  Returns:
    true if the table exists.
  Throws:
    `java.lang.Exception` - if an error occurs.

### isKeyInTable

    protected boolean isKeyInTable(java.lang.String tableName,
                                   MIResultProducer rp,
                                   java.lang.Object[] key)
                            throws java.lang.Exception

  Executes a database query to see whether a result for the supplied key is already in the database.

  Parameters:
    `tableName` - the name of the table to search for the key in
    `rp` - the ResultProducer who will generate the result if required
    `key` - the key for the result
  Returns:
    true if the result with that key is in the database already
  Throws:
    `java.lang.Exception` - if an error occurs

### getResultFromTable

    public java.lang.Object[] getResultFromTable(java.lang.String tableName,
                                                 MIResultProducer rp,
                                                 java.lang.Object[] key)
                                          throws java.lang.Exception

  Executes a database query to extract a result for the supplied key from the database.

  Parameters:
    `tableName` - the name of the table where the result is stored
    `rp` - the ResultProducer who will generate the result if required
    `key` - the key for the result
  Returns:
    true if the result with that key is in the database already
  Throws:
    `java.lang.Exception` - if an error occurs

### putResultInTable

    public void putResultInTable(java.lang.String tableName,
                                 MIResultProducer rp,
                                 java.lang.Object[] key,
                                 java.lang.Object[] result)
                          throws java.lang.Exception

  Executes a database query to insert a result for the supplied key into the database.

  Parameters:
    `tableName` - the name of the table where the result is stored
    `rp` - the ResultProducer who will generate the result if required
    `key` - the key for the result
    `result` - the result to store
  Returns:
    true if the result with that key is in the database already
  Throws:
    `java.lang.Exception` - if an error occurs

### experimentIndexExists

    public boolean experimentIndexExists()
                                  throws java.lang.Exception

  Returns true if the experiment index exists.

  Returns:
    true if the index exists
  Throws:
    `java.lang.Exception` - if an error occurs

### createExperimentIndex

    public void createExperimentIndex()
                               throws java.lang.Exception

  Attempts to create the experiment index table

  Throws:
    `java.lang.Exception` - if an error occurs.

### createExperimentIndexEntry

    public java.lang.String createExperimentIndexEntry(MIResultProducer rp)
                                                throws java.lang.Exception

  Attempts to insert a results entry for the table into the experiment index.

  Parameters:
    `rp` - the ResultProducer generating the results
  Returns:
    the name of the created results table
  Throws:
    `java.lang.Exception` - if an error occurs.

### getResultsTableName

    public java.lang.String getResultsTableName(MIResultProducer rp)
                                         throws java.lang.Exception

  Gets the name of the experiment table that stores results from a particular ResultProducer.

  Parameters:
    `rp` - the ResultProducer
  Returns:
    the name of the table where the results for this ResultProducer are stored, or null if there is no table for this ResultProducer.
  Throws:
    `java.lang.Exception` - if an error occurs

### createResultsTable

    public java.lang.String createResultsTable(MIResultProducer rp,
                                               java.lang.String tableName)
                                        throws java.lang.Exception

  Creates a results table for the supplied result producer.

  Parameters:
    `rp` - the ResultProducer generating the results
    `tableName` - the name of the resultsTable
  Returns:
    the name of the created results table
  Throws:
    `java.lang.Exception` - if an error occurs.