org.curjent.agent
Class AgentResult<V>

java.lang.Object
  org.curjent.agent.AgentResult<V>

All Implemented Interfaces:

Future<V>, AgentCall<V>

public class AgentResult<V>
extends Object
implements AgentCall<V>

Holder for a future's value. See Futures in org.curjent.agent for background information on future results and why a task would want to wrap a result in a holder such as this. The following are concrete examples for designing a task to return future results.

One option is to design the task to return the result directly:

 interface Counter {
     Future<Integer> getCount();
 }
 
 class CounterTask {
     private int count;
     
     int getCount() {
         return count;
     }
 }
 

With this design, the task simply returns the value. For this to compile, though, the task cannot add an implements clause with the Counter interface.

Alternative, the task can return a holder for the value:

 class CounterTask implements Counter {
     private int count;
     
     Future<Integer> getCount() {
         return new AgentResult<Integer>(count);
     }
 }
 

This enables the task designer to declare the Counter interface in its implements clause and thus catch method signature problems at compile time instead of runtime.

This holder works for Future and AgentCall results.

Instances of AgentResult are not intended to be returned directly to agent clients. This class is intended as a helper for tasks returning results for future values. Only the get() method is used for this purpose. Other methods return constant values (e.g., isDone() always returns true) or throw UnsupportedOperationException.

Constructor Summary

AgentResult(V value)
Saves the result's value.

Method Summary

void	await() Does nothing.
void	await(CallState state) Does nothing.
boolean	await(CallState state, long timeout, TimeUnit unit) Does nothing and returns false.
boolean	cancel(boolean mayInterruptIfRunning) Does nothing and returns false.
boolean	finish() Does nothing and returns false.
boolean	finish(boolean interrupt, boolean abandon, V result, Throwable exception) Does nothing and returns false.
boolean	finish(Throwable exception) Does nothing and returns false.
boolean	finish(V result) Does nothing and returns false.
V	get() Immediately returns the saved result value.
V	get(long timeout, TimeUnit unit) Immediately returns the saved result value.
Object	getArgument(int index) Throws UnsupportedOperationException.
int	getArgumentCount() Throws UnsupportedOperationException.
CallSite	getCallSite() Throws UnsupportedOperationException.
CallStateListener<?>	getCallStateListener() Throws UnsupportedOperationException.
CallStateListener<?>	getCallStateListener(CallState state) Throws UnsupportedOperationException.
CallCompletion	getCompletion() Throws UnsupportedOperationException.
Object	getData() Throws UnsupportedOperationException.
Throwable	getException() Throws UnsupportedOperationException.
long	getExpirationTimeout() Throws UnsupportedOperationException.
long	getExpirationTimeoutNanos() Throws UnsupportedOperationException.
TimeUnit	getExpirationTimeoutUnit() Throws UnsupportedOperationException.
V	getResult() Returns the saved result value.
CallState	getState() Always returns FINISHED.
boolean	isCancelled() Always returns false.
boolean	isDone() Always returns true.
boolean	isFinished() Always returns true.
boolean	isReentry() Always returns false.
void	run(Runnable runnable) Throws UnsupportedOperationException.
void	setArgument(int index, Object value) Throws UnsupportedOperationException.
boolean	setCallStateListener(CallState state, CallStateListener<?> listener) Throws UnsupportedOperationException.
CallState	setCallStateListener(CallStateListener<?> listener) Throws UnsupportedOperationException.
void	setData(Object data) Throws UnsupportedOperationException.
void	setException(Throwable exception) Throws UnsupportedOperationException.
boolean	setExpirationTimeout(long value, TimeUnit unit) Throws UnsupportedOperationException.
void	setResult(V value) Throws UnsupportedOperationException.

Methods inherited from class java.lang.Object

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

Constructor Detail

AgentResult

public AgentResult(V value)

Saves the result's value. The given value is returned by this result's get methods.

Method Detail

get

public V get()

Immediately returns the saved result value.

Specified by:

get in interface Future<V>

get

public V get(long timeout,
             TimeUnit unit)

Immediately returns the saved result value. The timeout and unit arguments are ignored.

Specified by:

get in interface Future<V>

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Does nothing and returns false. The argument is ignored.

Specified by:

cancel in interface Future<V>

isCancelled

public boolean isCancelled()

Always returns false.

Specified by:

isCancelled in interface Future<V>

isDone

public boolean isDone()

Always returns true.

Specified by:

isDone in interface Future<V>

await

public void await()

Does nothing.

Specified by:

await in interface AgentCall<V>

await

public void await(CallState state)

Does nothing.

Specified by:

await in interface AgentCall<V>

Parameters:

state - Call state to reach or pass.

await

public boolean await(CallState state,
                     long timeout,
                     TimeUnit unit)

Does nothing and returns false. All arguments are ignored.

Specified by:

await in interface AgentCall<V>

Parameters:

state - Call state to reach or pass. For example, if state is EXECUTING, this method waits until the call's state is either EXECUTING or FINISHED.

timeout - The timeout period. 0 or negative to timeout immediately. Long.MAX_VALUE to never timeout.

unit - The timeout units. May be null if timeout is 0 or Long.MAX_VALUE.

Returns:

true if the call state was reached or passed. false if the call state was not reached when the timeout period expired.

finish

public boolean finish()

Does nothing and returns false.

Specified by:

finish in interface AgentCall<V>

Returns:

false if the call was already FINISHED; true in all other cases.

See Also:

AgentCall.setResult(Object), AgentCall.setException(Throwable)

finish

public boolean finish(V result)

Does nothing and returns false. The argument is ignored.

Specified by:

finish in interface AgentCall<V>

Parameters:

result - The value of the call's result if successfully finished. May cause this method to throw an exception if the value is invalid. Sets the result value to the system default value (0, false, \u0000, etc.) for primitive types if result is null. Ignored for void result types with a result value of null.

Returns:

true if successfully transitioned to the FINISHED state.

See Also:

AgentCall.setResult(Object), AgentCall.setException(Throwable), AgentCall.finish(), AgentCall.finish(boolean, boolean, Object, Throwable)

finish

public boolean finish(Throwable exception)

Does nothing and returns false. The argument is ignored.

Specified by:

finish in interface AgentCall<V>

Parameters:

exception - The call's exception value if successfully finished. This value takes precedence over the result value; i.e., if exception is non-null, it is thrown regardless of the result value.

Returns:

true if successfully transitioned to the FINISHED state.

See Also:

AgentCall.setResult(Object), AgentCall.setException(Throwable), AgentCall.finish(), AgentCall.finish(boolean, boolean, Object, Throwable)

finish

public boolean finish(boolean interrupt,
                      boolean abandon,
                      V result,
                      Throwable exception)

Does nothing and returns false. All arguments are ignored.

Specified by:

finish in interface AgentCall<V>

Parameters:

interrupt - If true and the call is in the EXECUTING state with an assigned thread, the executing thread is interrupted. Ignored if false.

abandon - If true and the call is in the EXECUTING state, finishes the call and abandons the running task, leaving it running orphaned in the background. Ignored if false.

result - The value of the call's result if successfully finished. May cause this method to throw an exception if the value is invalid. Sets the result value to the system default value (0, false, \u0000, etc.) for primitive types if result is null. Ignored for void result types with a result value of null.

exception - The call's exception value if successfully finished. This value takes precedence over the result value; i.e., if exception is non-null, it is thrown regardless of the result value.

Returns:

true if successfully transitioned to the FINISHED state.

getCallSite

public CallSite getCallSite()

Throws UnsupportedOperationException.

Specified by:

getCallSite in interface AgentCall<V>

getCompletion

public CallCompletion getCompletion()

Throws UnsupportedOperationException.

Specified by:

getCompletion in interface AgentCall<V>

See Also:

CallCompletion

getData

public Object getData()

Throws UnsupportedOperationException.

Specified by:

getData in interface AgentCall<V>

getException

public Throwable getException()

Throws UnsupportedOperationException.

Specified by:

getException in interface AgentCall<V>

See Also:

AgentCall.setException(Throwable)

getArgument

public Object getArgument(int index)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

getArgument in interface AgentCall<V>

Parameters:

index - Index of the argument. The first value is at index 0 and the last at index getArgumentCount() - 1.

getArgumentCount

public int getArgumentCount()

Throws UnsupportedOperationException.

Specified by:

getArgumentCount in interface AgentCall<V>

getResult

public V getResult()

Returns the saved result value.

Specified by:

getResult in interface AgentCall<V>

getState

public CallState getState()

Always returns FINISHED.

Specified by:

getState in interface AgentCall<V>

See Also:

CallState

isFinished

public boolean isFinished()

Always returns true.

isReentry

public boolean isReentry()

Always returns false.

Specified by:

isReentry in interface AgentCall<V>

run

public void run(Runnable runnable)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

run in interface AgentCall<V>

Parameters:

runnable - Object to run.

setData

public void setData(Object data)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

setData in interface AgentCall<V>

setException

public void setException(Throwable exception)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

setException in interface AgentCall<V>

See Also:

AgentCall.getException()

setArgument

public void setArgument(int index,
                        Object value)

Throws UnsupportedOperationException. All arguments are ignored.

Specified by:

setArgument in interface AgentCall<V>

See Also:

AgentCall.getArgument(int)

setResult

public void setResult(V value)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

setResult in interface AgentCall<V>

See Also:

AgentCall.getResult()

getCallStateListener

public CallStateListener<?> getCallStateListener()

Throws UnsupportedOperationException.

Specified by:

getCallStateListener in interface AgentCall<V>

See Also:

AgentCall.setCallStateListener(CallStateListener)

setCallStateListener

public CallState setCallStateListener(CallStateListener<?> listener)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

setCallStateListener in interface AgentCall<V>

See Also:

AgentCall.setCallStateListener(CallState, CallStateListener)

getCallStateListener

public CallStateListener<?> getCallStateListener(CallState state)

Throws UnsupportedOperationException. The argument is ignored.

Specified by:

getCallStateListener in interface AgentCall<V>

See Also:

AgentCall.setCallStateListener(CallState, CallStateListener)

setCallStateListener

public boolean setCallStateListener(CallState state,
                                    CallStateListener<?> listener)

Throws UnsupportedOperationException. All arguments are ignored.

Specified by:

setCallStateListener in interface AgentCall<V>

See Also:

AgentCall.setCallStateListener(CallStateListener)

getExpirationTimeout

public long getExpirationTimeout()

Throws UnsupportedOperationException.

getExpirationTimeoutUnit

public TimeUnit getExpirationTimeoutUnit()

Throws UnsupportedOperationException.

setExpirationTimeout

public boolean setExpirationTimeout(long value,
                                    TimeUnit unit)

Throws UnsupportedOperationException. All arguments are ignored.

Specified by:

setExpirationTimeout in interface AgentCall<V>

See Also:

Expiration

getExpirationTimeoutNanos

public long getExpirationTimeoutNanos()

Throws UnsupportedOperationException.

Specified by:

getExpirationTimeoutNanos in interface AgentCall<V>