net.sf.asyncobjects.util
Class Compensated

java.lang.Object
  net.sf.asyncobjects.util.Compensated

All Implemented Interfaces:

ExplicitSharing

Direct Known Subclasses:

CompensatedClosable

public abstract class Compensated
extends Object
implements ExplicitSharing

This a special return value for actions in some control constructs like Any. These construct discard some values, an if the value is an open resource, this could lead to serious resource leaks. This special value allows for compensating in such situations. The normal scenario of this this object is the following:

1. Caller invokes run() method and waits until method finishes. Note that before this method called, the action must not do anythig that requires compensation. The caller might silently abandon the right to call compensated action.
2. If it is known that the computation should be compensated and method is not yet finished, the caller calls cancel() method.
3. After run() method finishes, eventually it is determined whether computation is commited or should be compensated.
4. If it should be committed, the method committed() is called.
5. If it should be compensated, the methods compensateValue(Object) or compensateFailure(Throwable) are called depending on situation.

The subclasses are assumed to be thread-unsafe and they should not passed to other vats.

Constructor Summary

Compensated()

Method Summary

protected void	cancel() Cancel computation if it is possible.
protected void	committed() Commit computation.
protected void	compensateFailure(Throwable value) Compensate failed execution.
protected abstract void	compensateValue(Object value) Compensate successful execution
boolean	equals(Object obj)
int	hashCode()
protected abstract Object	run() Run primary action.

Methods inherited from class java.lang.Object

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

Constructor Detail

Compensated

public Compensated()

Method Detail

run

protected abstract Object run()
                       throws Throwable

Run primary action. This method is called by containing class upon recieving instance of this class.

Returns:

a value that is either promise, asyncobject, or scalar value. It is not treated specially.

Throws:

Throwable - if there is a problem during execution

compensateValue

protected abstract void compensateValue(Object value)
                                 throws Throwable

Compensate successful execution

Parameters:

value - a value to compensate with

Throws:

Throwable - if there is problem with compensating. Note that fault is logged and ignored.

compensateFailure

protected void compensateFailure(Throwable value)
                          throws Throwable

Compensate failed execution. Such execution usually does not need compensation.

Parameters:

value - a value to compensate with

Throws:

Throwable - if there is problem with compensating. Note that fault is logged and ignored.

cancel

protected void cancel()
               throws Throwable

Cancel computation if it is possible. Note that parent construct tries to execute compensation anyway after run method finishes. This is used in case when action can be interrupted. It is expetected that interruption cause run method to finish as soon as possible with some failure. The implementer should be able to recieve this method at any time after run method is started. For example it could be called even after compensation has been executed.

Throws:

Throwable - if there is problem with cancelling. Note that fault is logged and ignored.

committed

protected void committed()
                  throws Throwable

Commit computation. This method is called when caller is committed to using the value or the failure. The action could release values stored purely for future compensation.

Throws:

Throwable - if there is problem with forgetting. Note that fault is logged and ignored.

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)