org.globus.wsrf.impl
Class PersistentReflectionResource

java.lang.Object
  org.globus.wsrf.impl.ReflectionResource
      org.globus.wsrf.impl.PersistentReflectionResource

All Implemented Interfaces:

DirtyFlagHolder, PersistenceCallback, RemoveCallback, Resource, ResourceIdentifier, ResourceLifetime, ResourceProperties

public abstract class PersistentReflectionResource

extends ReflectionResource

implements RemoveCallback, PersistenceCallback, DirtyFlagHolder

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 ResourceHomeImpl 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 ResourceHomeImpl), 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 ResourceHomeImpl. (note: maybe this is overkill and not necessary?)

See Also:

ReflectionResource, ResourceHomeImpl, PersistenceCallback, RemoveCallback

Field Summary

private boolean	dirty The dirty flag is set to true at instanciation time, so that the initial creator of the resource just needs to call store in order to actually persist the new resource for the first time.
private static org.globus.util.I18n	i18n
private static org.apache.commons.logging.Log	logger
private XmlPersistenceHelper	persistenceHelper

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

Constructor Summary

PersistentReflectionResource()

Method Summary

protected ResourceProperty	createNewResourceProperty(javax.xml.namespace.QName rpQName, java.lang.Object resourceBean) Warning: this is not a callback (but maybe it should be).
boolean	getDirty()
protected java.io.File	getKeyAsFile(java.lang.Object key) Create a file object based on the key supplied in parameter.
protected XmlPersistenceHelper	getPersistenceHelper()
protected abstract java.lang.Class	getResourceBeanClass()
protected java.io.File	getStorageDirectory()
java.util.List	getStoredResourceKeyValues() This function returns the keys of the resources that have been stored.
void	load(ResourceKey key) Called by ResourceHomeImpl 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

createNewResourceProperty, getCurrentTime, getID, getResourceBean, getResourcePropertySet, getTerminationTime, initialize, setTerminationTime

Methods inherited from class java.lang.Object

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

Field Detail

i18n

private static org.globus.util.I18n i18n

logger

private static org.apache.commons.logging.Log logger

dirty

private boolean dirty

The dirty flag is set to true at instanciation time, so that the initial creator of the resource just needs to call store in order to actually persist the new resource for the first time.

persistenceHelper

private XmlPersistenceHelper persistenceHelper

Constructor Detail

PersistentReflectionResource

public PersistentReflectionResource()

Method Detail

getPersistenceHelper

protected XmlPersistenceHelper getPersistenceHelper()

getResourceBeanClass

protected abstract java.lang.Class getResourceBeanClass()

Returns:

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

See Also:

ReflectionResource

load

public void load(ResourceKey key)
          throws ResourceException

Called by ResourceHomeImpl 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 PersistenceCallback

Throws:

ResourceException - if the load operation fails for any other reason.

See Also:

setDirty(), PersistenceCallback

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 PersistenceCallback

Throws:

ResourceException - if the resource could not be stored

See Also:

setDirty(), getKeyAsFile(), PersistenceCallback

getKeyAsFile

protected java.io.File getKeyAsFile(java.lang.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 java.io.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

Throws:

ResourceException - if the remove operation fails.

See Also:

RemoveCallback

createNewResourceProperty

protected ResourceProperty createNewResourceProperty(javax.xml.namespace.QName rpQName,
                                                     java.lang.Object resourceBean)
                                              throws java.lang.Exception

Description copied from class: ReflectionResource

Warning: this is not a callback (but maybe it should be).

Overrides:

createNewResourceProperty in class ReflectionResource

Parameters:

rpQName - QName

resourceBean - Object

Returns:

ResourceProperty

Throws:

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

Specified by:

setDirty in interface DirtyFlagHolder

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()

Specified by:

getDirty in interface DirtyFlagHolder

getStoredResourceKeyValues

public java.util.List getStoredResourceKeyValues()
                                          throws java.io.IOException

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

Throws:

java.io.IOException