org.gcube.common.core.utils.handlers
Class GCUBEServiceHandler<CLIENT extends GCUBEServiceClient>

java.lang.Object
  org.gcube.common.core.utils.handlers.GCUBEHandler<CLIENT>
      org.gcube.common.core.utils.handlers.GCUBEServiceHandler<CLIENT>

Type Parameters:

CLIENT - the type of the handled object. It must implement the GCUBEServiceClient interface.

All Implemented Interfaces:

GCUBEIHandler<CLIENT>, Lifetime<CLIENT>

Direct Known Subclasses:

GCUBEStatefulServiceHandler, RICall.RICallHandler

public abstract class GCUBEServiceHandler<CLIENT extends GCUBEServiceClient>
extends GCUBEHandler<CLIENT>
implements Lifetime<CLIENT>

Abstract extension of GCUBEHandler which implements a best-attempt strategy to interact with an instance of a port-type of a gCube service (the target port-type) on behalf of the handled object (the client). The strategy involves:

(1) Interacting with an instance of the target port-type, if its endpoint reference was previously cached within the client;
(2) Discovering suitable instances of the target port-type, if the cached instance fails or no such cache exists yet;
(3) Interacting with each instance of the target port-type, until the interaction is successful;
(4) Caching the endpoint reference of the instance of the target port-type with which interaction is successful;

To completely define strategy,concrete subclasses must implement the following abstract methods in accordance with the specific semantics of the interaction:

(a) findInstances() to discover suitable instances of the target port-type;
(b) interact(EndpointReferenceType) to interact with an instance of the target port-type;

They may and normally will also wish to implement the following method:

(c) getTargetPortTypeName() to return the name of the target port-type for customised logging and to grant EPR reuse across all the handler types that target the same port-type and operate on behalf of the same client. If the client is scope-sensitive (i.e. returns a non-null scope), then sharing is further scope-qualified.

Within the client, the cache of endpoint references of the target port-type is indexed by name of the port-type, so that the they can be shared by all GCUBEServiceHandlers which - in different ways and for different purposes - interact with the same port-type on behalf of the same client. The cache is entirely managed by the GCUBEServiceHandler, but the client must implement the GCUBEServiceClient interface (or else extend its base implementation GCUBEServiceClientImpl).

Before being cached, finally, endpoint references are also stored in the state of the GCUBEServiceHandler with the name targetEPR, so as to be shared asynchronously with other GCUBEHandlers in the context of a GCUBESequentialHandler.

Author:

Fabio Simeoni (University of Strathclyde)

Nested Class Summary

static class

GCUBEServiceHandler.NoQueryResultException Characterises empty query results.

Field Summary

Fields inherited from class org.gcube.common.core.utils.handlers.GCUBEHandler

handled, logger, producer

Constructor Summary

GCUBEServiceHandler()
Creates an instance.

GCUBEServiceHandler(CLIENT client)
Creates an instance to act on or on behalf of a service client.

Method Summary

protected void	_interact(org.apache.axis.message.addressing.EndpointReferenceType epr) Used internally to wrap interact(EndpointReferenceType) and handle its successes and failures.
protected void	cacheEPR(org.apache.axis.message.addressing.EndpointReferenceType epr) Caches the EPR of an instance of the target port-type.
protected void	clearCachedEPR() Clears the EPR of the instance of the target port-type which was last cached.
protected abstract List<org.apache.axis.message.addressing.EndpointReferenceType>	findInstances() Discovers EPRs to suitable instances of the target port-type.
int	getAttempts() Returns the number of times the handler tries to interact with instances of the target port-type which prove busy.
protected org.apache.axis.message.addressing.EndpointReferenceType	getCachedEPR() Returns the EPR of the instance of the target port-type which was last cached.
protected String	getCacheKey() Returns a key to store 'successful' endpoints of the target port-type in the cache provided by the service client.
protected List<org.apache.axis.message.addressing.EndpointReferenceType>	getInstances() Returns a non-empty list of EPRs to suitable instances of the target port-type.
protected String	getTargetPortTypeName() Returns the local name of the target port-type as the basis for a key to store 'successful' EPRs of the port-type in the cache provided by the service client (cf.
protected abstract void	interact(org.apache.axis.message.addressing.EndpointReferenceType epr) Interacts with an instance of the target port-type.
void	run() Executes the task implemented by the handler.
void	setAttempts(int attempts) Sets how many times the handler should try to interact with instances of the target port-type which prove busy.
protected org.apache.axis.message.addressing.EndpointReferenceType	tryInstances(List<org.apache.axis.message.addressing.EndpointReferenceType> eprs) Interacts with a list of instances of the target port-type, until one is successful.

Methods inherited from class org.gcube.common.core.utils.handlers.GCUBEHandler

clearBlackboard, getBlackboard, getHandled, getId, getLogger, getName, getScopeManager, getSecurityManager, getState, notify, setBlackboard, setHandled, setLogger, setName, setScopeManager, setSecurityManager, setState, subscribe, undo, unsubscribe

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.gcube.common.core.utils.handlers.lifetime.Lifetime

getState

Methods inherited from interface org.gcube.common.core.utils.handlers.GCUBEIHandler

clearBlackboard, getBlackboard, getHandled, getId, getLogger, getName, getScopeManager, getSecurityManager, setBlackboard, setHandled, setLogger, setName, setScopeManager, setSecurityManager, subscribe, undo, unsubscribe

Constructor Detail

GCUBEServiceHandler

public GCUBEServiceHandler()

Creates an instance.

GCUBEServiceHandler

public GCUBEServiceHandler(CLIENT client)

Creates an instance to act on or on behalf of a service client.

Parameters:

client - the client.

Method Detail

run

public void run()
         throws Exception

Executes the task implemented by the handler.

Specified by:

run in interface GCUBEIHandler<CLIENT extends GCUBEServiceClient>

Specified by:

run in class GCUBEHandler<CLIENT extends GCUBEServiceClient>

Throws:

Exception - if the execution of the task does not complete normally.

getInstances

protected List<org.apache.axis.message.addressing.EndpointReferenceType> getInstances()
                                                                               throws GCUBEServiceHandler.NoQueryResultException,
                                                                                      Exception

Returns a non-empty list of EPRs to suitable instances of the target port-type.

Returns:

the EPRs.

Throws:

GCUBEServiceHandler.NoQueryResultException - if the EPRs cannot be returned.

GCUBEServiceHandler.NoQueryResultException - if suitable instances cannot be found.

Exception

_interact

protected void _interact(org.apache.axis.message.addressing.EndpointReferenceType epr)
                  throws Exception

Used internally to wrap interact(EndpointReferenceType) and handle its successes and failures.
If interact(EndpointReferenceType) succeeds, it store the input EPR in the handler's state. If interact(EndpointReferenceType) fails with a GCUBEFault, it propagates the GCUBEException which models it most specifically.

Parameters:

epr - the EPR of an instance of the target port-type.

Throws:

GCUBEServiceHandler.NoQueryResultException - if the interaction fails to complete successfully.

Exception

See Also:

interact(EndpointReferenceType).

tryInstances

protected org.apache.axis.message.addressing.EndpointReferenceType tryInstances(List<org.apache.axis.message.addressing.EndpointReferenceType> eprs)
                                                                         throws Exception

Interacts with a list of instances of the target port-type, until one is successful.

Parameters:

eprs - the instance EPRs.

Returns:

the EPR of the successful instance.

Throws:

GCUBEServiceHandler.NoQueryResultException - if no interactions completes successfully.

Exception

getAttempts

public int getAttempts()

Returns the number of times the handler tries to interact with instances of the target port-type which prove busy.

Returns:

the number of attempts.

setAttempts

public void setAttempts(int attempts)

Sets how many times the handler should try to interact with instances of the target port-type which prove busy.

Parameters:

attempts - the number of attempts.

clearCachedEPR

protected void clearCachedEPR()

Clears the EPR of the instance of the target port-type which was last cached.

cacheEPR

protected void cacheEPR(org.apache.axis.message.addressing.EndpointReferenceType epr)

Caches the EPR of an instance of the target port-type.

Parameters:

epr - the EPR.

getCachedEPR

protected org.apache.axis.message.addressing.EndpointReferenceType getCachedEPR()

Returns the EPR of the instance of the target port-type which was last cached.

Returns:

the EPR.

getCacheKey

protected String getCacheKey()

Returns a key to store 'successful' endpoints of the target port-type in the cache provided by the service client.

By default, the key is derived from the name of the port-type (cf. getTargetPortTypeName() so as to reuse across endpoints across all handler types that target the same port-type and share the same client. If the client is scope-sensitive, however, the key is further scope-qualified.

Returns:

the key.

See Also:

getTargetPortTypeName()

getTargetPortTypeName

protected String getTargetPortTypeName()

Returns the local name of the target port-type as the basis for a key to store 'successful' EPRs of the port-type in the cache provided by the service client (cf. getCacheKey()).

By default, it returns the name of handler (cf. GCUBEHandler.getName()), which will not grant EPR reuse across any other handler type that may target the same port-type. Override and return a specific port-type name to grant EPR reuse across all handler types that target the same port-type and share the same client.

Returns:

the name.

See Also:

#getName()}, #getCacheKey()}.

findInstances

protected abstract List<org.apache.axis.message.addressing.EndpointReferenceType> findInstances()
                                                                                         throws Exception

Discovers EPRs to suitable instances of the target port-type.

Returns:

the EPRs.

Throws:

GCUBEServiceHandler.NoQueryResultException - if suitable instances cannot be found.

Exception

interact

protected abstract void interact(org.apache.axis.message.addressing.EndpointReferenceType epr)
                          throws Exception

Interacts with an instance of the target port-type.

Parameters:

epr - the EPR of the instance.

Throws:

GCUBEServiceHandler.NoQueryResultException - if the interaction does not complete successfully.

Exception