net.sf.asyncobjects.util
Class Compensated

java.lang.Object
  extended by 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)


Copyright 2002-2007 Constantine Plotnikov. All Rights Reserved.