org.iperg.part.persistency
Class IpRmsPersistencyManager

java.lang.Object
  org.iperg.part.persistency.IpRmsPersistencyManager

All Implemented Interfaces:

IpEventHandler, IpPersistencyManager

public class IpRmsPersistencyManager
extends java.lang.Object
implements IpPersistencyManager, IpEventHandler

The IpRmsPersistencyManager class defines a persistency manager that uses a record store to save and load objects and identifiers. On J2ME platforms, the manager uses the record store provided by the Java API. On J2SE platforms, the manager uses a record store library based on ordinary disk files.

Field Summary

Fields inherited from interface org.iperg.part.persistency.IpPersistencyManager

ON_CHANGE, ON_TIMER

Method Summary

boolean	contains(IpIdentifier objId) Check if the state of a given object has been saved in the record store.
boolean	contains(java.lang.String name) Check if the state of a given object has been saved in the record store.
static IpRmsPersistencyManager	getInstance() The main access method to retrieve the singleton RMS persistency manager instance.
int	getPersistOnTimerInterval() Get the interval of the peristency manager timer.
void	handleEvent(IpEvent event) Is called by PART whenever an event has been generated in the local process or received from the network.
IpObject	load(IpIdentifier objId) Load an object which has been previously saved in the persistency store.
IpObject	load(java.lang.String name) Load an object which has been previously saved in the persistency store.
IpObject[]	loadAll() Load and return all objects saved in the persistency store.
IpIdentifier	loadId(java.lang.String name) Load an identifier which has previously been saved using saveId.
void	persist(IpObject obj, java.lang.String name, int when) Save the state of the object repeatedly as specified by the when paramater.
void	remove(IpIdentifier objId) Remove the saved state of the given object.
void	remove(java.lang.String name) Remove the saved state of the given object.
void	removeAll() Remove the contents of the persistency store.
void	removeId(java.lang.String name) Remove an identifier which has previously been saved using saveId.
void	save(IpObject obj, java.lang.String name) Save the state of an object in the persistency store.
void	saveId(IpIdentifier id, java.lang.String name) Save an identifier in the store and associate it to a name.
void	setPersistOnTimerInterval(int interval) Set the interval of the peristency manager timer.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static IpRmsPersistencyManager getInstance()

The main access method to retrieve the singleton RMS persistency manager instance. Will create the singleton instance if it doesn't already exist.

Returns:

The RMS persistency manager singleton instance

handleEvent

public void handleEvent(IpEvent event)

Is called by PART whenever an event has been generated in the local process or received from the network.

Specified by:

handleEvent in interface IpEventHandler

Parameters:

event - The event

removeAll

public void removeAll()
               throws IpException

Remove the contents of the persistency store. Will remove all saved objects and also all name to identifier mappings created via getId.

Specified by:

removeAll in interface IpPersistencyManager

Throws:

IpException - if an exception occurs while the content is removed.

persist

public void persist(IpObject obj,
                    java.lang.String name,
                    int when)
             throws IpException

Save the state of the object repeatedly as specified by the when paramater. Will also cause the object to be saved immediately, If the name parameter is null and the object hasn't been saved before, the object is not associated to a name when saved. If the parameter is null and the object has been saved before, the object will be associated to the same name as was given when previously saved (may be null). If persits is called several times for the same object, the new association will replace the old one (unless the new value of name is null).

Possible values of the when parameter are:

• ON_CHANGE - Means that the object will be saved soon as it has been modified. Modifications that will trigger a save are additions, removals and updates of properties.
• ON_TIMER - Means that if the object has been modified, it will be saved the next time the persistency manager timer triggers (see getPersistOnTimerInterval and setPersistOnTimerInterval). Note that the object is only saved when the timer trigger if it has been modified since the last time the timer was triggered.

If the persist method is called several times for the same object, but with different values for the when parameter, only the last value will be used. I.e., if an object was previously persisted using ON_CHANGE, and persits is called with ON_TIMER, the object will only be peristed on timer triggers, not on changes.

Specified by:

persist in interface IpPersistencyManager

Parameters:

obj - The object

name - The name to which the object will be associated when saved (may be null)

when - Determines when the object will be saved

Throws:

IpException - if an exception occurs while saving the state.

getPersistOnTimerInterval

public int getPersistOnTimerInterval()

Get the interval of the peristency manager timer. The timer will trigger once every interval milliseconds.

The timer contols how often objects that have been persisted using ON_TIMER (see persist) are saved if modified.

Returns:

Interval in milliseconds

setPersistOnTimerInterval

public void setPersistOnTimerInterval(int interval)

Set the interval of the peristency manager timer. The timer will trigger once every interval milliseconds.

The timer contols how often objects that have been persisted using ON_TIMER (see persist) are saved if modified.

Parameters:

interval - Interval in milliseconds. Must be > 0.

save

public void save(IpObject obj,
                 java.lang.String name)
          throws IpException

Save the state of an object in the persistency store. May be called several times to update the state saved in the store. The object will be associated to the given name (if not null), which means that it can later be loaded using the name only:

 IpPersistencyManager pm = ...;
 pm.save(obj, "test");
 ..
 obj = pm.load("test");

If the name parameter is null and the object hasn't been saved before, the object is not associated to any name when saved. If the parameter is null and the object has been saved before, the object will be associated to the same name as was given when previously saved (may be null).

Specified by:

save in interface IpPersistencyManager

Parameters:

obj - The object whose state should be saved

name - A name to which the object will be associated, may be null

Throws:

IpException - if an exception occurs while saving the state.

load

public IpObject load(IpIdentifier objId)
              throws IpException

Load an object which has been previously saved in the persistency store.

Specified by:

load in interface IpPersistencyManager

Parameters:

objId - The identifier of the object that should be loaded loaded

Returns:

Object if found, null otherwise

Throws:

IpException - if an exception occurs while loading the state.

load

public IpObject load(java.lang.String name)
              throws IpException

Load an object which has been previously saved in the persistency store.

Specified by:

load in interface IpPersistencyManager

Parameters:

name - The name that was associated to the object when saved

Returns:

Object if found, null otherwise

Throws:

IpException - if an exception occurs while loading the state.

loadAll

public IpObject[] loadAll()
                   throws IpException

Load and return all objects saved in the persistency store. If an object that is loaded already exists in the local process, the state of the existing object will be overwritten with the state loaded from the persistency store.

Specified by:

loadAll in interface IpPersistencyManager

Returns:

An array of objects loaded from the store. If no objects were loaded, null is returned.

Throws:

IpException - if an exception occurs while loading the store content.

contains

public boolean contains(IpIdentifier objId)
                 throws IpException

Check if the state of a given object has been saved in the record store.

Specified by:

contains in interface IpPersistencyManager

Parameters:

objId - The object identifier

Returns:

true

if the object's state has been saved,

false

otherwise

Throws:

IpException - if an exception occurs while checking if the object is saved in the store.

contains

public boolean contains(java.lang.String name)
                 throws IpException

Check if the state of a given object has been saved in the record store.

Specified by:

contains in interface IpPersistencyManager

Parameters:

name - The name to which the object has been associated when saved

Returns:

true

if the object's state has been saved,

false

otherwise

Throws:

IpException - if an exception occurs while checking if the object is saved in the store.

remove

public void remove(IpIdentifier objId)
            throws IpException

Remove the saved state of the given object. Will also cancel the effect of any previous call to

persist

or

persistAll

for the object.

Specified by:

remove in interface IpPersistencyManager

Parameters:

objId - The identifier of the object whose state should be removed

Throws:

IpException - if an exception occurs while the object is removed.

remove

public void remove(java.lang.String name)
            throws IpException

Remove the saved state of the given object. Will also cancel the effect of any previous call to

persist

or

persistAll

for the object.

Specified by:

remove in interface IpPersistencyManager

Parameters:

name - The name under which the object is stored

Throws:

IpException - if an exception occurs while the object is removed.

loadId

public IpIdentifier loadId(java.lang.String name)
                    throws IpException

Load an identifier which has previously been saved using saveId.

Specified by:

loadId in interface IpPersistencyManager

Parameters:

name - The name that was given when the identifier was saved

Returns:

The identifier if found, null otherwise

Throws:

IpException - if an exception occurs while the identifer is loaded.

saveId

public void saveId(IpIdentifier id,
                   java.lang.String name)
            throws IpException

Save an identifier in the store and associate it to a name. The name can later be used to load the identifier via loadId.

If an identifier is already saved under the given name, it will be overwritten.

Specified by:

saveId in interface IpPersistencyManager

Parameters:

id - The identifier to save

name - The name to which the identifier will be associated. May not be null.

Throws:

IpException - if an exception occurs while the identifer is saved.

removeId

public void removeId(java.lang.String name)
              throws IpException

Remove an identifier which has previously been saved using saveId.

Specified by:

removeId in interface IpPersistencyManager

Parameters:

name - The name that was given when the identifier was saved

Throws:

IpException - if an exception occurs while the identifer is loaded.