dsto.dfc.swing.persistence
Class PersistenceManager

java.lang.Object
  extended by dsto.dfc.swing.persistence.PersistenceManager

public class PersistenceManager
extends Object

A lightweight persistent object manager. Maintains a set of persistent objects, loading, unloading and saving modified objects as required. Each managed object is accessed via a logical key: clients may register new persistent objects (registerObject(String, Object)), lookup existing objects (findObject(java.lang.String)) and mark objects modified (objectModified(java.lang.String)). Objects that fire StateChangeEvent's are automatically marked changed by the manager. The manager ensures modifed objects are periodically saved and that unreferenced objects are unloaded in response to memory demand using the Java weak reference system.

Version:
$Revision$
Author:
Matthew

Field Summary
protected  dsto.dfc.swing.persistence.PersistenceManager.Housekeeper housekeeper
           
protected  CountedSet modifiedObjects
           
protected  HashMap objects
          Maps object key to PersistentRef instance.
protected  ReferenceQueue refQueue
           
protected  String storageDir
          The default storage directory for objects.
 
Constructor Summary
PersistenceManager(String storageDir)
          Creates a new PersistenceManager instance.
 
Method Summary
 Object findObject(String key)
          Lookup a previously registered persistent object.
 Object findObject(String key, ISerializer serializer)
          Lookup a previously registered persistent object.
 Object findObject(String key, String dir)
          Lookup a previously registered persistent object.
 Object findObject(String key, String dir, ISerializer serializer)
          Lookup a previously registered persistent object.
 Object getModifyLock()
          Get the object that is locked by the manager when modifying state.
 boolean isModified(String key)
           
 String[] listObjects()
          Retrieve the list of all available persistent objects.
 String[] listObjects(Selector selector)
          Retrieve the list of all available persistent objects matching a given selector.
 String[] listObjects(String dir)
          Retrieve the list of all available persistent objects.
 String[] listObjects(String dir, Selector selector)
          Retrieve the list of all available persistent objects matching a given selector.
 void objectAccessed(Object object)
          Manually signal that a persistent object has been accessed.
 void objectModified(Object object)
          Mark an object as modified.
 void objectModified(String key)
          Mark an object as modified.
 String pathForKey(String key)
          The default path used to store serialized data for a given key.
 String pathForKey(String dir, String key)
          The path used to store serialized data for a given key dir storage directory.
 void registerObject(String key, Object object)
          Register a new persistent object using the default Java serialization format.
 void registerObject(String key, Object object, ISerializer serializer)
          Register a new persistent object.
 void registerObject(String key, String dir, Object object)
          Register a new persistent object.
 void registerObject(String key, String dir, Object object, ISerializer serializer)
          Register a new persistent object.
 void saveModified()
          Save all modified objects.
 void saveModified(boolean forceSaveAll)
          Save modified objects.
 void shutdown()
          Perform a controlled shutdown of the manager.
protected  void unlockStaleObjects()
          Unlock any unmodified objects that have not been accessed for 30 seconds, freeing them for GC.
 void unregisterObject(String key)
          Deprecated.  
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

storageDir

protected String storageDir
The default storage directory for objects. This may be overridden on a per-object basis.


objects

protected HashMap objects
Maps object key to PersistentRef instance.


modifiedObjects

protected final CountedSet modifiedObjects

refQueue

protected final ReferenceQueue refQueue

housekeeper

protected final dsto.dfc.swing.persistence.PersistenceManager.Housekeeper housekeeper
Constructor Detail

PersistenceManager

public PersistenceManager(String storageDir)
Creates a new PersistenceManager instance.

Parameters:
storageDir - The base directory for persistent storage. Serialized objects are saved here using filenames derived from their logical keys.
Method Detail

getModifyLock

public Object getModifyLock()
Get the object that is locked by the manager when modifying state. Multithreaded clients can use this to ensure atomicity of mutiple method calls (eg findObject () and registerObject ()).

Returns:
an Object value

pathForKey

public String pathForKey(String key)
The default path used to store serialized data for a given key. NOTE: This may not be the actual path if the storage directory is explicity set for an object.

See Also:
pathForKey(String, String)

pathForKey

public String pathForKey(String dir,
                         String key)
The path used to store serialized data for a given key dir storage directory.

Parameters:
dir - The storage directory.
key - The key.
Returns:
The storage path.

registerObject

public void registerObject(String key,
                           Object object)
                    throws IllegalArgumentException
Register a new persistent object using the default Java serialization format.

Throws:
IllegalArgumentException - if key is already in use.
See Also:
registerObject(String, Object, ISerializer)

registerObject

public void registerObject(String key,
                           String dir,
                           Object object)
Register a new persistent object.

Parameters:
key - The logical key for the object. This is used for subsequent access (eg see (findObject(java.lang.String)).
dir - The base directory for the saved object.
object - The object to be managed. Note, this object is not automatically considered to be modified, and will not be serialized until a call to objectModified() is made or the object fires a change event.
Throws:
IllegalArgumentException - if key is already in use.
See Also:
registerObject(String,Object), objectModified(String)

registerObject

public void registerObject(String key,
                           Object object,
                           ISerializer serializer)
                    throws IllegalArgumentException
Register a new persistent object.

Parameters:
key - The logical key for the object. This is used for subsequent access (eg see (findObject(java.lang.String)).
object - The object to be managed. Note, this object is not automatically considered to be modified, and will not be serialized until a call to objectModified() is made or the object fires a change event.
serializer - The serializer for the object.
Throws:
IllegalArgumentException - if key is already in use.
See Also:
registerObject(String,Object), objectModified(String)

registerObject

public void registerObject(String key,
                           String dir,
                           Object object,
                           ISerializer serializer)
                    throws IllegalArgumentException
Register a new persistent object.

Parameters:
key - The logical key for the object. This is used for subsequent access (eg see (findObject(java.lang.String)).
dir - The base directory for the saved object.
object - The object to be managed. Note, this object is not automatically considered to be modified, and will not be serialized until a call to objectModified() is made or the object fires a change event.
serializer - The serializer for the object.
Throws:
IllegalArgumentException - if key is already in use.
See Also:
registerObject(String,Object), objectModified(String)

findObject

public Object findObject(String key)
                  throws IOException
Lookup a previously registered persistent object. Note for multithreaded clients: to stop race conditions between two threads that call findObject () and then registerObject () if the object is not found, ensure that these calls are done in a synchronized block using getModifyLock().

Parameters:
key - The key for the object
Returns:
The object, or null if not defined.
Throws:
IOException - If an error occurred reading a previously saved store.
See Also:
registerObject(String, Object, ISerializer)

findObject

public Object findObject(String key,
                         ISerializer serializer)
                  throws IOException
Lookup a previously registered persistent object. Note for multithreaded clients: to stop race conditions between two threads that call findObject () and then registerObject () if the object is not found, ensure that these calls are done in a synchronized block using getModifyLock().

Parameters:
key - The key for the object
serializer - The serializer to use if the object needs to be loaded.
Returns:
The object, or null if not defined.
Throws:
IOException - If an error occurred reading a previously saved store.
See Also:
registerObject(String,Object,ISerializer)

findObject

public Object findObject(String key,
                         String dir)
                  throws IOException
Lookup a previously registered persistent object. Note for multithreaded clients: to stop race conditions between two threads that call findObject () and then registerObject () if the object is not found, ensure that these calls are done in a synchronized block using getModifyLock().

Parameters:
key - The key for the object.
dir - The directory to look for the object.
Returns:
The object, or null if not defined.
Throws:
IOException - If an error occurred reading a previously saved store.
See Also:
registerObject(String,Object,ISerializer)

findObject

public Object findObject(String key,
                         String dir,
                         ISerializer serializer)
                  throws IOException
Lookup a previously registered persistent object. Note for multithreaded clients: to stop race conditions between two threads that call findObject () and then registerObject () if the object is not found, ensure that these calls are done in a synchronized block using getModifyLock().

Parameters:
key - The key for the object
dir - The directory to look for the object.
serializer - The serializer to use if the object needs to be loaded.
Returns:
The object, or null if not defined.
Throws:
IOException - If an error occurred reading a previously saved store.
See Also:
registerObject(String,Object,ISerializer)

listObjects

public String[] listObjects()
Retrieve the list of all available persistent objects.

Returns:
The set of all available object keys.
See Also:
listObjects(Selector)

listObjects

public String[] listObjects(String dir)
Retrieve the list of all available persistent objects.

Parameters:
dir - The directory to search for saved objects.
Returns:
The set of all available object keys.
See Also:
listObjects(Selector)

listObjects

public String[] listObjects(Selector selector)
Retrieve the list of all available persistent objects matching a given selector.

Parameters:
selector - A selector instance that is used to select object keys.
Returns:
The set of matched object keys.

listObjects

public String[] listObjects(String dir,
                            Selector selector)
Retrieve the list of all available persistent objects matching a given selector.

Parameters:
dir - The directory to search for saved objects.
selector - A selector instance that is used to select object keys.
Returns:
The set of matched object keys.

unregisterObject

public void unregisterObject(String key)
Deprecated. 

NOTE: not currently implemented.


objectModified

public void objectModified(String key)
Mark an object as modified. The object will be saved at the next opportunity.

Parameters:
key - The key for the object.
See Also:
objectModified(Object)

objectModified

public void objectModified(Object object)
Mark an object as modified. The object will be saved at the next opportunity.

Parameters:
object - The object.
See Also:
objectModified(String)

objectAccessed

public void objectAccessed(Object object)
Manually signal that a persistent object has been accessed. This serves as as a hint not to unload the object. This is automatically done whenever findObject () is called or the object is modified.


isModified

public boolean isModified(String key)

saveModified

public void saveModified()
Save all modified objects.


saveModified

public void saveModified(boolean forceSaveAll)
Save modified objects.

Parameters:
forceSaveAll - Force save of all modified objects. If not true, only objects not recently modified (last 10 secs) or not saved for 2 mins are saved.

unlockStaleObjects

protected void unlockStaleObjects()
Unlock any unmodified objects that have not been accessed for 30 seconds, freeing them for GC.


shutdown

public void shutdown()
Perform a controlled shutdown of the manager. This should be called before system shutdown to ensure no data is lost.



Copyright © 2008 Commonwealth of Australia