uk.ac.ebi.intact.persistence
Class ObjectBridgeDAO

java.lang.Object
  |
  +--uk.ac.ebi.intact.persistence.ObjectBridgeDAO

All Implemented Interfaces:

DAO, java.io.Serializable

public class ObjectBridgeDAO

extends java.lang.Object

implements DAO, java.io.Serializable

This class provides an ObjectBridge-specific Data Access Object, which effectively wraps up an ObjectBridge broker object. Note that this DAO only provides a wrapped object from the ObjectBridge kernel, NOT the ODMG interface.

Version:

$Id: ObjectBridgeDAO.java,v 1.37 2004/03/29 15:03:40 smudali Exp $

Author:

Chris Lewington, Sugath Mudali

See Also:

Serialized Form

Field Summary

static java.lang.String

OJB_LOGGER_NAME

Constructor Summary

ObjectBridgeDAO(org.apache.ojb.broker.PersistenceBroker broker)

Method Summary

void	addCachedClass(java.lang.Class clazz) adds a class to a set of classes that should be cached.
void	begin(int txType) Used to begin a transaction.
void	clearCache() wipe the whole cache.
void	close() closes a DAO (connection).
void	closeResults(java.util.Iterator itemIterator) Method to release result resources (eg result set).
void	commit() Commits (finishes) a transaction.
void	create(java.lang.Object obj) creates a single object in persistent store.
java.util.Collection	find(java.lang.Object obj) This method performs an object-based search.
java.util.Collection	find(java.lang.String type, java.lang.String col, java.lang.String val) This method searches the DB based on the information in the parameters.
java.util.Collection	findBySQL(java.lang.String type, java.lang.String sqlString) This method allows submission of a query by straight SQL string.
java.util.Iterator	findColumnValues(java.lang.String type, java.lang.String[] cols) This method provides a means of obtaining particular values of a persistent object without retrieving the whole object itself.
java.lang.String	getDbName() Provides the database name that is being connected to.
java.lang.String	getDbUserName() Provides the user name that is connecting to the DB.
java.sql.Connection	getJDBCConnection() Method to get a direct SQL connection which can be used by JDBC
boolean	isActive() checks to see if a transaction is currently in progress.
boolean	isAutoSave() checks to see if object saving automatically is turned on
boolean	isCachedClass(java.lang.Class clazz)
boolean	isClosed() checks to see if a transaction is closed.
boolean	isPersistent(java.lang.Object obj) checks to determine if a given object is persistent or not
boolean	isUserValid(java.lang.String userName, java.lang.String password) validates a username and password against the datastore.
java.util.Iterator	iteratorFind(java.lang.String type, java.lang.String col, java.lang.String val) This method provides a means to obtain an Iterator for search results.
void	lock(java.lang.Object obj) Locks the specified object to a transaction for WRITE.
void	makePersistent(java.util.Collection objs) This method performs a simple creation for a number of objects.
void	open() opens a DAO (connection).
void	remove(java.lang.Object obj) removes an object from persistent store.
void	removeFromCache(java.lang.Object obj) Removes the given object from the cachce; hence, cancelling any changes to the object.
void	resetUserInfo(java.lang.String user, java.lang.String password) changes the username and password details used for connection.
void	rollback() rollback a transaction.
void	setAutoSave(boolean val) sets whether or not auto saving is turned on
void	setLogger(org.apache.log4j.Logger p) allows a logging destination to be specified
void	update(java.lang.Object obj) updates a given object which was oroginally obtained in another transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OJB_LOGGER_NAME

public static final java.lang.String OJB_LOGGER_NAME

See Also:

Constant Field Values

Constructor Detail

ObjectBridgeDAO

public ObjectBridgeDAO(org.apache.ojb.broker.PersistenceBroker broker)

Method Detail

closeResults

public void closeResults(java.util.Iterator itemIterator)

Method to release result resources (eg result set). An IllegalArgumentException is thronw if the iterator supplied has not been generated by use of iteratorFind.

Specified by:

closeResults in interface DAO

Parameters:

itemIterator - The iterator over the results (should be obtained from iteratorFind)

Throws:

java.lang.IllegalArgumentException - thrown if the Iterator is an invalid type

resetUserInfo

public void resetUserInfo(java.lang.String user,
                          java.lang.String password)

changes the username and password details used for connection. Note that this is NOT currently a runtime change, but will change to a different user if eg the DAO is serialized. This may be modified later to (if possible) provide runtime user switching.

Parameters:

user - the new username

password - the new user password

addCachedClass

public void addCachedClass(java.lang.Class clazz)

Description copied from interface: DAO

adds a class to a set of classes that should be cached. Note that this is in addition to any standard "cache by primary key" facility provided by an implementation.

Specified by:

addCachedClass in interface DAO

Parameters:

clazz - class to be cached

isCachedClass

public boolean isCachedClass(java.lang.Class clazz)

clearCache

public void clearCache()
                throws org.apache.ojb.broker.PersistenceBrokerException

Description copied from interface: DAO

wipe the whole cache.

Specified by:

clearCache in interface DAO

Throws:

org.apache.ojb.broker.PersistenceBrokerException

setLogger

public void setLogger(org.apache.log4j.Logger p)

Description copied from interface: DAO

allows a logging destination to be specified

Specified by:

setLogger in interface DAO

Parameters:

p - A PrintWriter for logging output

isUserValid

public boolean isUserValid(java.lang.String userName,
                           java.lang.String password)

validates a username and password against the datastore.

Specified by:

isUserValid in interface DAO

Returns:

boolean true if user credentials are valid, false if not or if a null username is supplied.

getDbName

public java.lang.String getDbName()
                           throws org.apache.ojb.broker.accesslayer.LookupException,
                                  java.sql.SQLException

Provides the database name that is being connected to.

Specified by:

getDbName in interface DAO

Returns:

String the database name, or an empty String if the query fails

Throws:

org.apache.ojb.broker.accesslayer.LookupException - thrown on error getting the Connection

java.sql.SQLException - thrown if the metatdata can't be obtained

getDbUserName

public java.lang.String getDbUserName()
                               throws org.apache.ojb.broker.accesslayer.LookupException,
                                      java.sql.SQLException

Provides the user name that is connecting to the DB.

Specified by:

getDbUserName in interface DAO

Returns:

String the user name, or an empty String if the query fails

Throws:

org.apache.ojb.broker.accesslayer.LookupException - thrown on error getting the Connection

java.sql.SQLException - thrown if the metatdata can't be obtained

getJDBCConnection

public java.sql.Connection getJDBCConnection()
                                      throws org.apache.ojb.broker.accesslayer.LookupException

Method to get a direct SQL connection which can be used by JDBC

Returns:

java.sql.Connection to database

Throws:

org.apache.ojb.broker.accesslayer.LookupException

begin

public void begin(int txType)
           throws TransactionException

Used to begin a transaction. The transaction level (object or JDBC) should be specified. Defaults to JDBC level.

Specified by:

begin in interface DAO

Parameters:

txType - The type of transaction to begin (JDBC or object)

Throws:

TransactionException - - can be thrown if a transaction is already in progress

See Also:

BusinessConstants

lock

public void lock(java.lang.Object obj)
          throws org.odmg.TransactionNotInProgressException

Locks the specified object to a transaction for WRITE. Note that this method can ONLY be used if you are using object-level transactions (it doesn't make sense for JDBC transactions)

Specified by:

lock in interface DAO

Parameters:

obj - The object to lock for write.

Throws:

org.odmg.TransactionNotInProgressException - thrown if no object TX is running

close

public void close()
           throws DataSourceException

closes a DAO (connection).

Specified by:

close in interface DAO

Throws:

DataSourceException - - thrown if the DAO cannot be closed (details in specific errors)

open

public void open()
          throws DataSourceException

opens a DAO (connection). Note that connections are opened also via the DAO constructor method, so this method should not be called unless a previous call to close() has been made.

Specified by:

open in interface DAO

Throws:

DataSourceException - - thrown if the DAO cannot be closed (details in specific errors)

commit

public void commit()
            throws TransactionException

Commits (finishes) a transaction. Usual meaning.

Specified by:

commit in interface DAO

Throws:

TransactionException - - thrown if, say, a transaction was not in progress for example

create

public void create(java.lang.Object obj)
            throws CreateException

creates a single object in persistent store.

Specified by:

create in interface DAO

Parameters:

obj - - the object to be saved

Throws:

CreateException

removeFromCache

public void removeFromCache(java.lang.Object obj)

Description copied from interface: DAO

Removes the given object from the cachce; hence, cancelling any changes to the object.

Specified by:

removeFromCache in interface DAO

Parameters:

obj - the object to remove from the cache.

update

public void update(java.lang.Object obj)
            throws UpdateException

Description copied from interface: DAO

updates a given object which was oroginally obtained in another transaction. This allows, for example, objects to be read from persistent store in one transaction, modified elsewhere (eg via a user interface object) and then have the changes reflected in persistent store within the context of a different transaction. This therefore removes the need to retrieve the object again in order to perform an update.

Specified by:

update in interface DAO

Parameters:

obj - - the object to be updated

Throws:

UpdateException - - thrown if the object could not me modified (eg called outside a transaction scope) or hasn't been persisted previously ( DAO.isPersistent(Object) must return true).

See Also:

DAO.update(Object)

isActive

public boolean isActive()

checks to see if a transaction is currently in progress. This will test either an Object or JDBC level transaction, depending upon which may be active (if any).

Specified by:

isActive in interface DAO

Returns:

boolean - true if a transaction is active, false otherwise

isAutoSave

public boolean isAutoSave()

checks to see if object saving automatically is turned on

Specified by:

isAutoSave in interface DAO

Returns:

boolean - true if auto saving is on, false otherwise

setAutoSave

public void setAutoSave(boolean val)

sets whether or not auto saving is turned on

Specified by:

setAutoSave in interface DAO

Parameters:

val - - true to turn on, false for off

isClosed

public boolean isClosed()

checks to see if a transaction is closed.

Specified by:

isClosed in interface DAO

Returns:

boolean - true if closed (default), false otherwise

isPersistent

public boolean isPersistent(java.lang.Object obj)

checks to determine if a given object is persistent or not

Specified by:

isPersistent in interface DAO

Parameters:

obj - - the object to be checked

Returns:

boolean - true if the object is persistent (default), false for all other instances.

remove

public void remove(java.lang.Object obj)
            throws TransactionException

removes an object from persistent store.

Specified by:

remove in interface DAO

Parameters:

obj - - the object to be removed

Throws:

TransactionException - - thrown usually if the operation is called outside a transaction

rollback

public void rollback()
              throws TransactionException

rollback a transaction. Usual meaning...

Specified by:

rollback in interface DAO

Throws:

TransactionException - - thrown if the transaction couldn't be rolled back

makePersistent

public void makePersistent(java.util.Collection objs)
                    throws CreateException,
                           TransactionException

This method performs a simple creation for a number of objects.

Specified by:

makePersistent in interface DAO

Parameters:

objs - - the collection of objects to be persisted

Throws:

CreateException - - thrown if an object could not be stored

TransactionException - - thrown if errors resulted from invalid transaction operations or errors

find

public java.util.Collection find(java.lang.String type,
                                 java.lang.String col,
                                 java.lang.String val)
                          throws SearchException

This method searches the DB based on the information in the parameters. Note that this only supports a single parameter (simple) search at present - bulk searches are TBD

Specified by:

find in interface DAO

Parameters:

type - - the class name (ie table) to be searched

col - - the parameter (column name) to search on (usually ac number or name)

val - - the value of the search parameter. If null, then all items matching the class name will be returned

Returns:

a collection containing the results of the searches

Throws:

SearchException - - thrown for errors during the search process, eg query problems

java.lang.NullPointerException - thrown if the type is not specified

find

public java.util.Collection find(java.lang.Object obj)
                          throws SearchException

Description copied from interface: DAO

This method performs an object-based search. Specifically it provides a way to search for a "complete" object given a partially defined object, ie an object which does not have all fields filled. It provides equivalent functionality to the simple text-based search when only a single (String) field is filled in. Searches may be performed using an example object which only has a single object reference set, or even an example object containing a Collection that has only a single element set.

NOTE - RESTRICTIONS ON CURRENT USE

• Any object references contained in the obj parameter must have, at least, their Primary Key defined
• if the obj parameter contains a non-empty Collection, the Collection must have at least one element with its Primary Key set

Specified by:

find in interface DAO

Parameters:

obj - - the object search "value"

Returns:

a collection containing the search results

Throws:

SearchException - - thrown if there were problems during the search process itself

See Also:

Note: the local cache of non-PK fields is not currently used in this method (to do)

findColumnValues

public java.util.Iterator findColumnValues(java.lang.String type,
                                           java.lang.String[] cols)
                                    throws SearchException

This method provides a means of obtaining particular values of a persistent object without retrieving the whole object itself. It therefore allows users to obtain table column values.

Specified by:

findColumnValues in interface DAO

Parameters:

type - the object type you want details of (must be specified)

cols - the table columns (NOT attribute names) you are interested in (null will retrieve all of them)

Returns:

Iterator an iterator over the requested table column values - NB each item in the Iterator is of type Object, and must therefore be cast to the correct type by the user of this method. If you do not exhaust the iterator then to clean up DB resources you must pass the Iterator to the closeResults method of this class. Null is returned if no results found

Throws:

SearchException - trhown if a problem occurs whilst searching the data store

java.lang.NullPointerException - thrown if the type is null

findBySQL

public java.util.Collection findBySQL(java.lang.String type,
                                      java.lang.String sqlString)
                               throws SearchException

This method allows submission of a query by straight SQL string. If the string is garbage then expect garbage back - no guarantees are made for the results.

Specified by:

findBySQL in interface DAO

Parameters:

type - the object type you want details of (must be specified)

sqlString - the string to be used for the query

Returns:

A Collection of search results, or empty if none found

Throws:

SearchException - thrown if a problem occurs whilst searching the data store

java.lang.NullPointerException - thrown if the type is null

iteratorFind

public java.util.Iterator iteratorFind(java.lang.String type,
                                       java.lang.String col,
                                       java.lang.String val)
                                throws SearchException

This method provides a means to obtain an Iterator for search results. This can be useful if you need direct control over a result set, because OJB iterators have access to result sets which may then be closed by passing the iterator back to the closeResults method. Note that this approach will not tidy up open cursors on an oracle server - the only way to do this seems to be to close the connection, which is done automatically via the find method (this is OK if oracle connection pooling is used).

Specified by:

iteratorFind in interface DAO

Parameters:

type - - the class name (ie table) to be searched

col - - the parameter (column name) to search on (usually ac number or name)

val - - the value of the search parameter

Returns:

an Iterator over the results set - null if no results found

Throws:

java.lang.NullPointerException - thrown if the type is null

SearchException - - thrown for errors during the search process, eg query problems