net.sf.asyncobjects
Class Promise<T>

java.lang.Object
  extended by net.sf.asyncobjects.Promise<T>
Type Parameters:
T - a value type for promise
All Implemented Interfaces:
ExplicitSharing

public final class Promise<T>
extends Object
implements ExplicitSharing

A promise represents outcome of some asynchronous operation. The promise resolves to some value if operation is successful or is smashed with failure otherwise. An asychronous operation might never finish, in such case a promise stays unresolved forever.

A promise should be never directly accessed outside of vat where it were created. There are two indirect ways to access it from other vats:

  1. Using resolver interface.
  2. Using proxy created with willBe method.

The promise has three fundamental states:

UNRESOLVED
This is an inital state of promise.
RESOLVED
This state means that operation that created this promise has completed successfully. The promise goes into this state after AResolver.resolve(Object) method has been called on promise resolver. This is final state, and promise cannot change state after this state is reached. The promise can be created in the resolved state using the constructor Promise(Object) or the method with(Object)
SMASHED
This state means that operation that created this promise has failed with throwable (exception or error). The promise goes into this state after AResolver.smash(Throwable) method has been called on promise resolver. The promise could be also created in the smashed state using the method smashed(Throwable).

Note if promise is resolved with implementation of AsyncObject interface for which AsyncObject.isImmediate() == false, it does not consider itself resolved. Instead it invokes AsyncObject.dereference(AResolver) method with resolver() in order to receive actual resolution.

When promise is either resolved or smashed, it notifies downstream resolvers that has been registered using dereference(AResolver) method. After downstream resolver is registered, it is notified at most once. If resolver is registered after promise is resolved or smashed, the downstream resolver is notifed immediatly about outcome of operation.


Nested Class Summary
 class Promise.InternalPromiseResolverImpl
          This is an internal class.
 
Field Summary
static int RESOLVED
          resolved state
static int SMASHED
          broken state
static int UNRESOLVED
          unresolved state
 
Constructor Summary
Promise()
          A constructor for promise
Promise(T value)
          A constructor for promise.
 
Method Summary
<O> Promise<O>
cast(Class<O> type)
          Cast promise to another type.
 void dereference(AResolver<? super T> l)
          Register resolver for the promise.
static void ensureSharable(Object o)
          Ensure that value is sharable
 Promise<Void> finished()
           
static Promise<Void> finished(Promise<?> in)
           
 boolean isResolved()
           
 boolean isSmashed()
           
 boolean isUnresolved()
           
static
<O> Promise<O>
notNull(Promise<? extends O> p)
          Return promise that never returns null.
static
<O> Promise<O>
notNull(Promise<? extends O> p, String text)
          Return promise that never returns null.
static
<T> Promise<T>
nullPromise()
          Return a promise resolved to null.
 Throwable problem()
           
 AResolver<T> resolver()
          Get resolver for this promise.
static
<T> Promise<T>
smashed(Throwable t)
          Create smashed promise
 Promise<Void> toVoid()
          Convert promise to promise for void
static Promise<Void> toVoid(Promise<?> in)
          Convert promise to promise for void
static
<A> Promise<A>
upcast(Promise<? extends A> p)
          Upcast the promise.
 T value()
           
<P extends AsyncObject>
P
willBe(Class<P> proxyType)
           This method allows creation of the proxy that allows sending message to resolution before promise is resolved.
static
<T> Promise<T>
with(T value)
          Get promise with value
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SMASHED

public static final int SMASHED
broken state

See Also:
Constant Field Values

RESOLVED

public static final int RESOLVED
resolved state

See Also:
Constant Field Values

UNRESOLVED

public static final int UNRESOLVED
unresolved state

See Also:
Constant Field Values
Constructor Detail

Promise

public Promise(T value)
A constructor for promise. Promise starts being in resolved state unless unerolved buffering proxy is passed as the value..

Parameters:
value - a value to resolve promise with.

Promise

public Promise()
A constructor for promise

Method Detail

resolver

public AResolver<T> resolver()
Get resolver for this promise. The resolver could be obtained only once.

Returns:
resolver for this promise

willBe

public <P extends AsyncObject> P willBe(Class<P> proxyType)

This method allows creation of the proxy that allows sending message to resolution before promise is resolved.

If promise is resolved with some value, it is checked if the resolution supports interface represented by _class parameter. If the interface is supported, all pending invocations are sent to resolution including dereference calls.* If the interface is not supported by resolution, the behavior is that same as if promise were smashed with ClassCastException. If promise is resolves to null, the behavior of reference is the same as if it were smashed with NullPointerException. If promise was smashed with some exception, all promises and eventual proxies returned by previous method invocations are smashed with this exception. And the method AResolver.smash(Throwable) will be called on pending dereference() calls.

Type Parameters:
P - A proxy type
Parameters:
proxyType -
Returns:
proxy that records until this promise is resolved or smashed.

isResolved

public boolean isResolved()
Returns:
true, if promise is resolved

isSmashed

public boolean isSmashed()
Returns:
true, if promise is broken

isUnresolved

public boolean isUnresolved()
Returns:
true, if promise is unresolved

problem

public Throwable problem()
Returns:
problem if promise is broken

value

public T value()
Returns:
value if promise is resolved

dereference

public void dereference(AResolver<? super T> l)
Register resolver for the promise. Note that resolver is expected to be asynchronous object.

Parameters:
l - listener to register

ensureSharable

public static void ensureSharable(Object o)
Ensure that value is sharable

Parameters:
o - an object to check

toVoid

public Promise<Void> toVoid()
Convert promise to promise for void

Returns:
converted promise

finished

public Promise<Void> finished()
Returns:
a promise that resolves to null when promise finishes in one way or another. This is done to supress failures.

finished

public static Promise<Void> finished(Promise<?> in)
Parameters:
in - an input promise
Returns:
a promise that resolves to null when promise finishes in one way or another. This is done to supress failures.

toVoid

public static Promise<Void> toVoid(Promise<?> in)
Convert promise to promise for void

Parameters:
in - an input promise
Returns:
converted promise

nullPromise

public static <T> Promise<T> nullPromise()
Return a promise resolved to null.

Type Parameters:
T - a type of promise
Returns:
a promise for null

with

public static <T> Promise<T> with(T value)
Get promise with value

Type Parameters:
T - a value type
Parameters:
value - a value
Returns:
a promise that resolved with value

smashed

public static <T> Promise<T> smashed(Throwable t)
Create smashed promise

Type Parameters:
T - a type of promise
Parameters:
t - a promise value
Returns:
smashed promise

cast

public <O> Promise<O> cast(Class<O> type)
Cast promise to another type. The resulting promise will resolve to casted value or will be smashed with ClassCastException if cast is impossible.

Type Parameters:
O - a new type of promise
Parameters:
type - a new expected type
Returns:
a promise that will resolve to casted value

upcast

public static <A> Promise<A> upcast(Promise<? extends A> p)
Upcast the promise. The only case when this is not a type safe operation is when resolver is got from this promise with resolver().

Type Parameters:
A - a supper type
Parameters:
p - a promise to upcast
Returns:
an upcasted promise

notNull

public static <O> Promise<O> notNull(Promise<? extends O> p)
Return promise that never returns null. Instead, it is automatically smashed with NullPointerException if argument promise resolves to the null.

Type Parameters:
O - a type
Parameters:
p - an arugment promise
Returns:
a promise that is smashed in case of null

notNull

public static <O> Promise<O> notNull(Promise<? extends O> p,
                                     String text)
Return promise that never returns null. Instead, it is automatically smashed with NullPointerException if argument promise resolves to the null.

Type Parameters:
O - a type
Parameters:
p - an arugment promise
text - a text for NullPointerException
Returns:
a promise that is smashed in case of null


Copyright 2002-2007 Constantine Plotnikov. All Rights Reserved.