dsto.dfc.swing.persistence
Class PersistenceManager

java.lang.Object
  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.