org.gcube.common.core.state
Class GCUBEWSHome

java.lang.Object
  org.gcube.common.core.state.GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>
      org.gcube.common.core.state.GCUBEWSHome

All Implemented Interfaces:

org.globus.wsrf.jndi.Initializable, org.globus.wsrf.ResourceHome

public abstract class GCUBEWSHome
extends GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>
implements org.globus.wsrf.ResourceHome

An abstract specialisation of GCUBEResourceHome to GCUBEWSResources.

It enforces scoping rules for resources and it manages their lifetime and publication in accordance with configuration (cf. onInitialisation()). In particular:

-) resources creation must be scoped and the scope must be compatible with (that of) the Running Instance. As a result, the resource acquires the scope and is published therein.
-) resources removal must be scoped and the scope must be compatible with (that of) the resource. As a result, the resource loses the scope and is unpublished from it. If the resource is left unscoped, it is physically removed (including its persistent serialisation, if any).
-) resource retrieval can be unscoped for legacy reasons. if scoped, however, the scope must be compatible with (that of) the resource.
-) the removal of the Running Instance from a scope propagates to all the resources created in that scope.
-) persistent resources are republished in all their scopes at container startup.
-) resources lifetime is checked periodically for resources that are in memory, and at the point of usage for those that exist only in storage. if found expired, the resource is removed from all its scopes and thus physically removed (including its persistent serialisation, if any).

Author:

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

Nested Class Summary

Nested classes/interfaces inherited from class org.gcube.common.core.state.GCUBEResourceHome

GCUBEResourceHome.Mode

Field Summary

protected QName	keyTypeName The qualified name of the resource key.
protected org.gcube.common.core.state.GCUBEWSHome.SweeperScheduler	sweeperScheduler The handler that controls the lifetime of WS-Resources.

Fields inherited from class org.gcube.common.core.state.GCUBEResourceHome

cache, lockManager, logger, mode, persistenceDelegate, resourceClass, resourceLog

Constructor Summary

GCUBEWSHome()

Method Summary

GCUBEWSResource	create(GCUBEWSResourceKey id, Object... params) Returns a resource with a given identifier from a set of initialisation parameters, creating it if it does not exist.
GCUBEWSResource	create(Object... params) Creates a resource from a set of initialisation parameters.
GCUBEWSResource	find() Returns the resource bound to the current call.
GCUBEWSResource	find(org.globus.wsrf.ResourceKey id) Returns a resource from its identifier.
protected GCUBEWSResource	get(org.globus.wsrf.ResourceKey id) Returns a resource from its identifier, deserialising it from storage if it is in a persistent state.
Class<String>	getKeyTypeClass() Satisfies the ResourceHome interface by returning the Class of the value wrapped by the resource identifier.
QName	getKeyTypeName() Returns the qualified name of the key of the WS-Resources managed by the home.
abstract GCUBEStatefulPortTypeContext	getPortTypeContext() Returns the associated GCUBEStatefulPortTypeContext.
GCUBEServiceContext	getServiceContext() Returns the associated GCUBEServiceContext.
long	getSweeperDelay() Returns the time between activations of the sweeper.
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(GCUBEWSResource 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(GCUBEWSResource resource) Invoked as a precondition to the removal of a resource.
protected void	onReuse(GCUBEWSResource resource) Invoked when a resource is reused across two or more calls to GCUBEResourceHome.create(Object, Object...) .
protected void	postInitialise(GCUBEWSResource resource) Invoked during the creation of a resource and after its initialisation.
protected void	preInitialise(GCUBEWSResource resource) Invoked during the creation of a resource and before its initialisation.
void	remove(org.globus.wsrf.ResourceKey id) Removes a resource with a given identifier.
protected GCUBEWSResource	reuse(GCUBEWSResourceKey id, Object... params) Returns a resource with a given identifier.
void	setKeyName(String keyName) Sets the qualified name of the key of the WS-Resource managed by the home.
void	setSweeperDelay(long delay) Sets the time between activations of the sweeper.

Methods inherited from class org.gcube.common.core.state.GCUBEResourceHome

add, createInternal, getIdentifiers, getResourceClass, getResources, initialize, newInstance, onStateChange, onUpdate, remove, setCacheTimeout, setPersistenceDelegateClass, setResourceClass

Methods inherited from class java.lang.Object

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

Field Detail

keyTypeName

protected QName keyTypeName

The qualified name of the resource key.

sweeperScheduler

protected org.gcube.common.core.state.GCUBEWSHome.SweeperScheduler sweeperScheduler

The handler that controls the lifetime of WS-Resources.

Constructor Detail

GCUBEWSHome

public GCUBEWSHome()

Method Detail

setKeyName

public void setKeyName(String keyName)

Sets the qualified name of the key of the WS-Resource managed by the home.

Parameters:

keyName - the name.

getKeyTypeName

public QName getKeyTypeName()

Returns the qualified name of the key of the WS-Resources managed by the home.

Specified by:

getKeyTypeName in interface org.globus.wsrf.ResourceHome

Returns:

the name ({[port-type namespaces<]/em>}ResourceKey by default).

getKeyTypeClass

public final Class<String> getKeyTypeClass()

Satisfies the ResourceHome interface by returning the Class of the value wrapped by the resource identifier.

Specified by:

getKeyTypeClass in interface org.globus.wsrf.ResourceHome

Returns:

the class.

setSweeperDelay

public void setSweeperDelay(long delay)

Sets the time between activations of the sweeper.

Parameters:

delay - the time, in seconds.

getSweeperDelay

public long getSweeperDelay()

Returns the time between activations of the sweeper.

Returns:

the time, in seconds.

getPortTypeContext

public abstract GCUBEStatefulPortTypeContext getPortTypeContext()

Returns the associated GCUBEStatefulPortTypeContext.

Returns:

the port-type context.

getServiceContext

public GCUBEServiceContext getServiceContext()

Returns the associated GCUBEServiceContext.

Specified by:

getServiceContext in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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, which must adhere to the following template (text in italics marks points of instantiations):

<resource name="[name]" type="[ the FQN of a subclass of GCUBEWSHome]">
<resourceParams>
<parameter>
<name>factory</name>
<value>org.globus.wsrf.jndi.BeanFactory</value>
</parameter>
<parameter>
<name>resourceClass</name>
<value>[FQN of a GCUBEWSResource extension]</value>
</parameter>
<parameter>
<name>persistenceDelegateClass</name>
<value>[FQN of a concrete subclass of GCUBEPersistenceDelegate]</value>
</parameter>
<parameter>
<name>keyName</name>
<value>[the serialisation of a QName]</value>
</parameter>
<parameter>
<name>sweeperDelay</name>
<value>[milliseconds]</value>
</parameter>
<parameter>
<name>cacheTimeout</name>
<value>[milliseconds, e.g. 120000]</value>
</parameter>
</resourceParams>
</resource>

where keyName, sweeperDelay and cacheTimeout are optional, and the name of the JNDI resource and its context of occurrence are to be constrained by clients.

Overrides:

onInitialisation in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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.

Overrides:

onReady in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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.

Overrides:

onFailure in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Throws:

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

get

protected GCUBEWSResource get(org.globus.wsrf.ResourceKey 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.

Overrides:

get in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Parameters:

id - the identifier.

Returns:

the resource.

Throws:

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

org.globus.wsrf.NoSuchResourceException

See Also:

GCUBEResourceHome.find(Object), GCUBEResourceHome.remove(Object)

create

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

Creates a resource from a set of initialisation parameters.

Overrides:

create in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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:

GCUBEResourceHome.create(Object, Object...)

create

public GCUBEWSResource create(GCUBEWSResourceKey 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.

Overrides:

create in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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:

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

reuse

protected GCUBEWSResource reuse(GCUBEWSResourceKey id,
                                Object... params)
                         throws org.globus.wsrf.ResourceException

Returns a resource with a given identifier.

Overrides:

reuse in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Parameters:

id - the identifier.

params - (optional) the initialisation parameters.

Returns:

the resource.

Throws:

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

find

public GCUBEWSResource find()
                     throws org.globus.wsrf.ResourceException

Returns the resource bound to the current call.

Returns:

the resource.

Throws:

org.globus.wsrf.ResourceException - if the resource could not be identified or returned.

find

public GCUBEWSResource find(org.globus.wsrf.ResourceKey id)
                     throws org.globus.wsrf.ResourceException,
                            org.globus.wsrf.NoSuchResourceException

Returns a resource from its identifier.

Specified by:

find in interface org.globus.wsrf.ResourceHome

Overrides:

find in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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(org.globus.wsrf.ResourceKey id)
            throws org.globus.wsrf.ResourceException

Removes a resource with a given identifier.

Specified by:

remove in interface org.globus.wsrf.ResourceHome

Overrides:

remove in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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(GCUBEWSResource 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.

Overrides:

preInitialise in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Parameters:

resource - the resource.

Throws:

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

postInitialise

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

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

Overrides:

postInitialise in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Parameters:

resource - the resource.

Throws:

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

onReuse

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

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

Overrides:

onReuse in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Parameters:

resource - the resource.

Throws:

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

onLoad

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

Invoked after successfully loading a resource from storage.

Overrides:

onLoad in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

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(GCUBEWSResource resource)
                    throws org.globus.wsrf.ResourceException

Invoked as a precondition to the removal of a resource.

Overrides:

onRemove in class GCUBEResourceHome<org.globus.wsrf.ResourceKey,GCUBEWSResourceKey,GCUBEWSResource>

Parameters:

resource - the resource.

Throws:

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