org.gcube.common.core.state
Class GCUBEResourceHome<LEGACYID,RESOURCEID extends LEGACYID,RESOURCE extends GCUBEStatefulResource<RESOURCEID>>

java.lang.Object
  org.gcube.common.core.state.GCUBEResourceHome<LEGACYID,RESOURCEID,RESOURCE>

Type Parameters:

RESOURCE - the type of GCUBEStatefulResource.

RESOURCEID - the type of the GCUBEStatefulResource identifier.

LEGACYID - the legacy identifier type. Used to retrofit the design to Globus technology while insulating clients from it.

All Implemented Interfaces:

org.globus.wsrf.jndi.Initializable

Direct Known Subclasses:

GCUBELocalHome, GCUBEWSHome

public abstract class GCUBEResourceHome<LEGACYID,RESOURCEID extends LEGACYID,RESOURCE extends GCUBEStatefulResource<RESOURCEID>>
extends Object
implements org.globus.wsrf.jndi.Initializable

Partial implementation of managers of GCUBEStatefulResources.

It creates, retrieves, and removes resources parametrically with respect to their type. Resource management can occur in either one of four different modes:

TRANSIENT: resources are maintained exclusively in memory (default mode);
HARDPERSISTENT: resources can be serialised to storage by configuration of a GCUBEPersistenceDelegate. At the reboot of the container all resource serialisations are transparently restored to memory.
CACHEDPERSISTENT: resources can be serialised to storage by configuration of a GCUBEPersistenceDelegate and remain in memory for a time that is proportional to the frequency of usage and and the amount of available memory. Resources that are not found in memory but exist on storage are transparently restored to memory.
SOFTPERSISTENT: resources can be serialised to storage by configuration of a GCUBEPersistenceDelegate and remain in memory for a time that is proportional to the amount of available memory. Resources that are not found in memory but exist on storage are transparently restored to memory.

The four modes above reflect different trade-offs between the efficiency of resource access (which decreases from the first to the fourth) and the efficiency of in-memory storage (which increases from the first to the fourth). In all cases, the mode of operation is derived from configuration (cf. onInitialisation()).

Author:

Fabio Simeoni (University of Strathclyde), Manuele Simi (ISTI-CNR)

Nested Class Summary

protected static class

GCUBEResourceHome.Mode Enumerates management modes.

Field Summary

protected org.globus.wsrf.utils.cache.LRUCache	cache Memory cache for persistent resources.
protected org.gcube.common.core.state.GCUBEResourceHome.LockManager	lockManager A manager of locks on resources identifiers.
protected GCUBELog	logger Instance logger.
protected GCUBEResourceHome.Mode	mode The management mode.
protected GCUBEPersistenceDelegate<RESOURCEID,RESOURCE>	persistenceDelegate The class of the persistence delegate for the managed resources.
protected Class<RESOURCE>	resourceClass The class of the managed resources.
protected List<RESOURCEID>	resourceLog List of identifiers of resources created in the home's lifetime.

Constructor Summary

GCUBEResourceHome()

Method Summary

protected void	add(RESOURCE resource) Adds a resource to the home.
RESOURCE	create(Object... params) Creates a resource from a set of initialisation parameters.
RESOURCE	create(RESOURCEID id, Object... params) Returns a resource with a given identifier from a set of initialisation parameters, creating it if it does not exist.
protected RESOURCE	createInternal(RESOURCEID id, Object... params) Used internally to create a resource from an identifier and a set of initialisation parameters.
RESOURCE	find(LEGACYID id) Returns a resource from its identifier.
protected RESOURCE	get(LEGACYID id) Returns a resource from its identifier, deserialising it from storage if it is in a persistent state.
Collection<? extends RESOURCEID>	getIdentifiers() Returns the identifiers of all resources ever created by the home.
String	getResourceClass() Returns the class of the resources managed by the home.
protected Collection<? extends RESOURCE>	getResources() Returns the resources that are held in memory at the point of invocation.
abstract GCUBEServiceContext	getServiceContext() Returns the associated GCUBEServiceContext.
void	initialize() Invoked by the container at startup, it subscribes a GCUBEResourceHome.HomeConsumer to lifetime events of the Running Instance.
protected RESOURCE	newInstance() Used internally to obtain an uninitialised resource.
protected void	onFailure() Invoked when the Running Instance fails.
protected void	onInitialisation() Invoked during initialisation of the Running Instance to initialise the home.
protected void	onLoad(RESOURCE resource, boolean firstLoad) Invoked after successfully loading a resource from storage.
protected void	onReady() Invoked when the Running Instance is ready to operate.
protected boolean	onRemove(RESOURCE resource) Invoked as a precondition to the removal of a resource.
protected void	onReuse(RESOURCE resource) Invoked when a resource is reused across two or more calls to create(Object, Object...) .
protected void	onStateChange() Invoked upon a change to the RI's stateful resources, if any.
protected void	onUpdate() Invoked when the Runnning Instance is updated.
protected void	postInitialise(RESOURCE resource) Invoked during the creation of a resource and after its initialisation.
protected void	preInitialise(RESOURCE resource) Invoked during the creation of a resource and before its initialisation.
void	remove(LEGACYID id) Removes a resource with a given identifier.
protected void	remove(RESOURCE resource) Removes a resource from the home.
protected RESOURCE	reuse(RESOURCEID id, Object... params) Returns a resource with a given identifier.
void	setCacheTimeout(long timeout) Sets the timeout in milliseconds of the cache used by the home.
void	setPersistenceDelegateClass(String clazz) Sets the name of the class of the persistence delegate for the resources managed by the home.
void	setResourceClass(String clazz) Sets the name of the class of the resources managed by the home.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final GCUBELog logger

Instance logger.

resourceClass

protected volatile Class<RESOURCE extends GCUBEStatefulResource<RESOURCEID>> resourceClass

The class of the managed resources.

persistenceDelegate

protected volatile GCUBEPersistenceDelegate<RESOURCEID extends LEGACYID,RESOURCE extends GCUBEStatefulResource<RESOURCEID>> persistenceDelegate

The class of the persistence delegate for the managed resources.

mode

protected volatile GCUBEResourceHome.Mode mode

The management mode.

cache

protected volatile org.globus.wsrf.utils.cache.LRUCache cache

Memory cache for persistent resources.

lockManager

protected final org.gcube.common.core.state.GCUBEResourceHome.LockManager lockManager

A manager of locks on resources identifiers.

resourceLog

protected final List<RESOURCEID extends LEGACYID> resourceLog

List of identifiers of resources created in the home's lifetime.

Constructor Detail

GCUBEResourceHome

public GCUBEResourceHome()

Method Detail

initialize

public final void initialize()
                      throws Exception

Invoked by the container at startup, it subscribes a GCUBEResourceHome.HomeConsumer to lifetime events of the Running Instance.

Specified by:

initialize in interface org.globus.wsrf.jndi.Initializable

Throws:

Exception - if initialisation fails.

setResourceClass

public void setResourceClass(String clazz)
                      throws ClassNotFoundException

Sets the name of the class of the resources managed by the home.

Parameters:

clazz - the class name.

Throws:

ClassNotFoundException - if the class name could not be resolved.

getResourceClass

public String getResourceClass()

Returns the class of the resources managed by the home.

Returns:

the class.

setPersistenceDelegateClass

public void setPersistenceDelegateClass(String clazz)
                                 throws Exception

Sets the name of the class of the persistence delegate for the resources managed by the home.

Parameters:

clazz - the class name.

Throws:

ClassNotFoundException - if the class name could not be resolved.

Exception

setCacheTimeout

public void setCacheTimeout(long timeout)

Sets the timeout in milliseconds of the cache used by the home.

Parameters:

timeout - the timeout.

getServiceContext

public abstract GCUBEServiceContext getServiceContext()

Returns the associated GCUBEServiceContext.

Returns:

the service context.

onInitialisation

protected void onInitialisation()
                         throws Exception

Invoked during initialisation of the Running Instance to initialise the home. Most of the initialisation occurs from JNDI configuration. Subclasses must define a configuration template which extends the following (text in italics marks points of instantiations):

<resource name="[name]" type="[FQN of a subclass of GCUBEResourceHome]">
<resourceParams>
<parameter>
<name>factory</name>
<value>org.globus.wsrf.jndi.BeanFactory</value>
</parameter>
<parameter>
<name>resourceClass</name>
<value>[FQN of a concrete subclass of GCUBEStatefulResource]</value>
</parameter>
<parameter>
<name>persistenceDelegateClass</name>
<value>[FQN of a concrete subclass of GCUBEPersistenceDelegate]</value>
</parameter>
<parameter>
<name>cacheTimeout</name>
<value>[seconds]</value>
</parameter>
</resourceParams>
</resource>

where:

-) the name of the JNDI resource and its resourceClass parameter may be further constrained by subclasses.
-) persistenceDelegateClass and cacheTimeout are optional and related. If neither is present, the mode of operation is TRANSIENT. If the first is present but the second is absent, then the mode of operation is SOFTPERSISTENT. If both are present, then the mode of operation is HARDPERSISTENT if the second has a value of 0 and CACHEDPERSISTENT in all other cases. Finally, the second cannot occur without the first.

Throws:

Exception - if the callback did not complete successfully (causes service failure).

onReady

protected void onReady()
                throws Exception

Invoked when the Running Instance is ready to operate. If needed, override in accordance with service semantics.

Throws:

Exception - if the callback did not complete successfully and the service ought to fail as a result.

onUpdate

protected void onUpdate()
                 throws Exception

Invoked when the Runnning Instance is updated. If needed, override in accordance with service semantics.

Throws:

Exception - if the callback did not complete successfully and the service ought to fail as a result.

onStateChange

protected void onStateChange()
                      throws Exception

Invoked upon a change to the RI's stateful resources, if any. If needed, override in accordance with service semantics.

Throws:

Exception - if the callback did not complete successfully and the service ought to fail as a result.

onFailure

protected void onFailure()
                  throws Exception

Invoked when the Running Instance fails. If needed, override in accordance with service semantics.

Throws:

Exception - if the callback did not complete successfully and the service ought to fail as a result.

newInstance

protected RESOURCE newInstance()
                                                                  throws org.globus.wsrf.ResourceException

Used internally to obtain an uninitialised resource.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be created.

add

protected void add(RESOURCE resource)

Adds a resource to the home.

Parameters:

resource - the resource.

get

protected RESOURCE get(LEGACYID id)
                                                          throws org.globus.wsrf.ResourceException,
                                                                 org.globus.wsrf.NoSuchResourceException

Returns a resource from its identifier, deserialising it from storage if it is in a persistent state.

It is invoked by find(id) and remove(id) after they have acquired a reentrant lock on the resource identifier.

Parameters:

id - the identifier.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource cannot be found.

org.globus.wsrf.NoSuchResourceException

See Also:

find(Object), remove(Object)

remove

protected void remove(RESOURCE resource)
               throws org.globus.wsrf.ResourceException

Removes a resource from the home.

Parameters:

resource - the resource.

Throws:

org.globus.wsrf.ResourceException

getResources

protected Collection<? extends RESOURCE> getResources()

Returns the resources that are held in memory at the point of invocation.

Returns:

the resources.

getIdentifiers

public Collection<? extends RESOURCEID> getIdentifiers()

Returns the identifiers of all resources ever created by the home.

Returns:

the identifiers.

create

public RESOURCE create(Object... params)
                                                          throws org.globus.wsrf.ResourceException

Creates a resource from a set of initialisation parameters.

Parameters:

params - (optional) the initialisation parameters.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could neither be reused or created.

See Also:

create(Object, Object...)

create

public RESOURCE create(RESOURCEID id,
                       Object... params)
                                                          throws org.globus.wsrf.ResourceException

Returns a resource with a given identifier from a set of initialisation parameters, creating it if it does not exist.

Parameters:

id - the identifier, or null.

params - (optional) the initialisation parameters.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could neither be reused or created.

See Also:

onReuse(GCUBEStatefulResource), reuse(Object, Object...)

reuse

protected RESOURCE reuse(RESOURCEID id,
                         Object... params)
                                                            throws org.globus.wsrf.ResourceException

Returns a resource with a given identifier.

Parameters:

id - the identifier.

params - (optional) the initialisation parameters.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be reused.

createInternal

protected RESOURCE createInternal(RESOURCEID id,
                                  Object... params)
                                                                     throws org.globus.wsrf.ResourceException

Used internally to create a resource from an identifier and a set of initialisation parameters.

Parameters:

id - the identifier, or null.

params - (optional) the initialisation parameters.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be created.

find

public RESOURCE find(LEGACYID id)
                                                        throws org.globus.wsrf.ResourceException,
                                                               org.globus.wsrf.NoSuchResourceException

Returns a resource from its identifier.

Parameters:

id - the identifier.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if no resource with the given identifier can be found.

org.globus.wsrf.NoSuchResourceException

remove

public void remove(LEGACYID id)
            throws org.globus.wsrf.ResourceException

Removes a resource with a given identifier.

Parameters:

id - the identifier.

Throws:

org.globus.wsrf.NoSuchResourceException - if no resource exists with the given identifier.

org.globus.wsrf.InvalidResourceKeyException - if the identifier is invalid.

org.globus.wsrf.ResourceException - if the resource exists but could not be removed.

preInitialise

protected void preInitialise(RESOURCE resource)
                      throws org.globus.wsrf.ResourceException

Invoked during the creation of a resource and before its initialisation.

If overriding this method, please note that the resource may not have been assigned an identifier yet.

Parameters:

resource - the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be pre-initialised.

postInitialise

protected void postInitialise(RESOURCE resource)
                       throws org.globus.wsrf.ResourceException

Invoked during the creation of a resource and after its initialisation.

Parameters:

resource - the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be post-initialised.

onReuse

protected void onReuse(RESOURCE resource)
                throws org.globus.wsrf.ResourceException

Invoked when a resource is reused across two or more calls to create(Object, Object...) .

Parameters:

resource - the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be reused.

onLoad

protected void onLoad(RESOURCE resource,
                      boolean firstLoad)
               throws org.globus.wsrf.ResourceException

Invoked after successfully loading a resource from storage.

Parameters:

resource - the resource.

firstLoad - true if this is the first time the resource is loaded since the last container reboot.

Throws:

org.globus.wsrf.ResourceException - if the resource could not loaded.

onRemove

protected boolean onRemove(RESOURCE resource)
                    throws org.globus.wsrf.ResourceException

Invoked as a precondition to the removal of a resource.

Parameters:

resource - the resource.

Throws:

org.globus.wsrf.ResourceException - if the precondition could not be verified.