net.sourceforge.pbeans.data
Interface Database

All Known Implementing Classes:

AbstractDatabase, GenericDatabase

public interface Database

Interface intended to be an abstraction for a any database.

Method Summary

void	beginTransaction(int transactionIsolationLevel) Starts a transaction.
void	endTransaction(boolean rollback) Ends a transaction.
void	ensureTableExists(java.lang.String tableName, FieldDescriptor fixedDescriptor, java.util.Collection fieldDescriptors, java.util.Collection indexDescriptors, boolean userManaged, boolean autoIncrementRequested, boolean deleteFields) Ensures that a table exists and modifies fields and indexes as needed.
int	getMaxColumnNameLength()
int	getMaxTableNameLength()
void	init(javax.sql.DataSource dataSource) This method should be invoked as soon as the Database implementation is instantiated by a DatabaseFactory.
java.lang.Long	insert(java.lang.String tableName, java.lang.String idField, java.lang.String[] fieldNames, java.lang.Object[] values, boolean autoIncrementRequested) Inserts a record in the database.
boolean	inTransaction()
boolean	isDuplicateEntryError(java.sql.SQLException se) Determines whether a SQLException corresponds to a duplicate record error.
java.lang.String	normalizeName(java.lang.String itemName) Coverts a field or table name to the name that will actually be used in the database.
ResultsIterator<BeanWrapper>	query(java.lang.String sql, java.lang.Object[] parameters, BeanUnmarshaller unmarshaller) Performs a database query.
void	relinquishLock(boolean rollback) Gives up a lock previously obtained by invoking requestLock in the current thread.
void	requestLock(java.lang.String lockName, int transactionIsolationLevel) Requests a record lock.
void	rollback(java.sql.Savepoint savepoint)
java.sql.Savepoint	setSavepoint(java.lang.String savepointName)
int	update(java.lang.String sql, java.lang.Object[] parameters) Executes a database statement.

Method Detail

init

void init(javax.sql.DataSource dataSource)
          throws java.sql.SQLException

This method should be invoked as soon as the Database implementation is instantiated by a DatabaseFactory.

Parameters:

dataSource - A DataSource instance.

Throws:

java.sql.SQLException

getMaxTableNameLength

int getMaxTableNameLength()
                          throws java.sql.SQLException

Throws:

java.sql.SQLException

getMaxColumnNameLength

int getMaxColumnNameLength()
                           throws java.sql.SQLException

Throws:

java.sql.SQLException

ensureTableExists

void ensureTableExists(java.lang.String tableName,
                       FieldDescriptor fixedDescriptor,
                       java.util.Collection fieldDescriptors,
                       java.util.Collection indexDescriptors,
                       boolean userManaged,
                       boolean autoIncrementRequested,
                       boolean deleteFields)
                       throws java.sql.SQLException

Ensures that a table exists and modifies fields and indexes as needed.

Parameters:

tableName - Name of the table.

fixedDescriptor - A FieldDescriptor which cannot be removed later (typically the table's primary key.)

fieldDescriptors - A collection of FieldDescriptor instances.

indexDescriptors - A collection of IndexDescriptor instances.

autoIncrementRequested - Whether auto-increment is requested for mandatory field.

deleteFields - Whether fields not requested that were found in the table should be deleted.

Throws:

java.sql.SQLException

query

ResultsIterator<BeanWrapper> query(java.lang.String sql,
                                   java.lang.Object[] parameters,
                                   BeanUnmarshaller unmarshaller)
                                   throws java.sql.SQLException

Performs a database query.

Parameters:

sql - A SQL SELECT statement with question marks (?) as placeholders.

parameters - An array of parameters whose length is equal to the number of placeholders in the SQL statement.

unmarshaller - A BeanUnmarshaller implementation instance.

Throws:

java.sql.SQLException

See Also:

update(java.lang.String, java.lang.Object[])

update

int update(java.lang.String sql,
           java.lang.Object[] parameters)
           throws java.sql.SQLException

Executes a database statement.

Parameters:

sql - A SQL modification statement with question marks (?) as placeholders.

parameters - An array of parameters whose length is equal to the number of placeholders in the SQL statement.

Throws:

java.sql.SQLException

See Also:

query(java.lang.String, java.lang.Object[], net.sourceforge.pbeans.data.BeanUnmarshaller)

insert

java.lang.Long insert(java.lang.String tableName,
                      java.lang.String idField,
                      java.lang.String[] fieldNames,
                      java.lang.Object[] values,
                      boolean autoIncrementRequested)
                      throws java.sql.SQLException

Inserts a record in the database.

Parameters:

tableName -

idField - Name of ID field.

fieldNames -

values -

autoIncrementRequested - Whether auto-increment is requested for the ID field.

Returns:

The record ID.

Throws:

java.sql.SQLException

requestLock

void requestLock(java.lang.String lockName,
                 int transactionIsolationLevel)
                 throws java.lang.InterruptedException,
                        java.sql.SQLException

Requests a record lock. The lock must be given up at some point by invoking relinquishLock. Nested locks are allowed.

Throws:

java.lang.InterruptedException

java.sql.SQLException

relinquishLock

void relinquishLock(boolean rollback)
                    throws java.sql.SQLException

Gives up a lock previously obtained by invoking requestLock in the current thread.

Throws:

java.sql.SQLException

beginTransaction

void beginTransaction(int transactionIsolationLevel)
                      throws java.sql.SQLException

Starts a transaction. Note that nested transactions are not allowed.

Parameters:

transactionIsolationLevel -

Throws:

java.sql.SQLException

endTransaction

void endTransaction(boolean rollback)
                    throws java.sql.SQLException

Ends a transaction.

Throws:

java.sql.SQLException

setSavepoint

java.sql.Savepoint setSavepoint(java.lang.String savepointName)
                                throws java.sql.SQLException

Throws:

java.sql.SQLException

rollback

void rollback(java.sql.Savepoint savepoint)
              throws java.sql.SQLException

Throws:

java.sql.SQLException

inTransaction

boolean inTransaction()

isDuplicateEntryError

boolean isDuplicateEntryError(java.sql.SQLException se)

Determines whether a SQLException corresponds to a duplicate record error.

normalizeName

java.lang.String normalizeName(java.lang.String itemName)

Coverts a field or table name to the name that will actually be used in the database. Usually this will return the itemName parameter unchanged.