org.almendra.commons.threads
Class Future

java.lang.Object
  extended by org.almendra.commons.threads.Future
All Implemented Interfaces:
IHistorizable, INamedObject, ISignalable
Direct Known Subclasses:
Acknowledge, CountDown, FutureResult

public abstract class Future
extends java.lang.Object
implements INamedObject, ISignalable, IHistorizable

Author:
Oliver

Field Summary
protected  java.lang.Exception exception
          Stores exception that may occur waiting for result.
(package private)  java.util.List historyItems
           
protected  boolean holds
          Indicates whether the Future is waiting or not.
protected  EDU.oswego.cs.dl.util.concurrent.Latch latch
          Used to block the calling thread if it requests the result that has not been produced so far.
protected  java.lang.Object lock
          Used to synchronize access to the signaled and holds state variable.
protected  java.lang.String name
          User-defined name of the future.
protected  boolean signaled
          Variable set to true when the latch has been released.
protected  boolean timeoutOccurred
          Answers whether a timeout occurred waiting for the result.
protected  boolean verbose
          Flag that indicates whether trace information should be written to the console when the future is waiting for the result.
 
Constructor Summary
Future()
          Creates a new Future object.
Future(java.lang.String name)
          Creates a new Future object.
 
Method Summary
 void acquire()
          Make the calling thread wait till the result has arrived.
 void acquire(long timeoutInMillisOrZero)
          Make the calling thread wait till the result has arrived.
 void addHistoryItems(java.util.List items)
           
 void createHistorySummary(IHistorySummary historySummary)
           
 java.lang.Exception getException()
           
 java.util.List getHistoryItems()
          Returns null if called before acquire() has resumed.
 java.lang.String getName()
          All objects that have a user-defined name must implement this method.
 boolean hasException()
          Anser whether an exception has occurred waiting for the result.
 boolean holds()
           
 boolean isTimeout()
           
 boolean isVerbose()
           
protected  void primAcquire(long milliseconds)
          Utility method to block the calling thread until the result has arrived or the timeout period expired.
 void setException(java.lang.Exception exception)
           
 void setVerbose(boolean verbose)
           
 void signal()
          Unblock the calling thread in case the result has arrived or some event has occurred.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

historyItems

java.util.List historyItems

name

protected java.lang.String name
User-defined name of the future. Can be used to write trace information to the console to determine which future is waiting for a result.


latch

protected EDU.oswego.cs.dl.util.concurrent.Latch latch
Used to block the calling thread if it requests the result that has not been produced so far. A latch is a condition that is acquirable forever more after the first release. See http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html


timeoutOccurred

protected boolean timeoutOccurred
Answers whether a timeout occurred waiting for the result.


signaled

protected boolean signaled
Variable set to true when the latch has been released. Used to determine whether latch has been released explicitly after result has arrived or whether a timeout has occurred.


lock

protected java.lang.Object lock
Used to synchronize access to the signaled and holds state variable.


exception

protected java.lang.Exception exception
Stores exception that may occur waiting for result.


holds

protected boolean holds
Indicates whether the Future is waiting or not.


verbose

protected boolean verbose
Flag that indicates whether trace information should be written to the console when the future is waiting for the result.

Constructor Detail

Future

public Future()
Creates a new Future object.


Future

public Future(java.lang.String name)
Creates a new Future object.

Method Detail

getName

public java.lang.String getName()
Description copied from interface: INamedObject
All objects that have a user-defined name must implement this method.

Specified by:
getName in interface INamedObject
Returns:
name

isTimeout

public boolean isTimeout()
Returns:
Returns the timeout.

setVerbose

public void setVerbose(boolean verbose)
Parameters:
verbose - The verbose to set.

isVerbose

public boolean isVerbose()
Returns:
Returns the verbose.

getException

public java.lang.Exception getException()
Returns:
Returns the exception.

setException

public void setException(java.lang.Exception exception)
Parameters:
exception - The exception to set.

acquire

public void acquire()
Make the calling thread wait till the result has arrived. Can be called explicitly without calling getResult(...) when the calling thread only has to be blocked till some event has occurred and there is no interest in some result.


acquire

public void acquire(long timeoutInMillisOrZero)
             throws java.lang.IllegalArgumentException,
                    TimeoutException
Make the calling thread wait till the result has arrived. Can be called explicitly without calling getResult(...) when the calling thread only has to be blocked till some event has occurred and there is no interest in some result.

Parameters:
timeoutInMillisOrZero - timeout period in milliseconds after which the calling thread is released
Throws:
java.lang.IllegalArgumentException - thrown if timeoutInMillisOrZero smaller than zero
TimeoutException

primAcquire

protected void primAcquire(long milliseconds)
                    throws TimeoutException
Utility method to block the calling thread until the result has arrived or the timeout period expired.

Parameters:
milliseconds - the timeout period in milliseconds
Throws:
TimeoutException - thrown when timeout period expired waiting for the result

hasException

public boolean hasException()
Anser whether an exception has occurred waiting for the result.

Returns:

signal

public void signal()
Unblock the calling thread in case the result has arrived or some event has occurred.

Specified by:
signal in interface ISignalable

holds

public boolean holds()
Specified by:
holds in interface ISignalable

getHistoryItems

public java.util.List getHistoryItems()
Returns null if called before acquire() has resumed.

Specified by:
getHistoryItems in interface IHistorizable

createHistorySummary

public void createHistorySummary(IHistorySummary historySummary)
Specified by:
createHistorySummary in interface IHistorizable

addHistoryItems

public void addHistoryItems(java.util.List items)
Specified by:
addHistoryItems in interface IHistorizable