Package org.dlese.dpc.datamgr

Class SerializedDataManager

java.lang.Object
org.dlese.dpc.datamgr.DataManager
org.dlese.dpc.datamgr.SerializedDataManager
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
SimpleDataStore
public class SerializedDataManager extends DataManager implements 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:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static 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 String
    dataPath
    The path to the data store
    protected static boolean
    debug
    DESCRIPTION
    protected Hashtable
    locks
    DESCRIPTION
    protected long
    nextLockKey
    A unique id for locking purposes
    protected long
    num_records
    DESCRIPTION
    protected Hashtable
    objectCache
    DESCRIPTION
    protected boolean
    useCache
    DESCRIPTION
    protected final boolean
    useFileLocks
    DESCRIPTION

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    protected String
    decodeFileName(String name)
    Decodes a String that was encoded using the method encodeFileName(String name).
    boolean
    delete(String oid)
    Deletes an existing data object iff the object is not locked by another user.
    boolean
    delete(String oid, String lockKey)
    Deletes an existing data object, assuming the caller had requested and recieved the necessary lock.
    protected String
    encodeFileName(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.
    Object
    get(String oid)
    Retrieves a single data object.
    List
    get(List oids)
    Retrieves a List of data objects.
    Object
    getCopy(String oid)
    Retrieves a copy of a single data object, sutable for modifying.
    List
    getCopy(List oids)
    Retrieves a List of copied data objects, suitable for modifying.
    String[]
    getIDs()
    Retrieves a String [] of all IDs that exist in this SerializedDataManager.
    String[]
    getIDsSorted()
    Retrieves a String [] of all IDs that exists in this SerializedDataManager sorted lexagraphically.
    long
    getLastModifiedDate(String oid)
    Returns the time that the object denoted by this oid was last modified.
    protected boolean
    getLock(String objectPath)
    Gets an internal read/write lock for a given object in the this SerializedDataManager.
    protected 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(String oid)
    Determine whether a given object is locked by another user.
    boolean
    isValidLock(String oid, String lockKey)
    Determine whether a given object is locked with the given key.
    String
    lock(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(String oid)
    Determines whether an object with the given oid exists in the DataManager.
    protected void
    prtln(String s)
    Print a line to standard output.
    Object
    put(String oid, Object obj)
    Adds a new object of data.
    protected void
    releaseLock(String objectPath)
    Release the read/write lock.
    Object
    remove(String oid)
    Removes an existing data object iff the object is not locked by another user.
    Object
    remove(String oid, String lockKey)
    Removes an existing data object, assuming the caller had requested and recieved the necessary lock for the object.
    protected Object
    restoreSerializedObject(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(String path, 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(String oid, String lockKey)
    Remove the lock on a data object, if it exists.
    Object
    update(String oid, Object obj)
    Updates a new object of data iff the object is not locked by another user.
    Object
    update(String oid, Object obj, 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 Details

    • dataPath

      protected String dataPath
      The path to the data store

    • debug

      protected static boolean debug
      DESCRIPTION

    • locks

      protected Hashtable locks
      DESCRIPTION

    • objectCache

      protected Hashtable objectCache
      DESCRIPTION

    • num_records

      protected long num_records
      DESCRIPTION

    • useFileLocks

      protected final boolean useFileLocks
      DESCRIPTION
      See Also:

    • useCache

      protected boolean useCache
      DESCRIPTION

    • codes

      protected static 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 Details

    • SerializedDataManager

      public SerializedDataManager(String dataPath, boolean useCache) throws 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:
      Exception - If error.

    • SerializedDataManager

      public SerializedDataManager()
      Constructor for the SerializedDataManager object, restores a serialized SerializedDataManager.

  • Method Details

    • get

      public Object get(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

      public Object getCopy(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

      public List get(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

      public List getCopy(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:

    • getIDs

      public 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 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 Object put(String oid, 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(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(String objectPath)
      Release the read/write lock.
      Parameters:
      objectPath - The absolute path to the data object being stored.

    • remove

      public Object remove(String oid, 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 Object remove(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(String oid, 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(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 Object update(String oid, Object obj, 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 Object update(String oid, 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 String lock(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(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(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(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(String oid, 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(String oid, 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(String path, Object obj) throws IOException, InvalidClassException, 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:
      IOException - DESCRIPTION
      InvalidClassException - DESCRIPTION
      NotSerializableException - DESCRIPTION

    • restoreSerializedObject

      protected Object restoreSerializedObject(String oid, boolean fromCache) throws IOException, 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:
      IOException - DESCRIPTION
      ClassNotFoundException - DESCRIPTION

    • encodeFileName

      protected String encodeFileName(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: * ? ! | \ / ' " { } invalid input: '<' > ; , ^ ( ) $ ~ Windows file names may not contain: \ / : * ? " invalid input: '<' > | 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 String decodeFileName(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 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(String s)
      Print a line to standard output.
      Parameters:
      s - DESCRIPTION