org.ow2.clif.util

Class Future

java.lang.Object

java.lang.Thread

org.ow2.clif.util.Future

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

BladeDeploy

public abstract class Future
extends java.lang.Thread

Abstract class for running asynchronous tasks. Usage:

1. derive this class and define the futureExecution() method
3. create an instance of the derived class
4. call start() to run the task implemented by the futureExecution() method
5. then:
   • poll with isComplete() method to know if the task is complete
   • directly get the task result or exception with method futureGet(), waiting for its completion when not completed yet
   • synchronize with the task completion through the optional lock object, to be notified on task completion

Author:

Bruno Dillenseger

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
Future(java.lang.String threadName, java.lang.Object lock) Creates an asynchronous task, but does not run it.

Method Summary

Modifier and Type	Method and Description
protected abstract java.lang.Object	futureExecution() Define this method to implement the task.
java.lang.Object	futureGet() Blocks caller until the task is completed, and get its result or exception.
boolean	isComplete() Checks if the task is complete.
void	run() Calls abstract method futureExecution() which is supposed to implement (through inheritance) the task, and manages synchronization: on return from futureExecution(): all calls blocked on method futureGet() are resumed method isComplete() definitely returns true instead of false when a lock is provided, all threads waiting on this lock are notified

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Constructor Detail

Future

public Future(java.lang.String threadName,
              java.lang.Object lock)

Creates an asynchronous task, but does not run it. Method start() must be called then, to actually run the task.

Parameters:

threadName - an arbitrary convenient name to identify this thread (for debugging purpose)

lock - an optional lock object to wait on for synchronization with this task completion. When null, just

See Also:

Thread.start()

Method Detail

run

public final void run()

Calls abstract method futureExecution() which is supposed to implement (through inheritance) the task, and manages synchronization: on return from futureExecution():

• all calls blocked on method futureGet() are resumed
• method isComplete() definitely returns true instead of false
• when a lock is provided, all threads waiting on this lock are notified

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

futureGet

public final java.lang.Object futureGet()
                                 throws java.lang.Exception

Blocks caller until the task is completed, and get its result or exception. A recommended usage is to define an extra method which calls this method and casts the result to the specific result type of the task.

Returns:

the task result, i.e. the object returned by method futureExecution()

Throws:

java.lang.Exception - if the task defined by method futureExecution() threw an exception

isComplete

public final boolean isComplete()

Checks if the task is complete.

Returns:

true if the task is complete, whatever it is successful or not (i.e. result available or exception thrown), false otherwise.

futureExecution

protected abstract java.lang.Object futureExecution()
                                             throws java.lang.Exception

Define this method to implement the task.

Returns:

the task result, of arbitrary type.

Throws:

java.lang.Exception - the task could not complete.