cz.cuni.amis.utils.future
Class FutureWithListeners<RESULT>

java.lang.Object
  cz.cuni.amis.utils.future.FutureWithListeners<RESULT>

Type Parameters:

RESULT -

All Implemented Interfaces:

java.util.concurrent.Future<RESULT>

Direct Known Subclasses:

ComponentFuture

public abstract class FutureWithListeners<RESULT>
extends java.lang.Object
implements java.util.concurrent.Future<RESULT>

Abstract class that represents future result of some computation that allows you to hook listeners on the status of the future computation (see addFutureListener(IFutureListener)). Whenever the computation is completed (or cancelled / exception has happened / etc.) the listeners are informed.

Field Summary

protected java.util.concurrent.CountDownLatch	latch Latch where threads are waiting when using get() or get(long, TimeUnit).
protected Listeners<IFutureListener<RESULT>>	listeners Future listeners, here we store listeners registred in addFutureListener(IFutureListener).
protected java.lang.Object	mutex Mutex synchronizing access to internal data structures of the future.

Constructor Summary

FutureWithListeners()

Method Summary

void	addFutureListener(IFutureListener<RESULT> listener) Adds a listener on a future status (using strong reference).
boolean	cancel(boolean mayInterruptIfRunning)
protected boolean	cancelComputation(boolean mayInterruptIfRunning) This should cancel the computation of the future.
void	computationException(java.lang.Exception e) Informs the future that it can't be computed due to the exception.
protected java.util.concurrent.CountDownLatch	createLatch() Factory method that should return CountDownLatch or its descendant initialized to 1.
RESULT	get()
RESULT	get(long timeout, java.util.concurrent.TimeUnit unit) Returns a result or waits for the computation till timeout.
java.lang.Exception	getException() Contains an exception that has happened during the computation in the case of (getStatus() == EXCEPTION).
FutureStatus	getStatus() Current status of the future computation.
boolean	isCancelled()
boolean	isDone()
boolean	isListening(IFutureListener<RESULT> listener) Whether some listener is listening on the future.
void	removeFutureListener(IFutureListener<RESULT> listener) Removes a listener from the future.
void	setResult(RESULT result) Sets the result of the future computation.
protected void	switchStatus(FutureStatus newStatus) Changes the status of the future (if it is different than current one) and notifies the listeners about this change.

Methods inherited from class java.lang.Object

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

Field Detail

mutex

protected java.lang.Object mutex

Mutex synchronizing access to internal data structures of the future.

listeners

protected Listeners<IFutureListener<RESULT>> listeners

Future listeners, here we store listeners registred in addFutureListener(IFutureListener).

latch

protected java.util.concurrent.CountDownLatch latch

Latch where threads are waiting when using get() or get(long, TimeUnit). This latch is instantiated whenever needed via method createLatch().

Constructor Detail

FutureWithListeners

public FutureWithListeners()

Method Detail

getStatus

public FutureStatus getStatus()

Current status of the future computation.

Returns:

addFutureListener

public void addFutureListener(IFutureListener<RESULT> listener)

Adds a listener on a future status (using strong reference). Listeners are automatically removed whenever the future gets its result (or is cancelled or an exception happens).

Parameters:

listener -

removeFutureListener

public void removeFutureListener(IFutureListener<RESULT> listener)

Removes a listener from the future.

Parameters:

listener -

isListening

public boolean isListening(IFutureListener<RESULT> listener)

Whether some listener is listening on the future.

Parameters:

listener -

Returns:

setResult

public void setResult(RESULT result)

Sets the result of the future computation.

Switches the status to FUTURE_IS_READY (notifying listeners along the way).

The result can be set only iff NOT isDone(), i.e., status is FutureStatus:FUTURE_IS_BEING_COMPUTED.

Parameters:

result -

computationException

public void computationException(java.lang.Exception e)

Informs the future that it can't be computed due to the exception.

Switches the status to EXCEPTION (notifying listeners along the way).

The result can be set only iff NOT isDone(), i.e., status is FutureStatus:FUTURE_IS_BEING_COMPUTED.

Parameters:

e -

switchStatus

protected void switchStatus(FutureStatus newStatus)

Changes the status of the future (if it is different than current one) and notifies the listeners about this change.

Parameters:

newStatus -

createLatch

protected java.util.concurrent.CountDownLatch createLatch()

Factory method that should return CountDownLatch or its descendant initialized to 1.

Returns:

cancelComputation

protected boolean cancelComputation(boolean mayInterruptIfRunning)

This should cancel the computation of the future. Current implementation returns always false. Override the method to provide correct behavior for particular future.

Parameters:

mayInterruptIfRunning -

Returns:

cancel

public final boolean cancel(boolean mayInterruptIfRunning)

Specified by:

cancel in interface java.util.concurrent.Future<RESULT>

get

public RESULT get()

Specified by:

get in interface java.util.concurrent.Future<RESULT>

get

public RESULT get(long timeout,
                  java.util.concurrent.TimeUnit unit)

Returns a result or waits for the computation till timeout.

Does not throw TimeoutException! It returns null instead - always examine status of the future via getStatus() if the null is returned to tell whether the 'null' is the result of the computation (if the status is FUTURE_IS_READY than the 'null' is truly the result).

Specified by:

get in interface java.util.concurrent.Future<RESULT>

Parameters:

timeout -

unit -

Returns:

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface java.util.concurrent.Future<RESULT>

isDone

public boolean isDone()

Specified by:

isDone in interface java.util.concurrent.Future<RESULT>

getException

public java.lang.Exception getException()

Contains an exception that has happened during the computation in the case of (getStatus() == EXCEPTION).

Returns: