com.antelmann.mgmt
Interface DBClassStore<T extends Resource>

All Known Implementing Classes:

JDBCRowProxy

public interface DBClassStore<T extends Resource>

provides persistence service for a Resource in the context of a Database. Note that all operations on a DBClassStore instance require to hold the lock on the active transaction of its Database, otherwise a TransactionException is thrown.

Author:

Holger Antelmann

See Also:

Database, DBTransaction, TransactionException, Resource

Method Summary

boolean	contains(T entry) determines whether the given entry is present in the database; it may be, however, that the database object differs from the given object (but its IDs must be the same) if present.
void	delete(T entry) removes the given entry from the database
Enumeration<T>	fetch(Filter<T> filter) filter may be null, in which case all entries from are returned.
Object	generateNewID() not every call must necessarily return a new value, but it must return an ID not yet present in the persistent storage.
Database<?>	getDatabase() provides access to the database instance that also coordinates the transaction management.
T	getResource(Object id) returns a Resource based on its ID.
void	insert(T entry) it is suggested to create the entry with an ID obtained through generateNewID() before passing it into this method.
int	size() returns the total number of T elements in this store
void	update(T entry) updates the given entry in the database.

Method Detail

getDatabase

Database<?> getDatabase()

provides access to the database instance that also coordinates the transaction management.

contains

boolean contains(T entry)
                 throws DatabaseException

determines whether the given entry is present in the database; it may be, however, that the database object differs from the given object (but its IDs must be the same) if present.

Throws:

DatabaseException

delete

void delete(T entry)
            throws DatabaseException

removes the given entry from the database

Throws:

DatabaseException

generateNewID

Object generateNewID()
                     throws DatabaseException

not every call must necessarily return a new value, but it must return an ID not yet present in the persistent storage. In particular, an unused ID (i.e. returned earlier for creating an object, but that object was never inserted and flushed into the database) may be returned again in a subsequent call much later. In general, however, the returned ID will be different on each call. As a returned ID may not be actually be used, it would be unwise to rely on the return value to generate IDs that are required to provide for a consecutive count.

Throws:

DatabaseException

insert

void insert(T entry)
            throws DatabaseException

it is suggested to create the entry with an ID obtained through generateNewID() before passing it into this method.

Throws:

DatabaseException

See Also:

generateNewID()

update

void update(T entry)
            throws DatabaseException

updates the given entry in the database. If the entry didn't exist before calling this method, a DatabaseException is thrown.

Throws:

DatabaseException

fetch

Enumeration<T> fetch(Filter<T> filter)
                                      throws DatabaseException

filter may be null, in which case all entries from are returned. As all relevant entries may not completely fit into memory, an Enumeration is returned instead of a list. Be aware that the result of the enumeration may become undefined if data is inserted/deleted/updated while the elements are accessed. To guarantee consistency, all access to the returned Enumeration must be externally synchronized by holding the monitor of the database transaction throughout maintaining the Enumeration. Note that you may have IterationExceptions being thrown on calling methods on the returned Enumeration, which are caused by either DatabaseExceptions or InstantiationExceptions on trying to fetch the next element, as not all possible errors may be caught on calling this method (as it possibly cannot instanciate all entries in advance). All access to the returned Enumeration must be made within an active transaction. To directly get all entries as a list (and thus avoid concurrency problems), consider using methods from AbstractIterator to quickly retrieve all resources before processing them.

Throws:

DatabaseException

See Also:

AbstractIterator.list(Enumeration), IterationException

getResource

T getResource(Object id)
                               throws DatabaseException

returns a Resource based on its ID.

Parameters:

id - the ID that is retrieved from Resource.getID()

Returns:

the associated resource or null if no resource is found

Throws:

DatabaseException

See Also:

Resource.getID()

size

int size()
         throws DatabaseException

returns the total number of T elements in this store

Throws:

DatabaseException