com.admc.jamama
Interface Repository

All Superinterfaces:

Configurable

All Known Implementing Classes:

MailFolderFileRepository, MitFileRepository

public interface Repository

extends Configurable

Generic data fetcher/saver/remover interface to a storage receptacle backend like a DB or a filesystem branch. Primary keys of Objects to be stored/retrieved are generated and managed by the implementations of this interface. Therefore, primary keys do not need to be supplied to these methods. (The persist method can even ALWAYS generate a unique primary key on each call-- unless exists is set to true). DestKeys are used for many of the Repository methods below. DestKeys are used so that the repository can have multiple independent stores for multiple values with the same primary key. E.g., I could say this.persist("one"); and this.persist("two") and the DB will have saved this in two places. A particular Repository implementation may or may not permit a null destKey. In general, an implementing class will only be able to handle fetch/save/removes of specific classes. Attempts to fetch/save/remove Objects that do not implement any of these classes will cause a runtime exception.

Version:

$Revision: 1.6 $

Author:

Blaine Simpson

Method Summary

boolean	addDestKey(java.lang.String destKey) Make the supplied destKey a valid destKey.
java.lang.Object[]	arrayFetch(java.lang.String queryString, java.lang.String destKey) Fetch the reqeusted objects.
java.lang.Object	fetch(java.lang.String key, java.lang.String destKey) Fetch the requested object.
java.lang.Class[]	getPersistableClasses() Tell what classes this Repository implementation can handle.
StringSet	getValidDestKeys() Return a list of valid destination keys.
boolean	isDestKeyValid(java.lang.String destKey) Says whether the given destKey is valid.
java.lang.String	persist(java.lang.Object object, java.lang.String destKey) Store the given object.
java.lang.String	persist(java.lang.Object object, java.lang.String destKey, boolean exists) Store or update the given object.
boolean	remove(java.lang.Object object, java.lang.String destKey) Remove the given object from storage.
boolean	removeDestKey(java.lang.String destKey) Make the supplied destKey an invalid destKey.

Methods inherited from interface com.admc.jamama.Configurable

configure, getConfig, getName

Method Detail

getPersistableClasses

public java.lang.Class[] getPersistableClasses()

Tell what classes this Repository implementation can handle.

Returns:

Return an array of the classes of Objects that the Repository implementation can fetch/store/remove.

getValidDestKeys

public StringSet getValidDestKeys()

Return a list of valid destination keys.

Returns:

The destKeys that are allowed for use with the other members of this interface that have a destKey parameter. A list with 0 elements means no valid keys. A null list means all keys are valid.

isDestKeyValid

public boolean isDestKeyValid(java.lang.String destKey)

Says whether the given destKey is valid.

Parameters:

destKey - The destKey to be checked.

Returns:

Tells whether the given destKey is allowed for use with the other members of this interface that have a destKey parameter.

addDestKey

public boolean addDestKey(java.lang.String destKey)

Make the supplied destKey a valid destKey.

Parameters:

destKey - The key to be added to the valid destKey list.

Returns:

false if destKey is already valid. true otherwise.

removeDestKey

public boolean removeDestKey(java.lang.String destKey)

Make the supplied destKey an invalid destKey.

Parameters:

destKey - The key to be removed from the valid destKey list.

Returns:

false if destKey is already invalid. true otherwise.

persist

public java.lang.String persist(java.lang.Object object,
                                java.lang.String destKey)
                         throws UnsupportedClassException,
                                java.io.IOException

Store the given object. If there is no such primary key currently stored for the given destKey, then it a new record will be created; otherwise the existing record will be replaced.

Parameters:

object - The object to store. It must be an implementation of a supported class.

destKey - A valid destination key

Returns:

Primary key (generated by the Repository implementation) used to successfully store the given object).

Throws:

UnsupportedClassException - if object does not implement a supported class.

java.io.IOException

remove

public boolean remove(java.lang.Object object,
                      java.lang.String destKey)
               throws java.io.IOException

Remove the given object from storage.

Parameters:

object - The object to remove. Only the generated primary key (as generated by the Repository implementation) is used.

destKey - A valid destination key for the given stored object

Throws:

java.io.IOException

persist

public java.lang.String persist(java.lang.Object object,
                                java.lang.String destKey,
                                boolean exists)
                         throws UnsupportedClassException,
                                java.io.IOException

Store or update the given object.

Parameters:

object - The object to store. It must be an implementation of a supported class.

destKey - A valid destination key

exists - Whether the primary key (as determined by the Repository implementation) must already be in storage for the given destKey.

Returns:

Primary key (generated by the Repository implementation) used to successfully store the given object).

Throws:

UnsupportedClassException - if object does not implement a supported class.

java.io.IOException

fetch

public java.lang.Object fetch(java.lang.String key,
                              java.lang.String destKey)
                       throws java.io.IOException

Fetch the requested object.

Parameters:

key - Primary key of object to fetch

destKey - A valid destination key

Returns:

The object fetched.

Throws:

java.io.IOException

arrayFetch

public java.lang.Object[] arrayFetch(java.lang.String queryString,
                                     java.lang.String destKey)
                              throws java.io.IOException

Fetch the reqeusted objects. The queryString is used in Repository implemenation specific manner. It could be used, for example, as a space-delimited list of primary keys, or as a SQL where clause.

Parameters:

queryString - A string used by the Repository implementation to identify the subset of objects to fetch.

destKey - A valid destination key

Returns:

Array of fetched objects

Throws:

java.io.IOException