com.bigdata.service.jini.master
Class AbstractClientTask<S extends TaskMaster.JobState,U,V extends Serializable>

java.lang.Object
  com.bigdata.service.FederationCallable<T>
      com.bigdata.service.DataServiceCallable<U>
          com.bigdata.service.jini.master.AbstractClientTask<S,U,V>

Type Parameters:

S - The generic for the TaskMaster.JobState.

U - The generic for the Callable's return type.

V - The generic type of the client state (stored in zookeeper).

All Implemented Interfaces:

IDataServiceCallable, IFederationCallable, Serializable, Callable<U>

public abstract class AbstractClientTask<S extends TaskMaster.JobState,U,V extends Serializable>
extends DataServiceCallable<U>
implements Callable<U>

An abstract base class which may be used for client tasks run by the master on one or more data services. This class contends for a ZLock based on the assigned clientNum and then invoked #runWithZLock() if the ZLock if granted. If the lock is lost, it will continue to contend for the lock and then run until finished.

Note: This implementation presumes that #runWithZLock() has some means of understanding when it is done and can restart its work from where it left off. One way to handle that is to write the state of the client into the client's znode and to update that from time to time as the client makes progress on its task. You can invoke setupClientState() to do that.

Note: This class DOES NOT have to be submitted to an IDataService for execution. Most client tasks will in fact run on IClientServices rather than IDataServices. This class extends DataServiceCallable for the convienence of subclasses which MAY introduce a requirement to execute on an IDataService.

Version:

$Id$

Author:

Bryan Thompson

See Also:

Serialized Form

Field Summary

protected int	clientNum
protected S	jobState
protected static org.apache.log4j.Logger	log
protected ZLockImpl	zlock The zpath for the ZLock node.

Constructor Summary

protected

AbstractClientTask(S jobState, int clientNum)

Method Summary

U	call() Runs the generator.
int	getClientNum() Return the index assigned to the client.
JiniFederation	getFederation() Return the IBigdataFederation reference.
S	getJobState() Return the jobstate.
protected abstract V	newClientState() Return a new instance of the client's state.
protected abstract U	runWithZLock(V clientState) Do work while holding the ZLock.
void	setFederation(IBigdataFederation fed) Invoked before the task is executed to provide a reference to the IBigdataFederation for the service on which the task is executing.
protected V	setupClientState() The method invoked newClientState() and attempts to create the client's znode with the serialized state as its data and that state will be returned to the caller.
String	toString()
protected void	writeClientState(V clientState) Method updates the client state in zookeeper.

Methods inherited from class com.bigdata.service.DataServiceCallable

getDataService, isDataService, setDataService

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final org.apache.log4j.Logger log

jobState

protected final S extends TaskMaster.JobState jobState

clientNum

protected final int clientNum

zlock

protected transient ZLockImpl zlock

The zpath for the ZLock node. Only the instance of this task holding the ZLock is allowed to run. This makes it safe to run multiple instances of this task for the same clientNum. If one instance dies, the instance that gains the ZLock will read the client's state from zookeeper and continue processing.

This is null until call().

Constructor Detail

AbstractClientTask

protected AbstractClientTask(S jobState,
                             int clientNum)

Method Detail

getJobState

public S getJobState()

Return the jobstate.

getClientNum

public int getClientNum()

Return the index assigned to the client.

Returns:

The client index.

setFederation

public void setFederation(IBigdataFederation fed)

Description copied from interface: IFederationCallable

Invoked before the task is executed to provide a reference to the IBigdataFederation for the service on which the task is executing.

Specified by:

setFederation in interface IFederationCallable

Overrides:

setFederation in class FederationCallable<U>

Parameters:

fed - The federation.

getFederation

public JiniFederation getFederation()

Description copied from interface: IFederationCallable

Return the IBigdataFederation reference.

Specified by:

getFederation in interface IFederationCallable

Overrides:

getFederation in class FederationCallable<U>

Returns:

The federation and never null.

toString

public String toString()

Overrides:

toString in class Object

call

public U call()
       throws Exception

Runs the generator.

Specified by:

call in interface Callable<U>

Throws:

Exception

runWithZLock

protected abstract U runWithZLock(V clientState)
                           throws Exception,
                                  org.apache.zookeeper.KeeperException,
                                  InterruptedException

Do work while holding the ZLock. The implementation SHOULD verify from time to time that it in fact holds the ZLock using ZLock.isLockHeld().

Returns:

The result.

Throws:

Exception

org.apache.zookeeper.KeeperException

InterruptedException

setupClientState

protected V setupClientState()
                                           throws InterruptedException,
                                                  org.apache.zookeeper.KeeperException

The method invoked newClientState() and attempts to create the client's znode with the serialized state as its data and that state will be returned to the caller. If there is an existing znode for the client, then the data of the znode is de-serialized and returned by this method.

This method is invoked automatically from within call() before the client attempts to obtain the ZLock (the zlock is a child of the client's znode).

You can update the client's state from time to time using writeClientState(Serializable). If the client looses the ZLock, it can read the client state from zookeeper using this method and pick up processing more or less where it left off (depending on when you last updated the client state in zookeeper).

Returns:

The client's state.

Throws:

InterruptedException

org.apache.zookeeper.KeeperException

See Also:

TaskMaster.JobState.getClientZPath(JiniFederation, int)

writeClientState

protected void writeClientState(V clientState)
                         throws org.apache.zookeeper.KeeperException,
                                InterruptedException

Method updates the client state in zookeeper. The caller MUST be holding the ZLock (this is verified).

Parameters:

clientState - The state to be written into the znode identified by clientZPath.

Throws:

InterruptedException

org.apache.zookeeper.KeeperException

newClientState

protected abstract V newClientState()

Return a new instance of the client's state.