org.biospice.sql.agent
Interface DBAgent

All Superinterfaces:

Agent

public interface DBAgent

extends Agent

Instances implementing this interface are OAA database (server) agents. The OAA solvables for DBAgent instances are described in the Field Detail documentation for the solvable functor names.

Java properties are used to configure DBAgent instances. An agent properties file (PostgreSQL example) might look like this:

 biospice.dbagent.jdbc.driver = org.postgresql.Driver
 biospice.dbagent.jdbc.url = jdbc:postgresql://machine/dbname
 biospice.dbagent.user.name = jdoe
 biospice.dbagent.user.password = myPassword
 

See Also:

DBAgentMain, DBAgentFactory

Field Summary

static String	AGENT_NAME The name of this agent.
static String	ALL The functor for the all solvable.
static String	CLOSE The functor for the close solvable.
static String	COLUMN_COUNT The functor for the columnCount solvable.
static String	COLUMN_NAMES The functor for the columnNames solvable.
static String	COLUMN_TYPES The functor for the columnTypes solvable.
static String	DBAGENT_JDBC_DRIVER_PROPERTY The Properties key identifying the JDBC Driver class for the DBAgent to load when connecting to the database.
static String	DBAGENT_JDBC_URL_PROPERTY The Properties key identifying the JDBC URL for the DBAgent to use when connecting to the database.
static String	DBAGENT_USER_NAME_PROPERTY The Properties key identifying the user name for the DBAgent to use when connecting to the database.
static String	DBAGENT_USER_PASSWORD_PROPERTY The Properties key identifying the user password for the DBAgent to use when connecting to the database.
static String	EXECUTE_QUERY The functor for the executeQuery solvable.
static String	LAST_EXCEPTION The functor for the lastException solvable.
static String	NEXT The functor for the next solvable.
static String	NEXT_N The functor for the nextN solvable.

Fields inherited from interface org.biospice.agent.Agent

ADDRESS_PARAM_NAME, BLOCK_FALSE_PARAM, BLOCK_PARAM_NAME, BLOCK_TRUE_PARAM, DC_FALSE_PARAM, DC_PARAM_NAME, DC_TRUE_PARAM, DEFAULT_AGENT_LOGGER, iclEmptyList, USED_DC_NAME, USED_DC_PARAM

Methods inherited from interface org.biospice.agent.Agent

facilitatorConnect, facilitatorDisconnect, getAgentCapabilities, getAgentName, getBlocking, getLibOaa, getLogger, getSolvingAgent, getUseDirectConnect, interpret, oaaDoEventCallback, setBlocking, setLogger, setSolvingAgent, setUseDirectConnect, solve, solve, start

Field Detail

AGENT_NAME

public static final String AGENT_NAME

The name of this agent.

See Also:

Constant Field Values

EXECUTE_QUERY

public static final String EXECUTE_QUERY

The functor for the executeQuery solvable. The complete solvable is:

executeQuery(SQLQuery, ResultSetID, Status)

Clients must replace SQLQuery with a SQL query string in single quotes (Prolog string). On return, ResultSetID will contain a string identifier for use when invoking other DBAgent solvables.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status, information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

COLUMN_COUNT

public static final String COLUMN_COUNT

The functor for the columnCount solvable. The complete solvable is:

columnCount(ResultSetID, NumberOfColumns, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request. On return, NumberOfColumns will be an IclInt containing the integer number of columns for the result set.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for NumberOfColumns is undefined. Information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

COLUMN_NAMES

public static final String COLUMN_NAMES

The functor for the columnNames solvable. The complete solvable is:

columnNames(ResultSetID, ColumnNames, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request. On return, ColumnNames will be an IclList containing the string names of the result set columns.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for ColumnNames is undefined. Information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

COLUMN_TYPES

public static final String COLUMN_TYPES

The functor for the columnTypes solvable. The complete solvable is:

columnTypes(ResultSetID, ColumnTypes, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request. On return, ColumnTypes will be an IclList containing the string names of the result set column types.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for ColumnTypes is undefined. Information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

NEXT

public static final String NEXT

The functor for the next solvable. The complete solvable is:

next(ResultSetID, Row, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request. On return, Row will be an IclList containing the string values of the next row in the result set.

If there are no more rows in the result set an empty list ([]) is returned AND the ResultSetID used in the request is no longer valid.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for Row is undefined. Information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

NEXT_N

public static final String NEXT_N

The functor for the nextN solvable. The complete solvable is:

nextN(ResultSetID, NumberOfRows, Rows, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request, and NumberOfRows is the number of rows requested. On return, Rows will be an IclList containing IclLists where each sublist is a row from the result set.

If the end of the result set is reached then an empty list ([]) is returned as the last sublist AND the ResultSetID used in the request is no longer valid. Note that nextN may return fewer than the NumberOfRows requested when the end of the result set is encountered.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for Rows is undefined. Information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

ALL

public static final String ALL

The functor for the all solvable. The complete solvable is:

all(ResultSetID, AllRemainingRows, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request. On return, AllRemainingRows will be an IclList containing IclLists where each sublist is a row from the result set. The last sublist will be an empty list ([]). When the result set is large this can be a time-consuming operation and it should be used with caution.

If there are no more rows in the result set an empty list ([]) is returned AND the ResultSetID used in the request is no longer valid.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for AllRemainingRows is undefined. Information about the error can be obtained by immediately invoking the lastException solvable.

See Also:

Constant Field Values

CLOSE

public static final String CLOSE

The functor for the close solvable. The complete solvable is:

close(ResultSetIDToClose, Status)

The ResultSetIDToClose parameter must be a value obtained from an executeQuery solution request. This solvable returns only a Status value but has the important side effect of releasing resources associated with the supplied ResultSetIDToClose.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status, information about the error can be obtained by immediately invoking the lastException solvable.

IMPORTANT: Failure to close results sets may lead to performance degradation, memory exhaustion, and/or database connectivity failures such as "maximum open cursors exceeded" errors.

See Also:

Constant Field Values

LAST_EXCEPTION

public static final String LAST_EXCEPTION

The functor for the lastException solvable. The complete solvable is:

lastException(ResultSetID, ExceptionMessage, Status)

The ResultSetID parameter must be a value obtained from an executeQuery solution request. On return, ExceptionMessage will be a string message describing the most recent error associated with the supplied ResultSetID.

If an error occurs, Status will be an IclInt containing a non-zero integer. In cases of non-zero status the value returned for ExceptionMessage is undefined. Information about the error can be obtained by immediately re-invoking this solvable.

See Also:

Constant Field Values

DBAGENT_JDBC_DRIVER_PROPERTY

public static final String DBAGENT_JDBC_DRIVER_PROPERTY

The Properties key identifying the JDBC Driver class for the DBAgent to load when connecting to the database.

See Also:

Properties, Constant Field Values

DBAGENT_JDBC_URL_PROPERTY

public static final String DBAGENT_JDBC_URL_PROPERTY

The Properties key identifying the JDBC URL for the DBAgent to use when connecting to the database.

See Also:

DriverManager, DriverManager.getConnection(String url, String user, String password), Properties, Constant Field Values

DBAGENT_USER_NAME_PROPERTY

public static final String DBAGENT_USER_NAME_PROPERTY

The Properties key identifying the user name for the DBAgent to use when connecting to the database. Depending on how a particular database is configured, the user name may be optional.

See Also:

DriverManager, DriverManager.getConnection(String url, String user, String password), Properties, Constant Field Values

DBAGENT_USER_PASSWORD_PROPERTY

public static final String DBAGENT_USER_PASSWORD_PROPERTY

The Properties key identifying the user password for the DBAgent to use when connecting to the database. Depending on how a particular database is configured, the user password may be optional.

See Also:

DriverManager, DriverManager.getConnection(String url, String user, String password), Properties, Constant Field Values