uk.ac.ebi.intact.persistence
Interface DAO

All Known Implementing Classes:

ObjectBridgeDAO

public interface DAO

This interface defines the methods available from a Data Access Object (DAO) implementation. It therefore allows clients of this interface to use typical operations usually provided by a connection class, such as submitting queries etc without knowing the details of the specific DAO implementing this interface. Each implementation of the interface will therefore be a wrapper object around a particular DAO type (eg Castor, XML etc).

Note that methods are included to either perform "encapsulated transactions" (for example bulk object creation or simple searching), or to manage transactions at the client level as one might usually do with, say, JDBC.

Author:

Chris Lewington

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 performs a simple search based on the object type to search over, the parameter name and the search value.
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.
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	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 given object for write access.
void	makePersistent(java.util.Collection objs) This method performs an object creation operation for a collection of objects provided as parameters.
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	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.

Method Detail

isUserValid

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

validates a username and password against the datastore.

Returns:

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

closeResults

public void closeResults(java.util.Iterator itemIterator)

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

Parameters:

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

Throws:

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

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.

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.

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

begin

public void begin(int txType)
           throws TransactionException

Used to begin a transaction.

Parameters:

txType - the Transaction type (eg object or JDBC level)

Throws:

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

lock

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

Locks the given object for write access. begin(int) must be called to prior to this method.

Parameters:

obj - the object to lock for write access.

Throws:

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

close

public void close()
           throws DataSourceException

closes a DAO (connection).

Throws:

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

open

public void open()
          throws DataSourceException

opens a DAO (connection).

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.

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.

Parameters:

obj - - the object to be saved

Throws:

CreateException

isActive

public boolean isActive()

checks to see if a transaction is currently in progress

Returns:

boolean - true if a transaction isa ctive, false otherwise

isAutoSave

public boolean isAutoSave()

checks to see if object saving automatically is turned on

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

Parameters:

val - - true to turn on, false for off

isClosed

public boolean isClosed()

checks to see if a transaction is closed

Returns:

boolean - true if closed, false otherwise

isPersistent

public boolean isPersistent(java.lang.Object obj)

checks to determine if a given object is persistent or not. Note If the object has manually set primary key this method will return true even if it isn't actually in the database.

Parameters:

obj - - the object to be checked

Returns:

boolean - true if the object is persistent (ie., exists in the DB); false otherwise including object created but not yet committed.

remove

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

removes an object from persistent store.

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...

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 an object creation operation for a collection of objects provided as parameters.

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 performs a simple search based on the object type to search over, the parameter name and the search value. This method will begin a new transaction and commit it before returning if it is not called from within the caller's own transaction

Note that at present this only performs very simple "single" text queries - and may be updated later..

Parameters:

type - - the persistent object type to be searched

col - - the parameter to be searched through - NB assumed to be a DB column name

val - - the value to be used for the search (all items for the type returned if null)

Returns:

a collection containing the search results

Throws:

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

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).

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 (all items for the type returned if null)

Returns:

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

Throws:

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

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

find

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

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

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

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.

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 - thrown 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.

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

removeFromCache

public void removeFromCache(java.lang.Object obj)

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

Parameters:

obj - the object to remove from the cache.

update

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

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.

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 ( isPersistent(Object) must return true).

See Also:

isPersistent(Object)

setLogger

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

allows a logging destination to be specified

Parameters:

p - A PrintWriter for logging output

addCachedClass

public void addCachedClass(java.lang.Class clazz)

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.

Parameters:

clazz - class to be cached

clearCache

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

wipe the whole cache.

Throws:

org.apache.ojb.broker.PersistenceBrokerException