cz.cuni.amis.utils.future

Class FutureWithListeners<RESULT>

java.lang.Object

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

Type Parameters:

RESULT -

All Implemented Interfaces:

IFutureWithListeners<RESULT>, Future<RESULT>

public abstract class FutureWithListeners<RESULT>
extends Object
implements IFutureWithListeners<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.

Author:

Jimmy

Field Summary

Fields

Modifier and Type	Field and Description
protected 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 Object	mutex Mutex synchronizing access to internal data structures of the future.

Constructor Summary

Constructors

Constructor and Description
FutureWithListeners()

Method Summary

Modifier and Type	Method and Description
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(Exception e) Informs the future that it can't be computed due to the exception.
protected CountDownLatch	createLatch() Factory method that should return CountDownLatch or its descendant initialized to 1.
RESULT	get()
RESULT	get(long timeout, TimeUnit unit) Returns a result or waits for the computation till timeout.
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 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 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.

Specified by:

getStatus in interface IFutureWithListeners<RESULT>

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).

Specified by:

addFutureListener in interface IFutureWithListeners<RESULT>

Parameters:

listener -

removeFutureListener

public void removeFutureListener(IFutureListener<RESULT> listener)

Removes a listener from the future.

Specified by:

removeFutureListener in interface IFutureWithListeners<RESULT>

Parameters:

listener -

isListening

public boolean isListening(IFutureListener<RESULT> listener)

Whether some listener is listening on the future.

Specified by:

isListening in interface IFutureWithListeners<RESULT>

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.

Specified by:

setResult in interface IFutureWithListeners<RESULT>

Parameters:

result -

computationException

public void computationException(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.

Specified by:

computationException in interface IFutureWithListeners<RESULT>

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 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 IFutureWithListeners<RESULT>

Specified by:

cancel in interface Future<RESULT>

get

public RESULT get()

Specified by:

get in interface IFutureWithListeners<RESULT>

Specified by:

get in interface Future<RESULT>

get

public RESULT get(long timeout,
                  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 IFutureWithListeners<RESULT>

Specified by:

get in interface Future<RESULT>

Parameters:

timeout -

unit -

Returns:

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface IFutureWithListeners<RESULT>

Specified by:

isCancelled in interface Future<RESULT>

isDone

public boolean isDone()

Specified by:

isDone in interface IFutureWithListeners<RESULT>

Specified by:

isDone in interface Future<RESULT>

getException

public Exception getException()

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

Specified by:

getException in interface IFutureWithListeners<RESULT>

Returns: