org.curjent.impl.agent
Class MessageCall

java.lang.Object
  extended by org.curjent.impl.agent.MessageFuture
      extended by org.curjent.impl.agent.MessageCall
All Implemented Interfaces:
Future<Object>, AgentCall<Object>

final class MessageCall
extends MessageFuture
implements AgentCall<Object>

Implements AgentCall on behalf of a message. Returned to clients instead of a reference to the message in order to avoid synchronization conflicts (i.e., it is safe for clients to synchronize on the returned MessageCall instance but not on a Message instance). MessageCall instances are passed to listeners via CallStateListener.callStateChanged(AgentCall, CallState) in Message.setState(CallState, CallCompletion, Object, Throwable) and in the generated agent proxy for agent interface methods returning AgentCall.

See Also:
Message.getCall()

Field Summary
private  CallStateListener<?>[] assigned
          Call's assigned state listeners.
private  Object data
          Client data for this message.
(package private)  CallStateListener<?>[] effective
          Call's effective state listeners.
private  CallStateListener<?> listener
          Call's default listener for unassigned state listeners.
 
Fields inherited from class org.curjent.impl.agent.MessageFuture
message
 
Constructor Summary
MessageCall(Message message)
          Saves the owning message.
 
Method Summary
 void await()
          Delegates to Message.await(CallState, long, TimeUnit).
 void await(CallState state)
          Delegates to Message.await(CallState, long, TimeUnit).
 boolean await(CallState state, long timeout, TimeUnit unit)
          Delegates to Message.await(CallState, long, TimeUnit).
 boolean finish()
          Delegates to Message.finish(boolean, boolean, Object, Throwable).
 boolean finish(boolean interrupt, boolean abandon, Object result, Throwable exception)
          Delegates to Message.finish(boolean, boolean, Object, Throwable).
 boolean finish(Object result)
          Delegates to Message.finish(boolean, boolean, Object, Throwable).
 boolean finish(Throwable exception)
          Delegates to Message.finish(boolean, boolean, Object, Throwable).
 Object getArgument(int index)
          Delegates to Message.getArgument(int).
 int getArgumentCount()
          Delegates to Message.getArgumentCount().
 CallSite getCallSite()
          Returns message.info.
 CallStateListener<?> getCallStateListener()
          Returns the default listener for this call.
 CallStateListener<?> getCallStateListener(CallState state)
          Returns the listener for a specified state change for this call.
 CallCompletion getCompletion()
          Delegates to Message.getCompletion().
 Object getData()
          Returns the client's data for this message.
 Throwable getException()
          Delegates to Message.getException().
 long getExpirationTimeoutNanos()
          Delegates to Expirations.getExpirationTimeoutNanos(Message).
 Object getResult()
          Delegates to Message.getResult().
 CallState getState()
          Delegates to Message.getState().
private  void initializeListeners()
          Initializes the listener fields.
 boolean isReentry()
          Delegates to Message.isReentry().
 void run(Runnable runnable)
          Locks the agent, synchronizes the message, and runs the given runnable.
 void setArgument(int index, Object value)
          Delegates to Message.setArgument(int, Object).
 boolean setCallStateListener(CallState state, CallStateListener<?> listener)
          Sets or clears the listener for a specified state change for this call.
 CallState setCallStateListener(CallStateListener<?> listener)
          Sets or clears the default listener for this call.
 void setData(Object data)
          Saves or clears the client's data for this message.
private static void setEffectiveListeners(CallStateListener<?>[] effective, CallStateListener<?> listener, CallStateListener<?>[] assigned)
          Sets the effective listeners.
 void setException(Throwable exception)
          Delegates to Message.setException(Throwable).
 boolean setExpirationTimeout(long value, TimeUnit unit)
          Delegates to Expirations.setExpirationTimeout(Message, long, TimeUnit).
 void setResult(Object value)
          Delegates to Message.setResult(Object).
 
Methods inherited from class org.curjent.impl.agent.MessageFuture
cancel, get, get, isCancelled, isDone, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.concurrent.Future
cancel, get, get, isCancelled, isDone
 

Field Detail

listener

private CallStateListener<?> listener
Call's default listener for unassigned state listeners.

See Also:
setCallStateListener(CallStateListener)

assigned

private CallStateListener<?>[] assigned
Call's assigned state listeners. Lazily initialized.

See Also:
setCallStateListener(CallState, CallStateListener)

effective

CallStateListener<?>[] effective
Call's effective state listeners. Lazily initialized.

This is accessed directly by the message's setState method and is therefore synchronized on the message's monitor, as is listener and assigned.

See Also:
setEffectiveListeners(CallStateListener[], CallStateListener, CallStateListener[])

data

private Object data
Client data for this message.

See Also:
setData(Object)
Constructor Detail

MessageCall

MessageCall(Message message)
Saves the owning message.

Method Detail

getState

public CallState getState()
Delegates to Message.getState().

Specified by:
getState in interface AgentCall<Object>
See Also:
CallState

getCompletion

public CallCompletion getCompletion()
Delegates to Message.getCompletion().

Specified by:
getCompletion in interface AgentCall<Object>
See Also:
CallCompletion

isReentry

public boolean isReentry()
Delegates to Message.isReentry().

Specified by:
isReentry in interface AgentCall<Object>

getArgumentCount

public int getArgumentCount()
Delegates to Message.getArgumentCount().

Specified by:
getArgumentCount in interface AgentCall<Object>

getArgument

public Object getArgument(int index)
Delegates to Message.getArgument(int).

Specified by:
getArgument in interface AgentCall<Object>
Parameters:
index - Index of the argument. The first value is at index 0 and the last at index getArgumentCount() - 1.

setArgument

public void setArgument(int index,
                        Object value)
Delegates to Message.setArgument(int, Object).

Specified by:
setArgument in interface AgentCall<Object>
See Also:
AgentCall.getArgument(int)

getResult

public Object getResult()
Delegates to Message.getResult().

Specified by:
getResult in interface AgentCall<Object>

setResult

public void setResult(Object value)
Delegates to Message.setResult(Object).

Specified by:
setResult in interface AgentCall<Object>
See Also:
AgentCall.getResult()

getException

public Throwable getException()
Delegates to Message.getException().

Specified by:
getException in interface AgentCall<Object>
See Also:
AgentCall.setException(Throwable)

setException

public void setException(Throwable exception)
Delegates to Message.setException(Throwable).

Specified by:
setException in interface AgentCall<Object>
See Also:
AgentCall.getException()

finish

public boolean finish()
Delegates to Message.finish(boolean, boolean, Object, Throwable).

Specified by:
finish in interface AgentCall<Object>
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(Object result)
Delegates to Message.finish(boolean, boolean, Object, Throwable).

Specified by:
finish in interface AgentCall<Object>
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)
Delegates to Message.finish(boolean, boolean, Object, Throwable).

Specified by:
finish in interface AgentCall<Object>
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,
                      Object result,
                      Throwable exception)
Delegates to Message.finish(boolean, boolean, Object, Throwable).

Specified by:
finish in interface AgentCall<Object>
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.

await

public void await()
           throws InterruptedException
Delegates to Message.await(CallState, long, TimeUnit).

Specified by:
await in interface AgentCall<Object>
Throws:
InterruptedException - The caller's thread was interrupted.

await

public void await(CallState state)
           throws InterruptedException
Delegates to Message.await(CallState, long, TimeUnit).

Specified by:
await in interface AgentCall<Object>
Parameters:
state - Call state to reach or pass.
Throws:
InterruptedException - The caller's thread was interrupted.

await

public boolean await(CallState state,
                     long timeout,
                     TimeUnit unit)
              throws InterruptedException
Delegates to Message.await(CallState, long, TimeUnit).

Specified by:
await in interface AgentCall<Object>
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.
Throws:
InterruptedException - The caller's thread was interrupted.

setExpirationTimeout

public boolean setExpirationTimeout(long value,
                                    TimeUnit unit)
Delegates to Expirations.setExpirationTimeout(Message, long, TimeUnit).

Specified by:
setExpirationTimeout in interface AgentCall<Object>
See Also:
Expiration

getExpirationTimeoutNanos

public long getExpirationTimeoutNanos()
Delegates to Expirations.getExpirationTimeoutNanos(Message).

Specified by:
getExpirationTimeoutNanos in interface AgentCall<Object>

getCallStateListener

public CallStateListener<?> getCallStateListener()
Returns the default listener for this call.

Specified by:
getCallStateListener in interface AgentCall<Object>
See Also:
AgentCall.setCallStateListener(CallStateListener)

setCallStateListener

public CallState setCallStateListener(CallStateListener<?> listener)
Sets or clears the default listener for this call. Returns the current call state at the time the listener was set.

Specified by:
setCallStateListener in interface AgentCall<Object>
See Also:
AgentCall.setCallStateListener(CallState, CallStateListener)

getCallStateListener

public CallStateListener<?> getCallStateListener(CallState state)
Returns the listener for a specified state change for this call.

Specified by:
getCallStateListener in interface AgentCall<Object>
See Also:
AgentCall.setCallStateListener(CallState, CallStateListener)

setCallStateListener

public boolean setCallStateListener(CallState state,
                                    CallStateListener<?> listener)
Sets or clears the listener for a specified state change for this call. Returns true if the call has already reached or passed the given state.

Specified by:
setCallStateListener in interface AgentCall<Object>
See Also:
AgentCall.setCallStateListener(CallStateListener)

initializeListeners

private void initializeListeners()
Initializes the listener fields.


setEffectiveListeners

private static void setEffectiveListeners(CallStateListener<?>[] effective,
                                          CallStateListener<?> listener,
                                          CallStateListener<?>[] assigned)
Sets the effective listeners.


run

public void run(Runnable runnable)
Locks the agent, synchronizes the message, and runs the given runnable. This ensures the agent and message are stable while runnable is executing.

Specified by:
run in interface AgentCall<Object>
Parameters:
runnable - Object to run.
See Also:
AgentCall.run(Runnable)

getData

public Object getData()
Returns the client's data for this message.

Specified by:
getData in interface AgentCall<Object>

setData

public void setData(Object data)
Saves or clears the client's data for this message.

Specified by:
setData in interface AgentCall<Object>

getCallSite

public CallSite getCallSite()
Returns message.info.

Specified by:
getCallSite in interface AgentCall<Object>


Copyright 2009-2011 Tom Landon
Apache License 2.0