## milk.experiment
Class MIDatabaseResultListener

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

All Implemented Interfaces:
  MIResultListener, java.io.Serializable

public class MIDatabaseResultListener
extends MIDatabaseUtils
implements MIResultListener

DatabaseResultListener takes the results from a ResultProducer and submits them to a central database.

See Also:
  Serialized Form

Field Summary
`protected weka.core.FastVector` `m_Cache` Stores the cached values
`protected java.lang.Object[]` `m_CacheKey` Stores the key for which the cache is valid
`protected int` `m_CacheKeyIndex` Stores the index of the key column holding the cache key data
`protected java.lang.String` `m_CacheKeyName` Holds the name of the key field to cache upon, or null if no caching
`protected boolean` `m_Debug` True if debugging output should be printed
`protected MIResultProducer` `m_ResultProducer` The ResultProducer to listen to
`protected java.lang.String` `m_ResultsTableName` The name of the current results table

Fields inherited from class milk.experiment.MIDatabaseUtils
`DRIVERS, EXP_INDEX_TABLE, EXP_RESULT_COL, EXP_RESULT_PREFIX, EXP_SETUP_COL, EXP_TYPE_COL, m_Connection, m_DatabaseURL, m_Statement, PROPERTIES, PROPERTY_FILE`

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

Method Summary
`void` `acceptResult(MIResultProducer rp, java.lang.Object[] key, java.lang.Object[] result)` Submit the result to the appropriate table of the database
`java.lang.String` `cacheKeyNameTipText()` Returns the tip text for this property
`java.lang.String[]` `determineColumnConstraints(MIResultProducer rp)` Determines if there are any constraints (imposed by the destination) on any additional measures produced by resultProducers.
`java.lang.String` `getCacheKeyName()` Get the value of CacheKeyName.
`java.lang.String` `globalInfo()` Returns a string describing this result listener
`protected boolean` `isCacheValid(java.lang.Object[] key)` Checks whether the current cache contents are valid for the supplied key.
`protected boolean` `isKeyInCache(MIResultProducer rp, java.lang.Object[] key)` Returns true if the supplied key is in the key cache (and thus we do not need to execute a database query).
`boolean` `isResultRequired(MIResultProducer rp, java.lang.Object[] key)` Always says a result is required.
`protected void` `loadCache(MIResultProducer rp, java.lang.Object[] key)` Executes a database query to fill the key cache
`void` `postProcess(MIResultProducer rp)` Perform any postprocessing.
`void` `preProcess(MIResultProducer rp)` Prepare for the results to be received.
`void` `setCacheKeyName(java.lang.String newCacheKeyName)` Set the value of CacheKeyName.
`protected void` `updateResultsTableName(MIResultProducer rp)` Determines the table name that results will be inserted into.

Methods inherited from class milk.experiment.MIDatabaseUtils
`arrayToString, connectToDatabase, createExperimentIndex, createExperimentIndexEntry, createResultsTable, databaseURLTipText, disconnectFromDatabase, execute, experimentIndexExists, getDatabaseURL, getResultFromTable, getResultSet, getResultsTableName, isConnected, isKeyInTable, putResultInTable, setDatabaseURL, tableExists, typeName`

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

Field Detail

### m_ResultProducer

    protected MIResultProducer m_ResultProducer

  The ResultProducer to listen to

### m_ResultsTableName

    protected java.lang.String m_ResultsTableName

  The name of the current results table

### m_Debug

    protected boolean m_Debug

  True if debugging output should be printed

### m_CacheKeyName

    protected java.lang.String m_CacheKeyName

  Holds the name of the key field to cache upon, or null if no caching

### m_CacheKeyIndex

    protected int m_CacheKeyIndex

  Stores the index of the key column holding the cache key data

### m_CacheKey

    protected java.lang.Object[] m_CacheKey

  Stores the key for which the cache is valid

### m_Cache

    protected weka.core.FastVector m_Cache

  Stores the cached values

Constructor Detail

### MIDatabaseResultListener

    public MIDatabaseResultListener()
                             throws java.lang.Exception

  Sets up the database drivers

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

Method Detail

### globalInfo

    public java.lang.String globalInfo()

  Returns a string describing this result listener

  Returns:
    a description of the result listener suitable for displaying in the explorer/experimenter gui

### preProcess

    public void preProcess(MIResultProducer rp)
                    throws java.lang.Exception

  Prepare for the results to be received.

  Specified by:
    `preProcess` in interface `MIResultListener`
  Parameters:
    `rp` - the ResultProducer that will generate the results
  Throws:
    `java.lang.Exception` - if an error occurs during preprocessing.

### postProcess

    public void postProcess(MIResultProducer rp)
                     throws java.lang.Exception

  Perform any postprocessing. When this method is called, it indicates that no more results will be sent that need to be grouped together in any way.

  Specified by:
    `postProcess` in interface `MIResultListener`
  Parameters:
    `rp` - the ResultProducer that generated the results
  Throws:
    `java.lang.Exception` - if an error occurs

### determineColumnConstraints

    public java.lang.String[] determineColumnConstraints(MIResultProducer rp)
                                                  throws java.lang.Exception

  Determines if there are any constraints (imposed by the destination) on any additional measures produced by resultProducers. Null should be returned if there are NO constraints, otherwise a list of column names should be returned as an array of Strings. In the case of DatabaseResultListener, the structure of an existing database will impose constraints.

  Specified by:
    `determineColumnConstraints` in interface `MIResultListener`
  Parameters:
    `rp` - the ResultProducer to which the constraints will apply
  Returns:
    an array of column names to which resutltProducer's results will be restricted.
  Throws:
    `java.lang.Exception` - if an error occurs.

### acceptResult

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

  Submit the result to the appropriate table of the database

  Specified by:
    `acceptResult` in interface `MIResultListener`
  Parameters:
    `rp` - the ResultProducer that generated the result
    `key` - The key for the results.
    `result` - The actual results.
  Throws:
    `java.lang.Exception` - if the result couldn't be sent to the database

### isResultRequired

    public boolean isResultRequired(MIResultProducer rp,
                                    java.lang.Object[] key)
                             throws java.lang.Exception

  Always says a result is required. If this is the first call, prints out the header for the Database output.

  Specified by:
    `isResultRequired` in interface `MIResultListener`
  Parameters:
    `rp` - the ResultProducer wanting to generate the result
    `key` - The key for which a result may be needed.
  Returns:
    true if the result should be calculated.
  Throws:
    `java.lang.Exception` - if the database couldn't be queried

### updateResultsTableName

    protected void updateResultsTableName(MIResultProducer rp)
                                   throws java.lang.Exception

  Determines the table name that results will be inserted into. If required: a connection will be opened, an experiment index table created, and the results table created.

  Parameters:
    `rp` - the ResultProducer
  Throws:
    `java.lang.Exception` - if an error occurs

### cacheKeyNameTipText

    public java.lang.String cacheKeyNameTipText()

  Returns the tip text for this property

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

### getCacheKeyName

    public java.lang.String getCacheKeyName()

  Get the value of CacheKeyName.

  Returns:
    Value of CacheKeyName.

### setCacheKeyName

    public void setCacheKeyName(java.lang.String newCacheKeyName)

  Set the value of CacheKeyName.

  Parameters:
    `newCacheKeyName` - Value to assign to CacheKeyName.

### isCacheValid

    protected boolean isCacheValid(java.lang.Object[] key)

  Checks whether the current cache contents are valid for the supplied key.

  Parameters:
    `key` - the results key
  Returns:
    true if the cache contents are valid for the key given

### isKeyInCache

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

  Returns true if the supplied key is in the key cache (and thus we do not need to execute a database query).

  Parameters:
    `rp` - the ResultProducer the key belongs to.
    `key` - the result key
  Returns:
    true if the key is in the key cache
  Throws:
    `java.lang.Exception` - if an error occurs

### loadCache

    protected void loadCache(MIResultProducer rp,
                             java.lang.Object[] key)
                      throws java.lang.Exception

  Executes a database query to fill the key cache

  Parameters:
    `rp` - the ResultProducer the key belongs to
    `key` - the key
  Throws:
    `java.lang.Exception` - if an error occurs