org.apache.manifoldcf.core.interfaces
Interface IDBInterface

All Known Implementing Classes:

DBInterfaceDerby, DBInterfaceHSQLDB, DBInterfaceMySQL, DBInterfacePostgreSQL

public interface IDBInterface

The purpose of this interface is to provide abstracted database table modification primitives, as well as general access primitives. It is expected that the generalized database layer will provide the underlying services. This layer should provide services roughly equivalent to the former DBInterface bean, but be callable in a pure Java fashion. It is furthermore intended that all abstraction database requests go through this layer. It will therefore, over time, provide grander and grander levels of database query abstraction. Also note that the database parameters will be passed to the factory for this class, not to the individual methods.

Field Summary

static java.lang.String	_rcsid
static int	TRANSACTION_ENCLOSING
static int	TRANSACTION_READCOMMITTED
static int	TRANSACTION_SERIALIZED

Method Summary

void	addTableIndex(java.lang.String tableName, boolean unique, java.util.ArrayList columnList) Add an index to a table.
void	analyzeTable(java.lang.String tableName) Analyze a table.
void	beginTransaction() Begin a database transaction.
void	beginTransaction(int transactionType) Begin a database transaction.
void	closeDatabase() Uninitialize.
java.lang.String	constructDistinctOnClause(java.util.ArrayList outputParameters, java.lang.String baseQuery, java.util.ArrayList baseParameters, java.lang.String[] distinctFields, java.util.Map otherFields) Construct a 'distinct on (x)' filter.
java.lang.String	constructOffsetLimitClause(int offset, int limit) Construct an offset/limit clause.
java.lang.String	constructRegexpClause(java.lang.String column, java.lang.String regularExpression, boolean caseInsensitive) Construct a regular-expression match clause.
java.lang.String	constructSubstringClause(java.lang.String column, java.lang.String regularExpression, boolean caseInsensitive) Construct a regular-expression substring clause.
void	createUserAndDatabase(java.lang.String adminUserName, java.lang.String adminPassword, StringSet invalidateKeys) Create user and database.
void	dropUserAndDatabase(java.lang.String adminUserName, java.lang.String adminPassword, StringSet invalidateKeys) Drop user and database.
void	endTransaction() End a database transaction, either performing a commit or a rollback (depending on whether signalRollback() was called within the transaction).
StringSet	getAllTables(StringSet cacheKeys, java.lang.String queryClass) Get a database's tables.
java.lang.String	getDatabaseCacheKey() Get the database general cache key.
java.lang.String	getDatabaseName() Get the database name.
int	getMaxInClause() Obtain the maximum number of individual items that should be present in an IN clause.
int	getMaxOrClause() Obtain the maximum number of individual clauses that should be present in a sequence of OR clauses.
long	getSleepAmt() Get a random time, in milliseconds, for backoff from deadlock.
java.util.Map	getTableIndexes(java.lang.String tableName, StringSet cacheKeys, java.lang.String queryClass) Get a table's indexes.
java.util.Map	getTableSchema(java.lang.String tableName, StringSet cacheKeys, java.lang.String queryClass) Get a table's schema.
java.lang.String	getTransactionID() Get the current transaction id.
void	noteModifications(java.lang.String tableName, int insertCount, int modifyCount, int deleteCount) Note a number of inserts, modifications, or deletions to a specific table.
void	openDatabase() Initialize.
void	performAddIndex(java.lang.String indexName, java.lang.String tableName, IndexDescription description) Add an index to a table.
void	performAlter(java.lang.String tableName, java.util.Map columnMap, java.util.Map columnModifyMap, java.util.ArrayList columnDeleteList, StringSet invalidateKeys) Perform a table alter operation.
void	performCreate(java.lang.String tableName, java.util.Map columnMap, StringSet invalidateKeys) Perform a table creation operation.
void	performDelete(java.lang.String tableName, java.lang.String whereClause, java.util.ArrayList whereParameters, StringSet invalidateKeys) Perform a delete operation.
void	performDrop(java.lang.String tableName, StringSet invalidateKeys) Perform a table drop operation.
void	performInsert(java.lang.String tableName, java.util.Map parameterMap, StringSet invalidateKeys) Perform an insert operation.
void	performLock(java.lang.String tableName) Perform a table lock operation.
void	performModification(java.lang.String query, java.util.ArrayList params, StringSet invalidateKeys) Perform a general database modification query.
IResultSet	performQuery(java.lang.String query, java.util.ArrayList params, StringSet cacheKeys, java.lang.String queryClass) Perform a general "data fetch" query.
IResultSet	performQuery(java.lang.String query, java.util.ArrayList params, StringSet cacheKeys, java.lang.String queryClass, int maxResults, ILimitChecker returnLimit) Perform a general "data fetch" query.
IResultSet	performQuery(java.lang.String query, java.util.ArrayList params, StringSet cacheKeys, java.lang.String queryClass, int maxResults, ResultSpecification resultSpec, ILimitChecker returnLimit) Perform a general "data fetch" query.
void	performRemoveIndex(java.lang.String indexName) Remove an index.
void	performUpdate(java.lang.String tableName, java.util.Map parameterMap, java.lang.String whereClause, java.util.ArrayList whereParameters, StringSet invalidateKeys) Perform an update operation.
void	reindexTable(java.lang.String tableName) Reindex a table.
void	signalRollback() Signal that a rollback should occur on the next endTransaction().
void	sleepFor(long time) Sleep for a specified time, as part of backoff from deadlock.

Field Detail

_rcsid

static final java.lang.String _rcsid

See Also:

Constant Field Values

TRANSACTION_ENCLOSING

static final int TRANSACTION_ENCLOSING

See Also:

Constant Field Values

TRANSACTION_READCOMMITTED

static final int TRANSACTION_READCOMMITTED

See Also:

Constant Field Values

TRANSACTION_SERIALIZED

static final int TRANSACTION_SERIALIZED

See Also:

Constant Field Values

Method Detail

openDatabase

void openDatabase()
                  throws ManifoldCFException

Initialize. This method is called once per JVM instance, in order to set up database communication.

Throws:

ManifoldCFException

closeDatabase

void closeDatabase()
                   throws ManifoldCFException

Uninitialize. This method is called during JVM shutdown, in order to close all database communication.

Throws:

ManifoldCFException

getDatabaseName

java.lang.String getDatabaseName()

Get the database name.

Returns:

the database name.

getTransactionID

java.lang.String getTransactionID()

Get the current transaction id.

Returns:

the current transaction identifier, or null if no transaction.

getDatabaseCacheKey

java.lang.String getDatabaseCacheKey()

Get the database general cache key.

Returns:

the general cache key for the database.

performLock

void performLock(java.lang.String tableName)
                 throws ManifoldCFException

Perform a table lock operation.

Parameters:

tableName - is the name of the table.

Throws:

ManifoldCFException

performInsert

void performInsert(java.lang.String tableName,
                   java.util.Map parameterMap,
                   StringSet invalidateKeys)
                   throws ManifoldCFException

Perform an insert operation.

Parameters:

tableName - is the name of the table.

invalidateKeys - are the cache keys that should be invalidated.

parameterMap - is the map of column name/values to write.

Throws:

ManifoldCFException

performUpdate

void performUpdate(java.lang.String tableName,
                   java.util.Map parameterMap,
                   java.lang.String whereClause,
                   java.util.ArrayList whereParameters,
                   StringSet invalidateKeys)
                   throws ManifoldCFException

Perform an update operation.

Parameters:

tableName - is the name of the table.

invalidateKeys - are the cache keys that should be invalidated.

parameterMap - is the map of column name/values to write.

whereClause - is the where clause describing the match (including the WHERE), or null if none.

whereParameters - are the parameters that come with the where clause, if any.

Throws:

ManifoldCFException

performDelete

void performDelete(java.lang.String tableName,
                   java.lang.String whereClause,
                   java.util.ArrayList whereParameters,
                   StringSet invalidateKeys)
                   throws ManifoldCFException

Perform a delete operation.

Parameters:

tableName - is the name of the table to delete from.

invalidateKeys - are the cache keys that should be invalidated.

whereClause - is the where clause describing the match (including the WHERE), or null if none.

whereParameters - are the parameters that come with the where clause, if any.

Throws:

ManifoldCFException

performCreate

void performCreate(java.lang.String tableName,
                   java.util.Map columnMap,
                   StringSet invalidateKeys)
                   throws ManifoldCFException

Perform a table creation operation.

Parameters:

tableName - is the name of the table to create.

columnMap - is the map describing the columns and types. NOTE that these are abstract types, which will be mapped to the proper types for the actual database inside this layer. The types are ColumnDefinition objects.

invalidateKeys - are the cache keys that should be invalidated, if any.

Throws:

ManifoldCFException

performAlter

void performAlter(java.lang.String tableName,
                  java.util.Map columnMap,
                  java.util.Map columnModifyMap,
                  java.util.ArrayList columnDeleteList,
                  StringSet invalidateKeys)
                  throws ManifoldCFException

Perform a table alter operation.

Parameters:

tableName - is the name of the table to alter.

columnMap - is the map describing the columns and types to add. These are in the same form as for performCreate.

columnModifyMap - is the map describing the columns to be changed. The key is the existing column name, and the value is the new type of the column. Data will be copied from the old column to the new.

columnDeleteList - is the list of column names to delete.

invalidateKeys - are the cache keys that should be invalidated, if any.

Throws:

ManifoldCFException

addTableIndex

void addTableIndex(java.lang.String tableName,
                   boolean unique,
                   java.util.ArrayList columnList)
                   throws ManifoldCFException

Add an index to a table.

Parameters:

tableName - is the name of the table to add the index for.

unique - is a boolean that if true describes a unique index.

columnList - is the list of columns that need to be included in the index, in order.

Throws:

ManifoldCFException

performAddIndex

void performAddIndex(java.lang.String indexName,
                     java.lang.String tableName,
                     IndexDescription description)
                     throws ManifoldCFException

Add an index to a table.

Parameters:

tableName - is the name of the table to add the index for.

indexName - is the optional name of the table index. If null, a name will be chosen automatically.

description - is the index description.

Throws:

ManifoldCFException

performRemoveIndex

void performRemoveIndex(java.lang.String indexName)
                        throws ManifoldCFException

Remove an index.

Parameters:

indexName - is the name of the index to remove.

Throws:

ManifoldCFException

analyzeTable

void analyzeTable(java.lang.String tableName)
                  throws ManifoldCFException

Analyze a table.

Parameters:

tableName - is the name of the table to analyze/calculate statistics for.

Throws:

ManifoldCFException

reindexTable

void reindexTable(java.lang.String tableName)
                  throws ManifoldCFException

Reindex a table.

Parameters:

tableName - is the name of the table to rebuild indexes for.

Throws:

ManifoldCFException

performDrop

void performDrop(java.lang.String tableName,
                 StringSet invalidateKeys)
                 throws ManifoldCFException

Perform a table drop operation.

Parameters:

tableName - is the name of the table to drop.

invalidateKeys - are the cache keys that should be invalidated, if any.

Throws:

ManifoldCFException

createUserAndDatabase

void createUserAndDatabase(java.lang.String adminUserName,
                           java.lang.String adminPassword,
                           StringSet invalidateKeys)
                           throws ManifoldCFException

Create user and database.

Parameters:

adminUserName - is the admin user name.

adminPassword - is the admin password.

invalidateKeys - are the cache keys that should be invalidated, if any.

Throws:

ManifoldCFException

dropUserAndDatabase

void dropUserAndDatabase(java.lang.String adminUserName,
                         java.lang.String adminPassword,
                         StringSet invalidateKeys)
                         throws ManifoldCFException

Drop user and database.

Parameters:

adminUserName - is the admin user name.

adminPassword - is the admin password.

invalidateKeys - are the cache keys that should be invalidated, if any.

Throws:

ManifoldCFException

getTableSchema

java.util.Map getTableSchema(java.lang.String tableName,
                             StringSet cacheKeys,
                             java.lang.String queryClass)
                             throws ManifoldCFException

Get a table's schema.

Parameters:

tableName - is the name of the table.

cacheKeys - are the keys against which to cache the query, or null.

queryClass - is the name of the query class, or null.

Returns:

a map of column names and ColumnDescription objects, describing the schema.

Throws:

ManifoldCFException

getTableIndexes

java.util.Map getTableIndexes(java.lang.String tableName,
                              StringSet cacheKeys,
                              java.lang.String queryClass)
                              throws ManifoldCFException

Get a table's indexes.

Parameters:

tableName - is the name of the table.

cacheKeys - are the keys against which to cache the query, or null.

queryClass - is the name of the query class, or null.

Returns:

a map of index names and IndexDescription objects, describing the indexes.

Throws:

ManifoldCFException

getAllTables

StringSet getAllTables(StringSet cacheKeys,
                       java.lang.String queryClass)
                       throws ManifoldCFException

Get a database's tables.

Parameters:

cacheKeys - are the cache keys for the query, or null.

queryClass - is the name of the query class, or null.

Returns:

the set of tables.

Throws:

ManifoldCFException

performModification

void performModification(java.lang.String query,
                         java.util.ArrayList params,
                         StringSet invalidateKeys)
                         throws ManifoldCFException

Perform a general database modification query.

Parameters:

query - is the query string.

params - are the parameterized values, if needed.

invalidateKeys - are the cache keys to invalidate.

Throws:

ManifoldCFException

performQuery

IResultSet performQuery(java.lang.String query,
                        java.util.ArrayList params,
                        StringSet cacheKeys,
                        java.lang.String queryClass)
                        throws ManifoldCFException

Perform a general "data fetch" query.

Parameters:

query - is the query string.

params - are the parameterized values, if needed.

cacheKeys - are the cache keys, if needed (null if no cache desired).

queryClass - is the LRU class name against which this query would be cached, or null if no LRU behavior desired.

Returns:

a resultset.

Throws:

ManifoldCFException

performQuery

IResultSet performQuery(java.lang.String query,
                        java.util.ArrayList params,
                        StringSet cacheKeys,
                        java.lang.String queryClass,
                        int maxResults,
                        ILimitChecker returnLimit)
                        throws ManifoldCFException

Perform a general "data fetch" query.

Parameters:

query - is the query string.

params - are the parameterized values, if needed.

cacheKeys - are the cache keys, if needed (null if no cache desired).

queryClass - is the LRU class name against which this query would be cached, or null if no LRU behavior desired.

maxResults - is the maximum number of results returned (-1 for all).

returnLimit - is a description of how to limit the return result, or null if no limit.

Returns:

a resultset.

Throws:

ManifoldCFException

performQuery

IResultSet performQuery(java.lang.String query,
                        java.util.ArrayList params,
                        StringSet cacheKeys,
                        java.lang.String queryClass,
                        int maxResults,
                        ResultSpecification resultSpec,
                        ILimitChecker returnLimit)
                        throws ManifoldCFException

Perform a general "data fetch" query.

Parameters:

query - is the query string.

params - are the parameterized values, if needed.

cacheKeys - are the cache keys, if needed (null if no cache desired).

queryClass - is the LRU class name against which this query would be cached, or null if no LRU behavior desired.

maxResults - is the maximum number of results returned (-1 for all).

resultSpec - is a result specification, or null for the standard treatment.

returnLimit - is a description of how to limit the return result, or null if no limit.

Returns:

a resultset.

Throws:

ManifoldCFException

constructRegexpClause

java.lang.String constructRegexpClause(java.lang.String column,
                                       java.lang.String regularExpression,
                                       boolean caseInsensitive)

Construct a regular-expression match clause. This method builds a regular-expression match expression.

Parameters:

column - is the column specifier string.

regularExpression - is the properly-quoted regular expression string, or "?" if a parameterized value is to be used.

caseInsensitive - is true if the regular expression match is to be case insensitive.

Returns:

the query chunk needed, not padded with spaces on either side.

constructSubstringClause

java.lang.String constructSubstringClause(java.lang.String column,
                                          java.lang.String regularExpression,
                                          boolean caseInsensitive)

Construct a regular-expression substring clause. This method builds an expression that extracts a specified string section from a field, based on a regular expression.

Parameters:

column - is the column specifier string.

regularExpression - is the properly-quoted regular expression string, or "?" if a parameterized value is to be used.

caseInsensitive - is true if the regular expression match is to be case insensitive.

Returns:

the expression chunk needed, not padded with spaces on either side.

constructOffsetLimitClause

java.lang.String constructOffsetLimitClause(int offset,
                                            int limit)

Construct an offset/limit clause. This method constructs an offset/limit clause in the proper manner for the database in question.

Parameters:

offset - is the starting offset number.

limit - is the limit of result rows to return.

Returns:

the proper clause, with no padding spaces on either side.

constructDistinctOnClause

java.lang.String constructDistinctOnClause(java.util.ArrayList outputParameters,
                                           java.lang.String baseQuery,
                                           java.util.ArrayList baseParameters,
                                           java.lang.String[] distinctFields,
                                           java.util.Map otherFields)

Construct a 'distinct on (x)' filter. This filter wraps a query and returns a new query whose results are similar to POSTGRESQL's DISTINCT-ON feature. Specifically, for each combination of the specified distinct fields in the result, only the first such row is included in the final result.

Parameters:

outputParameters - is a blank arraylist into which to put parameters. Null may be used if the baseParameters parameter is null.

baseQuery - is the base query, which is another SELECT statement, without parens, e.g. "SELECT ..."

baseParameters - are the parameters corresponding to the baseQuery.

distinctFields - are the fields to consider to be distinct. These should all be keys in otherFields below.

otherFields - are the rest of the fields to return, keyed by the AS name, value being the base query column value, e.g. "value AS key"

Returns:

a revised query that performs the necessary DISTINCT ON operation. The arraylist outputParameters will also be appropriately filled in.

getMaxInClause

int getMaxInClause()

Obtain the maximum number of individual items that should be present in an IN clause. Exceeding this amount will potentially cause the query performance to drop.

Returns:

the maximum number of IN clause members.

getMaxOrClause

int getMaxOrClause()

Obtain the maximum number of individual clauses that should be present in a sequence of OR clauses. Exceeding this amount will potentially cause the query performance to drop.

Returns:

the maximum number of OR clause members.

beginTransaction

void beginTransaction()
                      throws ManifoldCFException

Begin a database transaction. This method call MUST be paired with an endTransaction() call, or database handles will be lost. If the transaction should be rolled back, then signalRollback() should be called before the transaction is ended. It is strongly recommended that the code that uses transactions be structured so that a try block starts immediately after this method call. The body of the try block will contain all direct or indirect calls to executeQuery(). After this should be a catch for every exception type, including Error, which should call the signalRollback() method, and rethrow the exception. Then, after that a finally{} block which calls endTransaction(). (The kind of transaction started by this method is the current default transaction type, which is "read committed" if not otherwise determined).

Throws:

ManifoldCFException

beginTransaction

void beginTransaction(int transactionType)
                      throws ManifoldCFException

Begin a database transaction. This method call MUST be paired with an endTransaction() call, or database handles will be lost. If the transaction should be rolled back, then signalRollback() should be called before the transaction is ended. It is strongly recommended that the code that uses transactions be structured so that a try block starts immediately after this method call. The body of the try block will contain all direct or indirect calls to executeQuery(). After this should be a catch for every exception type, including Error, which should call the signalRollback() method, and rethrow the exception. Then, after that a finally{} block which calls endTransaction().

Parameters:

transactionType - is the kind of transaction desired.

Throws:

ManifoldCFException

signalRollback

void signalRollback()

Signal that a rollback should occur on the next endTransaction().

endTransaction

void endTransaction()
                    throws ManifoldCFException

End a database transaction, either performing a commit or a rollback (depending on whether signalRollback() was called within the transaction).

Throws:

ManifoldCFException

noteModifications

void noteModifications(java.lang.String tableName,
                       int insertCount,
                       int modifyCount,
                       int deleteCount)
                       throws ManifoldCFException

Note a number of inserts, modifications, or deletions to a specific table. This is so we can decide when to do appropriate maintenance.

Parameters:

tableName - is the name of the table being modified.

insertCount - is the number of inserts.

modifyCount - is the number of updates.

deleteCount - is the number of deletions.

Throws:

ManifoldCFException

getSleepAmt

long getSleepAmt()

Get a random time, in milliseconds, for backoff from deadlock.

Returns:

the random time.

sleepFor

void sleepFor(long time)
              throws ManifoldCFException

Sleep for a specified time, as part of backoff from deadlock.

Parameters:

time - is the amount to sleep.

Throws:

ManifoldCFException