org.dlese.dpc.datamgr

Class SerializedDataManager

java.lang.Object

org.dlese.dpc.datamgr.DataManager

org.dlese.dpc.datamgr.SerializedDataManager

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

SimpleDataStore

public class SerializedDataManager
extends DataManager
implements java.io.Serializable

A Hashtable-like interface for reading and writing persistent Java objects from and to disc. 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 SerializedDataManager 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

Modifier and Type	Field and Description
protected static java.util.Hashtable	codes Converts a string that contains escaped hex encoding of the form %HEX back to plain text.Provides the inverse operation of the method encodeFileName()
protected java.lang.String	dataPath The path to the data store
protected static boolean	debug DESCRIPTION
protected java.util.Hashtable	locks DESCRIPTION
protected long	nextLockKey A unique id for locking purposes
protected long	num_records DESCRIPTION
protected java.util.Hashtable	objectCache DESCRIPTION
protected boolean	useCache DESCRIPTION
protected boolean	useFileLocks DESCRIPTION

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	decodeFileName(java.lang.String name) Decodes a String that was encoded using the method encodeFileName(String name).
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.
protected java.lang.String	encodeFileName(java.lang.String name) Encodes a String so that it is suitable for use as a file name by encoding all non letter or digit chars such as "/" and ":" into escaped hex values of the form _HEX.
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.
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.
java.lang.String[]	getIDs() Retrieves a String [] of all IDs that exist in this SerializedDataManager.
java.lang.String[]	getIDsSorted() Retrieves a String [] of all IDs that exists in this SerializedDataManager sorted lexagraphically.
long	getLastModifiedDate(java.lang.String oid) Returns the time that the object denoted by this oid was last modified.
protected boolean	getLock(java.lang.String objectPath) Gets an internal read/write lock for a given object in the this SerializedDataManager.
protected java.lang.String	getNextLockKey() Gets the nextLockKey attribute of the SerializedDataManager object
protected int	getNumFiles() Return the number of files in this DataManager as reported by the file system.
long	getNumRecords() Get the number of records in this SerializedDataManager.
boolean	isLocked(java.lang.String oid) Determine whether a given object is locked by another user.
boolean	isValidLock(java.lang.String oid, java.lang.String lockKey) Determine whether a given object is locked with the given key.
java.lang.String	lock(java.lang.String oid) Get a user-requested lock for a data object, preventing it from being written by other threads that are using this SerializedDataManager.
boolean	oidExists(java.lang.String oid) Determines whether an object with the given oid exists in the DataManager.
protected void	prtln(java.lang.String s) Print a line to standard output.
java.lang.Object	put(java.lang.String oid, java.lang.Object obj) Adds a new object of data.
protected void	releaseLock(java.lang.String objectPath) Release the read/write lock.
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.
protected java.lang.Object	restoreSerializedObject(java.lang.String oid, boolean fromCache) Restores a Serialized object from the given file path, pulling if from a RAM cache if caching indicated at construction time.
protected void	serailizeObject(java.lang.String path, java.lang.Object obj) Serializes an object to the given file path, placing it in a RAM cache if caching indicated at construction time.
static void	setDebug(boolean isDebugOutput) Sets the debug attribute of the SerializedDataManager class
boolean	unlock(java.lang.String oid, java.lang.String lockKey) Remove the lock on a data object, if it exists.
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 java.lang.Object

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

Field Detail

dataPath

protected java.lang.String dataPath

The path to the data store

debug

protected static boolean debug

DESCRIPTION

locks

protected java.util.Hashtable locks

DESCRIPTION

objectCache

protected java.util.Hashtable objectCache

DESCRIPTION

num_records

protected long num_records

DESCRIPTION

useFileLocks

protected final boolean useFileLocks

DESCRIPTION

See Also:

Constant Field Values

useCache

protected boolean useCache

DESCRIPTION

codes

protected static java.util.Hashtable codes

Converts a string that contains escaped hex encoding of the form %HEX back to plain text.Provides the inverse operation of the method encodeFileName()

nextLockKey

protected long nextLockKey

A unique id for locking purposes

Constructor Detail

SerializedDataManager

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

Constructs a new SerializedDataManager 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 SerializedDataManager, 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.

SerializedDataManager

public SerializedDataManager()

Constructor for the SerializedDataManager object, restores a serialized SerializedDataManager.

Method Detail

get

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

Retrieves a single data object. Note that if caching is turned on in this SerializedDataManager, 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).

Specified by:

get in class DataManager

Parameters:

oid - The data identifier

Returns:

Object of data

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

See Also:

getCopy(String)

getCopy

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

Retrieves a copy of a single data object, sutable for modifying. The object that is returned is safe for modifying without affecting the data that is in this SerializedDataManager.

Parameters:

oid - The data identifier.

Returns:

A copy of an Object of data that is in this SerializedDataManager.

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

See Also:

get(String)

get

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

Retrieves a List of data objects. Note that if caching is turned on in this SerializedDataManager, 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).

Specified by:

get in class DataManager

Parameters:

oids - List of data identifiers

Returns:

List of corresponding data objects

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

See Also:

getCopy(List)

getCopy

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

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

Parameters:

oids - List of data identifiers.

Returns:

List of corresponding data objects copies.

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

See Also:

get(List)

getIDs

public java.lang.String[] getIDs()

Retrieves a String [] of all IDs that exist in this SerializedDataManager. Results are not guaranteed to be in lexagraphical order, however the order is guaranteed to be in the same order from one invocation to the next.

Returns:

String [] of the IDs in this SerializedDataManager

getIDsSorted

public java.lang.String[] getIDsSorted()

Retrieves a String [] of all IDs that exists in this SerializedDataManager sorted lexagraphically.

Returns:

A lexagraphically sorted String [] of the IDs in this SerializedDataManager

getNumRecords

public long getNumRecords()

Get the number of records in this SerializedDataManager.

Returns:

The number of records in this SerializedDataManager.

put

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

Adds a new object of data. This method is safe for concurrent use among multiple processes and JVMs accessing the same SerializedDataManager.

Specified by:

put in class DataManager

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

Throws:

OIDAlreadyExistsException - If an object with given oid already exists in the data store.

ObjectNotSupportedException - If the object type is not suppored.

getLock

protected boolean getLock(java.lang.String objectPath)

Gets an internal read/write lock for a given object in the this SerializedDataManager. This method, together with releaseLock(String objectPath), provide reliable locking method for use across multiple processes or JVMs that may access the SDM data concurrently.

Parameters:

objectPath - The absolute path to the data object being stored.

Returns:

True if the lock was obtained.

releaseLock

protected void releaseLock(java.lang.String objectPath)

Release the read/write lock.

Parameters:

objectPath - The absolute path to the data object being stored.

remove

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

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.

Specified by:

remove in class DataManager

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

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

InvalidLockException - If the lock provided for the object is not valid.

remove

public java.lang.Object remove(java.lang.String oid)
                        throws OIDDoesNotExistException,
                               LockNotAvailableException

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.

Specified by:

remove in class DataManager

Parameters:

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

Returns:

The Object that was removed.

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

LockNotAvailableException - If another user currently has a lock on this object.

delete

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

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.

Specified by:

delete in class DataManager

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:

DESCRIPTION

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

InvalidLockException - If the lock provided for the object is not valid.

delete

public boolean delete(java.lang.String oid)
               throws OIDDoesNotExistException,
                      LockNotAvailableException

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.

Specified by:

delete in class DataManager

Parameters:

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

Returns:

DESCRIPTION

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

LockNotAvailableException - If another user currently has a lock on this object.

update

public java.lang.Object update(java.lang.String oid,
                               java.lang.Object obj,
                               java.lang.String lockKey)
                        throws OIDDoesNotExistException,
                               ObjectNotSupportedException,
                               InvalidLockException

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.

Specified by:

update in class DataManager

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

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

ObjectNotSupportedException - If the object type is not suppored.

InvalidLockException - If the lock provided for the object is not valid.

update

public java.lang.Object update(java.lang.String oid,
                               java.lang.Object obj)
                        throws OIDDoesNotExistException,
                               ObjectNotSupportedException,
                               LockNotAvailableException

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

Specified by:

update in class DataManager

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

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

ObjectNotSupportedException - If the object type is not suppored.

LockNotAvailableException - If another user currently has a lock on this object.

lock

public java.lang.String lock(java.lang.String oid)
                      throws OIDDoesNotExistException,
                             LockNotAvailableException

Get a user-requested lock for a data object, preventing it from being written by other threads that are using this SerializedDataManager. Note that this type of locking only works within a single instance of the SerializedDataManager. Other instances of SerializedDataManager will not know about this lock.

Specified by:

lock in class DataManager

Parameters:

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

Returns:

The key used to unlock this object.

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

LockNotAvailableException - If another user currently has a lock on this object.

getLastModifiedDate

public long getLastModifiedDate(java.lang.String oid)
                         throws OIDDoesNotExistException

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

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)

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

oidExists

public boolean oidExists(java.lang.String oid)

Determines whether an object with the given oid exists in the DataManager.

Specified by:

oidExists in class DataManager

Parameters:

oid - The unique identifier that references the data object

Returns:

True iff the given object exists in this DataManager

isLocked

public boolean isLocked(java.lang.String oid)

Determine whether a given object is locked by another user.

Specified by:

isLocked in class DataManager

Parameters:

oid - The unique identifier that references the data object

Returns:

True iff the object referred to by this oid is locked

isValidLock

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

Determine whether a given object is locked with the given key.

Specified by:

isValidLock in class DataManager

Parameters:

oid - The unique identifier that references the data object

lockKey - The lock key

Returns:

True iff the object referred to by this oid is locked with the given key

unlock

public boolean unlock(java.lang.String oid,
                      java.lang.String lockKey)
               throws OIDDoesNotExistException,
                      InvalidLockException

Remove the lock on a data object, if it exists.

Specified by:

unlock in class DataManager

Parameters:

oid - The unique identifier that references the locked data object

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

Returns:

true iff the lock has been removed for the given object regardless of whether it had been locked prior to calling this method.

Throws:

OIDDoesNotExistException - If no object exists for the given uid.

InvalidLockException - If the lock provided for the object is not valid.

serailizeObject

protected void serailizeObject(java.lang.String path,
                               java.lang.Object obj)
                        throws java.io.IOException,
                               java.io.InvalidClassException,
                               java.io.NotSerializableException

Serializes an object to the given file path, placing it in a RAM cache if caching indicated at construction time.

Parameters:

path - DESCRIPTION

obj - DESCRIPTION

Throws:

java.io.IOException - DESCRIPTION

java.io.InvalidClassException - DESCRIPTION

java.io.NotSerializableException - DESCRIPTION

restoreSerializedObject

protected java.lang.Object restoreSerializedObject(java.lang.String oid,
                                                   boolean fromCache)
                                            throws java.io.IOException,
                                                   java.lang.ClassNotFoundException

Restores a Serialized object from the given file path, pulling if from a RAM cache if caching indicated at construction time. Returns null if no file was found for the given path.

Parameters:

oid - DESCRIPTION

fromCache - DESCRIPTION

Returns:

DESCRIPTION

Throws:

java.io.IOException - DESCRIPTION

java.lang.ClassNotFoundException - DESCRIPTION

encodeFileName

protected java.lang.String encodeFileName(java.lang.String name)

Encodes a String so that it is suitable for use as a file name by encoding all non letter or digit chars such as "/" and ":" into escaped hex values of the form _HEX. Note: Unix commands cannot include the following chars: * ? ! | \ / ' " { } < > ; , ^ ( ) $ ~ Windows file names may not contain: \ / : * ? " < > | nor does Win 2000 like it when a . is at the end of the filename (it removes it when returning the file name).

Parameters:

name - The String to encode.

Returns:

An encoded String.

decodeFileName

protected java.lang.String decodeFileName(java.lang.String name)

Decodes a String that was encoded using the method encodeFileName(String name).

Parameters:

name - The string to decods.

Returns:

A decoded String.

getNumFiles

protected int getNumFiles()

Return the number of files in this DataManager as reported by the file system.

Returns:

int The number of files currently in the DataManager

getNextLockKey

protected java.lang.String getNextLockKey()

Gets the nextLockKey attribute of the SerializedDataManager object

Returns:

The nextLockKey value

setDebug

public static void setDebug(boolean isDebugOutput)

Sets the debug attribute of the SerializedDataManager class

Parameters:

isDebugOutput - The new debug value

prtln

protected void prtln(java.lang.String s)

Print a line to standard output.

Parameters:

s - DESCRIPTION