intradoc.data
Interface Workspace

public interface Workspace

An interface that specifies methods for accessing a database. This interface specifies a fairly rich set of database query and management routines. All calls in Intradoc to a database go through an implementation of this interface.

See Also:

ResultSet

Field Summary

static int

COMPACT Used for MS Access databases to specify that the database should be compacted.

Method Summary

void	addIndex(java.lang.String table, java.lang.String[] indexCols) Adds an index used for optimizing queries.
void	addQuery(SimpleQueryInfo qInfo) Adds a parameterized query to the object that implements this interface.
void	addQueryDefs(DataResultSet rset) Adds queries from a table.
void	alterTable(java.lang.String table, FieldInfo[] addCols, java.lang.String[] dropCols, java.lang.String[] primaryKeys) Method adds and deletes columns from a database table.
void	beginTran() Starts a database transaction.
boolean	checkQuery(java.lang.String query, Parameters args) Validates that the Parameters interface supplies all the necessary parameters for the query.
void	commitTran() Commits the database transaction.
ResultSet	createResultSet(java.lang.String query, Parameters args) Executes a parameterized query that returns a result set.
ResultSet	createResultSetSQL(java.lang.String sql) Executes SQL that returns a result set.
void	createTable(java.lang.String table, FieldInfo[] cols, java.lang.String[] primaryKeys) Creates a table in the database.
void	dbManagement(int type, Parameters args) A general management or configuration function whose appropriate values for its arguments are dependent on the object that implements this interface.
void	deleteTable(java.lang.String table) Deletes a table from the database.
java.lang.String	dumpQuery(java.lang.String query, Parameters args) Creates debug dump of a query using the values supplied by the Parameters interface.
long	execute(java.lang.String function, Parameters args) Executes a parameterized query.
long	executeSQL(java.lang.String sql) Executes SQL.
FieldInfo[]	getColumnList(java.lang.String tableName) Method returns list of FieldInfo corresponding to the columns in the table.
java.lang.String[]	getPrimaryKeys(java.lang.String table) Method returns list of columns that make up the primary key.
java.lang.String	getProperty(java.lang.String key) General function that allow retreiving Workspace specific properties.
java.lang.String[]	getQueryList() Returns the names of all the parameterized queries in this Workspace.
java.lang.String[]	getQueryParameters(java.lang.String query) Lists the names of parameters that need to filled in order to execute a parameterized query.
java.lang.String[]	getTableList() Returns all table names currently in the database.
void	initConnections(int num) Initializes the Workspace object with connection attributes.
void	releaseConnection() Used to release a connection to the database back into the cache of pooled database connetions.
void	releaseConnection(java.lang.String threadName) Releases a connection from the named thread.
void	removeQuery(java.lang.String query) Removeds a parameterized query.
void	rollbackTran() Cancels a database transaction.
boolean	supportsSqlColumnChange() Method returns a value indicating whether or not a varchar column can have its length extended without recreating the entire table.
boolean	supportsSqlColumnDelete() Method returns a value indicating whether or not a column can be deleted from a database table without recreating the entire table.

Field Detail

COMPACT

public static final int COMPACT

Used for MS Access databases to specify that the database should be compacted.

See Also:

Constant Field Values

Method Detail

initConnections

public void initConnections(int num)
                     throws DataException

Initializes the Workspace object with connection attributes. This method may not create the actual connection with the database, in which case the object implementing this interface may have additional initialization routines.

Throws:

DataException - Thrown if there was an error doing the initialization.

execute

public long execute(java.lang.String function,
                    Parameters args)
             throws DataException

Executes a parameterized query. The Workspace should be initialized using the 'addQueryDefs' or 'addQuery' methods before this method is called.

Parameters:

function - The name of the parameterized query that uses '?' as place holders for arguments. Each '?' mark is associated with a lookup key as part of the definition of the parameterized query.

args - An interface through which the values to fill in the parameters of the query can be extracted.

Returns:

The number of rows in the database table affected.

Throws:

DataException - Thrown if there is an error executing the query.

See Also:

addQueryDefs(intradoc.data.DataResultSet), addQuery(intradoc.data.SimpleQueryInfo)

executeSQL

public long executeSQL(java.lang.String sql)
                throws DataException

Executes SQL.

Returns:

The number of rows affected.

Throws:

DataException - Thrown if there is an error executing the query.

createResultSet

public ResultSet createResultSet(java.lang.String query,
                                 Parameters args)
                          throws DataException

Executes a parameterized query that returns a result set.

Parameters:

args - An interface through which the values to fill in the parameters of the query can be extracted.

Returns:

A result set containing the results of the query.

Throws:

DataException - Thrown if there is an error executing the query.

See Also:

execute(java.lang.String, intradoc.data.Parameters)

createResultSetSQL

public ResultSet createResultSetSQL(java.lang.String sql)
                             throws DataException

Executes SQL that returns a result set.

Returns:

A result set containing the results of the query.

Throws:

DataException - Thrown if there is an error executing the query.

See Also:

executeSQL(java.lang.String)

beginTran

public void beginTran()
               throws DataException

Starts a database transaction. A transaction counter is incremented after the transaction starts. This has the effect of blocking other transactions that use this method from starting until this transaction is completed.

Throws:

DataException - Thrown if transaction cannot be started.

See Also:

commitTran(), rollbackTran()

commitTran

public void commitTran()
                throws DataException

Commits the database transaction.

Throws:

DataException - Thrown if transaction cannot be commited.

rollbackTran

public void rollbackTran()

Cancels a database transaction.

getQueryList

public java.lang.String[] getQueryList()

Returns the names of all the parameterized queries in this Workspace.

Returns:

An array of query names.

getTableList

public java.lang.String[] getTableList()
                                throws DataException

Returns all table names currently in the database. This list can be used to detect table name collision before making a call to 'createTable'.

Returns:

An array of table names.

Throws:

DataException - Thrown if table list cannot be retrieved.

See Also:

createTable(java.lang.String, intradoc.data.FieldInfo[], java.lang.String[])

getColumnList

public FieldInfo[] getColumnList(java.lang.String tableName)
                          throws DataException

Method returns list of FieldInfo corresponding to the columns in the table.

Parameters:

tableName -

Returns:

List of column description

Throws:

DataException

createTable

public void createTable(java.lang.String table,
                        FieldInfo[] cols,
                        java.lang.String[] primaryKeys)
                 throws DataException

Creates a table in the database.

Parameters:

table - Name of table to created.

cols - Specifications of the fields to use as columns for the database table.

primaryKeys - An array holding the fields that will make up the primary key.

Throws:

DataException - Thrown if table cannot be created.

deleteTable

public void deleteTable(java.lang.String table)
                 throws DataException

Deletes a table from the database.

Parameters:

table - Name of table to deleted.

Throws:

DataException - Thrown if table cannot be deleted.

alterTable

public void alterTable(java.lang.String table,
                       FieldInfo[] addCols,
                       java.lang.String[] dropCols,
                       java.lang.String[] primaryKeys)
                throws DataException

Method adds and deletes columns from a database table. If the column being added already exists and it is a varchar field whose length is being increased then the data in that column is preserved. If a column is being modified then if the column occurs in the dropCols parameter, that occurence is ignored and the normal logic for deletion is skipped.

Parameters:

table - Name of table to alter.

Throws:

DataException - Thrown if table cannot be altered.

See Also:

supportsSqlColumnDelete(), supportsSqlColumnChange()

supportsSqlColumnDelete

public boolean supportsSqlColumnDelete()

Method returns a value indicating whether or not a column can be deleted from a database table without recreating the entire table. If this method returns false, then any indices and special characteristics will be lost on all the columns in the database table any time a column is deleted.

Returns:

Whether the database supports a simple column drop.

supportsSqlColumnChange

public boolean supportsSqlColumnChange()

Method returns a value indicating whether or not a varchar column can have its length extended without recreating the entire table. If this method returns false, then any indices and special characteristics will be lost on all the columns in the database table any time a column has its length extended. Note 1: if a column's length is reduced then that is always treated as a column delete followed by a column recreate and all data in the column is lost (see supportsSqlColumnDelete for whether the table is entirely recreated for such modifications).

Returns:

Whether the database supports a simple column length extension.

getPrimaryKeys

public java.lang.String[] getPrimaryKeys(java.lang.String table)
                                  throws DataException

Method returns list of columns that make up the primary key.

Parameters:

table -

Throws:

DataException - Thrown if error is encountered

addIndex

public void addIndex(java.lang.String table,
                     java.lang.String[] indexCols)
              throws DataException

Adds an index used for optimizing queries. The name of the index is computed from the fields that make up the index.

Parameters:

table - The table that is to get the new index.

indexCols - The name of the fields that will make up the index.

Throws:

DataException - Thrown if index cannot be added.

addQuery

public void addQuery(SimpleQueryInfo qInfo)
              throws DataException

Adds a parameterized query to the object that implements this interface.

Parameters:

qInfo - An object containing the information necessary to specify a simple parameterized query.

Throws:

DataException - Thrown if query cannot be added.

removeQuery

public void removeQuery(java.lang.String query)
                 throws DataException

Removeds a parameterized query.

Throws:

DataException - Thrown if query cannot be removed.

getQueryParameters

public java.lang.String[] getQueryParameters(java.lang.String query)
                                      throws DataException

Lists the names of parameters that need to filled in order to execute a parameterized query.

Parameters:

query - The name of the query.

Returns:

Array of lookup keys to use to fill in '?'s.

Throws:

DataException - Thrown if parameters cannot be retrieved.

checkQuery

public boolean checkQuery(java.lang.String query,
                          Parameters args)
                   throws DataException

Validates that the Parameters interface supplies all the necessary parameters for the query.

Returns:

Whether the query will be completed filled.

Throws:

DataException - Thrown if query cannot be validated.

dumpQuery

public java.lang.String dumpQuery(java.lang.String query,
                                  Parameters args)
                           throws DataException

Creates debug dump of a query using the values supplied by the Parameters interface.

Parameters:

query - The name of the parameterized query.

args - The source of the data to fill the query.

Returns:

A debug string for the query.

Throws:

DataException - Thrown if debug string for query cannot be creatd.

releaseConnection

public void releaseConnection()

Used to release a connection to the database back into the cache of pooled database connetions. Note: A connection is automatically assigned to each thread at the time it makes its first database access call. The thread must call this method before terminating or the connection will never be released back to the pool. If the thread is performing many queries, it may want to call this method to periodically release connections so that threads still waiting connections can be serviced.

releaseConnection

public void releaseConnection(java.lang.String threadName)

Releases a connection from the named thread. Called by 'releaseConnection' with the name of the current thread as a parameter.

See Also:

releaseConnection

addQueryDefs

public void addQueryDefs(DataResultSet rset)
                  throws DataException

Adds queries from a table. The table must have the columns 'name', 'queryStr', and 'parameters' defined with the 'parameters' being a list of paramNameparamDataType pairs separated by carriage returns. The 'queryStr' uses '?' marks for its places of substitutions. Note: the possible values for paramDataType are specified as constants in the FieldInfo class.

Parameters:

rset - A result set containing information about parameterized queries to load.

Throws:

DataException - Thrown if the queries could not be added.

getProperty

public java.lang.String getProperty(java.lang.String key)

General function that allow retreiving Workspace specific properties. This function is intended to provide those properties that otherwise not easily derivable. Such as DatabaseType, DatabaseVersion, etc.

Returns:

null if name not found.

dbManagement

public void dbManagement(int type,
                         Parameters args)
                  throws DataException

A general management or configuration function whose appropriate values for its arguments are dependent on the object that implements this interface.

Parameters:

type - An integer argument specifying what management function to perform (Ex: the value may be 'COMPACT' for a MS Access database to specify that the database should be compacted.)

args - Optional arguments whose appropriate values are dependent on the management service specified.

Throws:

DataException - Thrown if there is an error perfoming management function.

See Also:

COMPACT