org.dlese.dpc.datamgr

Class SimpleDataStore

java.lang.Object

org.dlese.dpc.datamgr.DataManager

org.dlese.dpc.datamgr.SerializedDataManager

org.dlese.dpc.datamgr.SimpleDataStore

All Implemented Interfaces:

java.io.Serializable

public class SimpleDataStore
extends SerializedDataManager
implements java.io.Serializable

A Hashtable-like interface for reading and writing persistent Java objects from and to disc. Same as SerializedDataManager except the getter and setter methods return null insted of throwing exceptions. Objects are stored in serialized form on disc - any object that implements Serializable can be stored in this DataManager for persistent retrieval. The objects can also be held in a RAM cache to provide faster retrieval. Serialized objects are stored in a directory specified at the time of construction. Objects stored in a SimpleDataStore can be of mixed type. This class is safe to use with multiple process and/or JVMs that access the same dataPath concurrently.

Author:

John Weatherley

See Also:

Serialized Form

Field Summary

Fields inherited from class org.dlese.dpc.datamgr.SerializedDataManager

codes, dataPath, debug, locks, nextLockKey, num_records, objectCache, useCache, useFileLocks

Constructor Summary

Constructors

Constructor and Description
SimpleDataStore() Constructor for the SimpleDataStore object, restores a serialized SimpleDataStore.
SimpleDataStore(java.lang.String dataPath, boolean useCache) Constructs a new SimpleDataStore that reads and writes data to the given dataPath directory.

Method Summary

Modifier and Type	Method and Description
boolean	delete(java.lang.String oid) Deletes an existing data object iff the object is not locked by another user.
boolean	delete(java.lang.String oid, java.lang.String lockKey) Deletes an existing data object, assuming the caller had requested and recieved the necessary lock.
java.util.List	get(java.util.List oids) Retrieves a List of data objects.
java.lang.Object	get(java.lang.String oid) Retrieves a single data object, or null if none exists or unable to retrieve.
java.util.List	getCopy(java.util.List oids) Retrieves a List of copied data objects, suitable for modifying.
java.lang.Object	getCopy(java.lang.String oid) Retrieves a copy of a single data object, sutable for modifying, or null if none exists or unable to retrieve.
long	getLastModifiedDate(java.lang.String oid) Returns the time that the object denoted by this oid was last modified.
java.lang.Object	put(java.lang.String oid, java.lang.Object obj) Adds a new object of data, replacing the existing one if one exists and is not locked.
java.lang.Object	put(java.lang.String oid, java.lang.Object obj, java.lang.String lockKey) Adds a new object of data, replacing the existing one if one exists and it can be unlocked with the given key.
java.lang.Object	remove(java.lang.String oid) Removes an existing data object iff the object is not locked by another user.
java.lang.Object	remove(java.lang.String oid, java.lang.String lockKey) Removes an existing data object, assuming the caller had requested and recieved the necessary lock for the object.
java.lang.Object	update(java.lang.String oid, java.lang.Object obj) Updates a new object of data iff the object is not locked by another user.
java.lang.Object	update(java.lang.String oid, java.lang.Object obj, java.lang.String lockKey) Updates a new object of data, assuming the caller had requested and recieved the necessary lock.

Methods inherited from class org.dlese.dpc.datamgr.SerializedDataManager

decodeFileName, encodeFileName, getIDs, getIDsSorted, getLock, getNextLockKey, getNumFiles, getNumRecords, isLocked, isValidLock, lock, oidExists, prtln, releaseLock, restoreSerializedObject, serailizeObject, setDebug, unlock

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleDataStore

public SimpleDataStore(java.lang.String dataPath,
                       boolean useCache)
                throws java.lang.Exception

Constructs a new SimpleDataStore that reads and writes data to the given dataPath directory. Allows control over whether or not to hold a cache of the objects in RAM memory for faster retrieval. Note that if caching is turned on in this SimpleDataStore, the objects that are returned from the get(String) and get(List) methods are not safe to modify. Specifically, any changes made to the objects will be reflected in subsequent calls to those methods. To get a copy of the data items that are safe to modify the caller should use the getCopy(String) or getCopy(List) methods instead. If caching is not turned on, the effect of the get methods are the same as the getCopy methods.

This class is safe to use with multiple process and/or JVMs that access the same dataPath.

Parameters:

dataPath - The directory where the serialzed objects are stored.

useCache - Indicates whether to cache the objects in RAM memory for faster retrievel.

Throws:

java.lang.Exception - If error.

SimpleDataStore

public SimpleDataStore()

Constructor for the SimpleDataStore object, restores a serialized SimpleDataStore.

Method Detail

get

public java.lang.Object get(java.lang.String oid)

Retrieves a single data object, or null if none exists or unable to retrieve. Note that if caching is turned on in this SimpleDataStore, the object that is returned is not safe to modify. Specifically, if caching is enabled, any changes made to that object will be reflected in subsequent calls to this method and the get(List) method. To get a copy of a data item that is safe to modify use the getCopy(String) method instead. If caching is not enabled, the effect of this method is the same as getCopy(String).

Overrides:

get in class SerializedDataManager

Parameters:

oid - The data identifier

Returns:

Object of data or null.

See Also:

getCopy(String)

getCopy

public java.lang.Object getCopy(java.lang.String oid)

Retrieves a copy of a single data object, sutable for modifying, or null if none exists or unable to retrieve. The object that is returned is safe for modifying without affecting the data that is in this SimpleDataStore.

Overrides:

getCopy in class SerializedDataManager

Parameters:

oid - The data identifier.

Returns:

A copy of an Object of data that is in this SimpleDataStore or null.

See Also:

get(String)

get

public java.util.List get(java.util.List oids)

Retrieves a List of data objects. Note that if caching is turned on in this SimpleDataStore, the objects that are returned are not safe to modify. Specifically, if caching is enabled, any changes made to the objects will be reflected in subsequent calls to this method and the get(String) method. To get a copy of a data items that are safe to modify use the getCopy(List) method instead. If caching is not ebabled, the effect of this method is the same as getCopy(List).

Overrides:

get in class SerializedDataManager

Parameters:

oids - List of data identifiers

Returns:

List of corresponding data objects

See Also:

getCopy(List)

getCopy

public java.util.List getCopy(java.util.List oids)

Retrieves a List of copied data objects, suitable for modifying. The objects that are returned are safe for modifying without affecting the data that is in this SimpleDataStore.

Overrides:

getCopy in class SerializedDataManager

Parameters:

oids - List of data identifiers.

Returns:

List of corresponding data objects copies.

See Also:

get(List)

remove

public java.lang.Object remove(java.lang.String oid,
                               java.lang.String lockKey)

Removes an existing data object, assuming the caller had requested and recieved the necessary lock for the object. After successful completion the object is removed from the DataManager and returned to the caller.

Overrides:

remove in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object to be removed

lockKey - The key corresponding to the lock on this data object

Returns:

The removed data object iff successful, otherwise null

remove

public java.lang.Object remove(java.lang.String oid)

Removes an existing data object iff the object is not locked by another user. If the object is locked a LockNotAvailableException is thrown. After successful completion the object is removed from the DataManager and returned to the caller.

Overrides:

remove in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object to be removed

Returns:

The Object that was removed, or null.

delete

public boolean delete(java.lang.String oid,
                      java.lang.String lockKey)

Deletes an existing data object, assuming the caller had requested and recieved the necessary lock. Similar to remove() except no object is returned and thus is more efficient if an object is not required.

Overrides:

delete in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object to be deleted

lockKey - The key corresponding to the lock on this data object

Returns:

True if object was successfully deleted, otherwise false.

delete

public boolean delete(java.lang.String oid)

Deletes an existing data object iff the object is not locked by another user. If the object is locked a LockNotAvailableException is thrown. Similar to remove() except no object is returned and thus is more efficient. After successful completion the object is deleted from the DataManager.

Overrides:

delete in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object to be deleted

Returns:

True if object was successfully deleted, otherwise false.

put

public java.lang.Object put(java.lang.String oid,
                            java.lang.Object obj)

Adds a new object of data, replacing the existing one if one exists and is not locked. This method is safe for concurrent use among multiple processes and JVMs accessing the same SimpleDataStore.

Overrides:

put in class SerializedDataManager

Parameters:

oid - The unique identifier that references the new data object

obj - The new data object

Returns:

The added data object iff successful, otherwise null

put

public java.lang.Object put(java.lang.String oid,
                            java.lang.Object obj,
                            java.lang.String lockKey)

Adds a new object of data, replacing the existing one if one exists and it can be unlocked with the given key. The caller retains the lock after this method returns. This method is safe for concurrent use among multiple processes and JVMs accessing the same SimpleDataStore.

Parameters:

oid - The unique identifier that references the new data object

obj - The new data object

lockKey - The key corresponding to the lock on this data object

Returns:

The added data object iff successful, otherwise null

update

public java.lang.Object update(java.lang.String oid,
                               java.lang.Object obj,
                               java.lang.String lockKey)

Updates a new object of data, assuming the caller had requested and recieved the necessary lock. The caller retains the lock after this method returns.

Overrides:

update in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object to be updated

obj - The new updated data object

lockKey - The key corresponding to the lock on this data object

Returns:

The updated data object, if successful otherwise null

update

public java.lang.Object update(java.lang.String oid,
                               java.lang.Object obj)

Updates a new object of data iff the object is not locked by another user. If the object is locked a LockNotAvailableException is thrown.

Overrides:

update in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object to be updated

obj - The new updated data object

Returns:

The updated data object, if successful otherwise null.

getLastModifiedDate

public long getLastModifiedDate(java.lang.String oid)

Returns the time that the object denoted by this oid was last modified.

Overrides:

getLastModifiedDate in class SerializedDataManager

Parameters:

oid - The unique identifier that references the data object

Returns:

A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or -1 if the oid does not exist.