Package weka.experiment

# Class InstanceQuery

java.lang.Object
weka.experiment.DatabaseUtils
weka.experiment.InstanceQuery

All Implemented Interfaces:
  `Serializable`, `OptionHandler`, `RevisionHandler`, `InstanceQueryAdapter`

public class InstanceQuery extends DatabaseUtils implements OptionHandler, InstanceQueryAdapter
Convert the results of a database query into instances. 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

Command line use just outputs the instances to System.out.

Valid options are:

     -Q <query>
      SQL query to execute.

     -S
      Return sparse rather than normal instances.

     -U <username>
      The username to use for connecting.

     -P <password>
      The password to use for connecting.

     -D
      Enables debug output.

Version:
  $Revision: 11885 $
Author:
  Len Trigg (trigg@cs.waikato.ac.nz)
See Also:
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class weka.experiment.DatabaseUtils

  `BOOL, BYTE, DATE, DOUBLE, EXP_INDEX_TABLE, EXP_RESULT_COL, EXP_RESULT_PREFIX, EXP_SETUP_COL, EXP_TYPE_COL, FLOAT, INTEGER, LONG, PROPERTY_FILE, SHORT, STRING, TEXT, TIME, TIMESTAMP`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `InstanceQuery()`
  Sets up the database drivers

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `customPropsFileTipText()`
  The tip text for this property.
  `File`
  `getCustomPropsFile()`
  Returns the custom properties file in use, if any.
  `String[]`
  `getOptions()`
  Gets the current settings of InstanceQuery
  `String`
  `getQuery()`
  Get the query to execute against the database
  `String`
  `getRevision()`
  Returns the revision string.
  `boolean`
  `getSparseData()`
  Gets whether data is to be returned as a set of sparse instances
  `Enumeration<Option>`
  `listOptions()`
  Returns an enumeration describing the available options
  `static void`
  `main(String[] args)`
  Test the class from the command line.
  `String`
  `queryTipText()`
  Returns the tip text for this property
  `Instances`
  `retrieveInstances()`
  Makes a database query using the query set through the -Q option to convert a table into a set of instances
  `Instances`
  `retrieveInstances(String query)`
  Makes a database query to convert a table into a set of instances
  `static Instances`
  `retrieveInstances(InstanceQueryAdapter adapter, ResultSet rs)`
  `void`
  `setCustomPropsFile(File value)`
  Sets the custom properties file to use.
  `void`
  `setOptions(String[] options)`
  Parses a given list of options.
  `void`
  `setQuery(String q)`
  Set the query to execute against the database
  `void`
  `setSparseData(boolean s)`
  Sets whether data should be encoded as sparse instances
  `String`
  `sparseDataTipText()`
  Returns the tip text for this property

  ### Methods inherited from class weka.experiment.DatabaseUtils

  `arrayToString, attributeCaseFix, close, close, connectToDatabase, createExperimentIndex, createExperimentIndexEntry, createResultsTable, databaseURLTipText, debugTipText, disconnectFromDatabase, execute, experimentIndexExists, getDatabaseURL, getDebug, getKeywords, getKeywordsMaskChar, getPassword, getResultFromTable, getResultSet, getResultsTableName, getSupportedCursorScrollType, getUsername, initialize, initialize, isConnected, isCursorScrollable, isCursorScrollSensitive, isKeyword, maskKeyword, passwordTipText, processKeyString, putResultInTable, select, setDatabaseURL, setDebug, setKeywords, setKeywordsMaskChar, setPassword, setUsername, tableExists, translateDBColumnType, typeName, update, usernameTipText`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface weka.experiment.InstanceQueryAdapter

  `attributeCaseFix, getDebug, translateDBColumnType`

- ## Constructor Details

  - ### InstanceQuery

    public InstanceQuery() throws Exception
    Sets up the database drivers
    Throws:
      `Exception` - if an error occurs

- ## Method Details

  - ### listOptions

    public Enumeration<Option> listOptions()
    Returns an enumeration describing the available options

    Specified by:
      `listOptions` in interface `OptionHandler`
    Returns:
      an enumeration of all options

  - ### setOptions

    public void setOptions(String[] options) throws Exception
    Parses a given list of options. Valid options are:

         -Q <query>
          SQL query to execute.

         -S
          Return sparse rather than normal instances.

         -U <username>
          The username to use for connecting.

         -P <password>
          The password to use for connecting.

         -D
          Enables debug output.

    Specified by:
      `setOptions` in interface `OptionHandler`
    Parameters:
      `options` - the list of options as an array of strings
    Throws:
      `Exception` - if an option is not supported

  - ### queryTipText

    public String queryTipText()
    Returns the tip text for this property
    Returns:
      tip text for this property suitable for displaying in the explorer/experimenter gui

  - ### setQuery

    public void setQuery(String q)
    Set the query to execute against the database
    Parameters:
      `q` - the query to execute

  - ### getQuery

    public String getQuery()
    Get the query to execute against the database
    Returns:
      the query

  - ### sparseDataTipText

    public String sparseDataTipText()
    Returns the tip text for this property
    Returns:
      tip text for this property suitable for displaying in the explorer/experimenter gui

  - ### setSparseData

    public void setSparseData(boolean s)
    Sets whether data should be encoded as sparse instances
    Parameters:
      `s` - true if data should be encoded as a set of sparse instances

  - ### getSparseData

    public boolean getSparseData()
    Gets whether data is to be returned as a set of sparse instances
    Specified by:
      `getSparseData` in interface `InstanceQueryAdapter`
    Returns:
      true if data is to be encoded as sparse instances

  - ### setCustomPropsFile

    public void setCustomPropsFile(File value)
    Sets the custom properties file to use.
    Parameters:
      `value` - the custom props file to load database parameters from, use null or directory to disable custom properties.
    See Also:
      - `DatabaseUtils.initialize(File)`

  - ### getCustomPropsFile

    public File getCustomPropsFile()
    Returns the custom properties file in use, if any.
    Returns:
      the custom props file, null if none used

  - ### customPropsFileTipText

    public String customPropsFileTipText()
    The tip text for this property.
    Returns:
      the tip text

  - ### getOptions

    public String[] getOptions()
    Gets the current settings of InstanceQuery
    Specified by:
      `getOptions` in interface `OptionHandler`
    Returns:
      an array of strings suitable for passing to setOptions()

  - ### retrieveInstances

    public Instances retrieveInstances() throws Exception
    Makes a database query using the query set through the -Q option to convert a table into a set of instances
    Returns:
      the instances contained in the result of the query
    Throws:
      `Exception` - if an error occurs

  - ### retrieveInstances

    public static Instances retrieveInstances(InstanceQueryAdapter adapter, ResultSet rs) throws Exception
    Throws:
      `Exception`

  - ### retrieveInstances

    public Instances retrieveInstances(String query) throws Exception
    Makes a database query to convert a table into a set of instances
    Parameters:
      `query` - the query to convert to instances
    Returns:
      the instances contained in the result of the query, NULL if the SQL query doesn't return a ResultSet, e.g., DELETE/INSERT/UPDATE
    Throws:
      `Exception` - if an error occurs

  - ### main

    public static void main(String[] args)
    Test the class from the command line. The instance query should be specified with -Q sql_query
    Parameters:
      `args` - contains options for the instance query

  - ### getRevision

    public String getRevision()
    Returns the revision string.
    Specified by:
      `getRevision` in interface `RevisionHandler`
    Overrides:
      `getRevision` in class `DatabaseUtils`
    Returns:
      the revision