org.globus.wsrf.impl
Class PersistentReflectionResource

java.lang.Object
  |
  +--org.globus.wsrf.impl.ReflectionResource
        |
        +--org.globus.wsrf.impl.PersistentReflectionResource

All Implemented Interfaces:

PersistentResource, RemoveCallback, ResourceIdentifier, ResourceProperties

public abstract class PersistentReflectionResource

extends ReflectionResource

implements RemoveCallback, PersistentResource

A persistent specialization of ReflectionResource. It persists itself by serializing the resource implementation JavaBean used in constructing an object as a ReflectionResource. The result of storing the resource is an XML file that corresponds exactly to the XML Schema Resource document defined for this resource. Future versions will offer alternative modes of persistence.

This class can be very useful for rapid prototyping of persistent resources. In addition, it is possible to refine the persistence model by overriding the load() and store() methods.

Usage:

• extend this class by implementing the function getResourceBeanClass.
• apply usage rules for extending ReflectionResource:
  • override initialize() in order to add run-time-defined resource properties and/or topics.
  • add specialized behavior, for instance domain-specific functions.
• As a resource home, use a specialization of a PersistentResource-managing ResourceHome such as PersistentResourceHome and follow its set of usage rules.
• initialize the objects by calling initialize.
• Call the store() method after initial creation of the resource (since this is not triggered by PersistentResourceHome), and then whenever adequate (for instance when a resource property value, or a set thereof, is modified). Remember to set the dirty flag to true first. (see setDirty)

Refining the persistence model:

The default persistence model implemented by this class may be sufficient in most simple cases, but refining it may sometimes make sense, for instance in cases where:

• when it is not necessary to persist every resource property.
• when there is some implementation state that needs to be stored that is not a resource property.

Note: The implementation of this class use the PerformanceLogger in order to log the duration of storing and loading the resource. The log subcategory is performance.

Dirty flag:

A dirty flag is set to true every time a resource property of the Schema-defined resource property set is set to a new value. This enables to optimize storing so the resource is not actually persisted each time it is passivated by PersistentResourceHome. (note: maybe this is overkill and not necessary?)

See Also:

ReflectionResource, PersistentResourceHome, PersistentResource, RemoveCallback

Constructor Summary

PersistentReflectionResource()

Method Summary

protected ResourceProperty	createNewResourceProperty(QName rpQName, Object resourceBean) Override this callback method to specialize the implementation of the resource property value accessors on a per resource property basis.
boolean	getDirty()
protected File	getKeyAsFile(Object key) Create a file object based on the key supplied in parameter.
protected abstract Class	getResourceBeanClass()
protected File	getStorageDirectory()
List	getStoredResourceKeyValues() This function returns the keys of the resources that have been stored.
void	load(ResourceKey key) Called by PersistentResourceHome when activating a resource.
void	remove() Notifies that the resource was removed.
void	setDirty(boolean changed) Sets the dirty flag on this persistent object.
void	store() Store the resource into an XML document (current implementation).

Methods inherited from class org.globus.wsrf.impl.ReflectionResource

getCurrentTime, getID, getResourceBean, getResourcePropertySet, initialize

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.globus.wsrf.ResourceIdentifier

getID

Constructor Detail

PersistentReflectionResource

public PersistentReflectionResource()

Method Detail

getResourceBeanClass

protected abstract Class getResourceBeanClass()

Returns:

Class The class of the Axis-generated Serializable implementation bean for the resource property set. See ReflectionResource.

load

public void load(ResourceKey key)
          throws ResourceException

Called by PersistentResourceHome when activating a resource. This is called after an instance has been created with the parameterless constructor, so nothing has been initialized yet. After deserialization, this calls initialize() so as to initialize the resource properly, with its key and the stored state of its resource properties.

If the resource was successfully loaded, its dirty flag is set to false.

Postcondition getDirty() == false

Specified by:

load in interface PersistentResource

See Also:

setDirty(), PersistentResource

store

public void store()
           throws ResourceException

Store the resource into an XML document (current implementation). The name of the file is governed by getKeyAsFile(). This stores the state of the implementation JAvaBean. If some resource properties have been implemented with something else (for instance getters and setters from another object) they will not be persisted with the current state. This is not a problem if their state is immutable after initial creation, as their values will be set by initialize, ReflectionResource.initialize()} which is called by this method. (TODO: persist based on each RP?)

If the resource was successfully stored, its dirty flag is set to false.

Postcondition getDirty() == false

Specified by:

store in interface PersistentResource

Throws:

ResourceException - if the resource could not be stored

See Also:

setDirty(), getKeyAsFile(), PersistentResource

getKeyAsFile

protected File getKeyAsFile(Object key)

Create a file object based on the key supplied in parameter. The file name will follow the format:

file name :== (class name)_(key scalar value).xml

where:

• (class name) is class name of the implementation resource bean.
• (key scalar value) is the toString value of the key passed in parameter. If the key is an instance of ResourceKey, its value is the result of key.getValue().

Parameters:

key - Object the key of the resource

Returns:

File

getStorageDirectory

protected File getStorageDirectory()

remove

public void remove()
            throws ResourceException

Description copied from interface: RemoveCallback

Notifies that the resource was removed. This function must not be called directly on the resource object. Only ResourceHome.remove() is allowed to call that method during the remove operation.

Specified by:

remove in interface RemoveCallback

See Also:

RemoveCallback

createNewResourceProperty

protected ResourceProperty createNewResourceProperty(QName rpQName,
                                                     Object resourceBean)
                                              throws Exception

Description copied from class: ReflectionResource

Override this callback method to specialize the implementation of the resource property value accessors on a per resource property basis. For instance, in the overriden version, do special processing if the QName of the property matches a special QName, or just call this base implementation otherwise.

The default behavior is to create a new ReflectionResourceProperty constructed with the QName of the resource property and the resource implementation Bean used to construct this ReflectionResource object.

This function handles a few special cases:

• If rpQName equals WSRFConstants.CURRENT_TIME, the resource property MUST use a dynamic implementation of getCurrentTime(), since time never stops changing. Therefore the resource bean callback used is not the initial resource Bean but the ReflectionResource object, which bears such an implementation of that function.
• If rpQName equals WSRFConstants.TERMINATION_TIME, the resource property created is set be nillable.

Overrides:

createNewResourceProperty in class ReflectionResource

Parameters:

rpQName - QName

resourceBean - Object

Returns:

ResourceProperty

Throws:

Exception -

setDirty

public void setDirty(boolean changed)

Sets the dirty flag on this persistent object. The resource will not be persisted unless it the firty flag is true.

Parameters:

changed - boolean To flag the resource as changed i.e. "dirty" and have it persisted by the next invocation of store

getDirty

public boolean getDirty()

getStoredResourceKeyValues

public List getStoredResourceKeyValues()
                                throws Exception

This function returns the keys of the resources that have been stored. This should be used by the home in order to recover state, by listing all the stored resource keys and adding them to the map of resources. The consumer code must test for null.

Returns:

List the list of key values