de.esprit.netsuite.netdata.agent

Class AbstractSuperAgent<C extends ClientContext,S extends ServerContext>

java.lang.Object

de.esprit.common.util.DumpableObject

de.esprit.common.util.TransferableObject

de.esprit.netsuite.netdata.AbstractCrossPlatformObject<C,S>

de.esprit.netsuite.netdata.agent.AbstractAgent<C,S>

de.esprit.netsuite.netdata.agent.AbstractSuperAgent<C,S>

All Implemented Interfaces:

TaskIdHolder, Renderable, SimpleLogSupport, DeepCloneable, Dumpable, ClientObject<C>, Agent<C,S>, SuperAgent<C,S>, TimeMeasurable, CrossPlatformObject<C,S>, ServerObject<S>, java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

AbstractInternalAgent, AbstractLockableAgent, AbstractLoginAgent, AbstractSequencedAgent, ClientInfoUpdateAgent, JournalTaskDeregisterAgent, JournalTaskListAgent, RegisterForProgressEventsAgent, RemoteTaskProgessSwitchAgent, RemoteTaskReleaseAgent, RemoteTaskRunStateFlagAgent, RemoteTaskStartAgent, ServerActivityInfoAgent, ServerStatisticsRefreshAgent

public abstract class AbstractSuperAgent<C extends ClientContext,S extends ServerContext>
extends AbstractAgent<C,S>
implements SuperAgent<C,S>

This is the abstract base class for all agent implementations. It may execute on the server either synchronously (received in response) or asynchronously (received in message) depending on the isAsync() flag. Because the agent always contains a SessionId the server knows who the actor is.

Note that if the agent is running asynchronously you should implement the Agent.executeOnServer() method such that the agent remains cancellable in a well controlled way. You achieve this by calling the checkCancelled() method in regular time frames.

Author:

Rainer Buesch

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
AbstractSuperAgent(C clientCtx)
AbstractSuperAgent(C clientCtx, boolean isAsync)
AbstractSuperAgent(ClientConnector conn)
AbstractSuperAgent(ClientConnector conn, boolean isAsync)

Method Summary

Methods

Modifier and Type	Method and Description
void	checkCancelled() Throws a CancellationException when the agent was cancelled.
void	clearClientParams() Clears the parameters in the client cache that have been set by this agent.
void	doOnClientSideCancellation() Is called by the TaskManager when an AgentId is being cancelled.
void	doOnMessageError() Is called on the client when the received agent contains an error.
void	doOnMessageReceived() Is called on the client side when the agent has been received in a message.
void	doOnServerSideCancellation() Is called by the AgentExecutorTask when a cancellation has been detected.
void	executeForResponse() This method is called on an asynchronous agent only, before it is returned within the NetResponse.
<T> T	getClientParam(java.lang.String key) Fetches an agent specific parameter from the client cache.
java.util.Map	getClientParams() Allows an async agent to store an Agent-specific parameter in a client cache.
SessionId	getKillerSessionId() Tells which foreign user has cancelled the agent
int	getMessageTimeout() Returns the async execution timeout
java.awt.Color	getRenderColor()
javax.swing.Icon	getRenderIcon()
java.lang.String	getRenderText()
boolean	hasClientParam(java.lang.String key) Checks whether an agent specific parameter exists in the client cache.
boolean	isAsync() Tells whether the agent should be executed asynchroneosly on the server in which case it is sent back to the client via a NetMessage.
boolean	isIgnoreMessageError() Tells whether errors are being ignored by the client when the agent is received in a message.
boolean	isNoReturn() Tells whether this async agent should never be returned to the sender within a NetMessage.
boolean	isTimedOut() Tells whether the agent has been cancelled due to an async execution timeout on server side.
void	putClientParam(java.lang.String key, java.lang.Object value) Putting a null value results in removing the key
<A extends Agent<C,S>> A	sendForSilentExecution() Same as Agent.sendForExecution() just without throwing an Exception.
void	setAsync(boolean isAsync) If this flag is set the agent is executed asynchroneosly on the server.
void	setCancelledBy(SessionId killerSessId) Marks the agent to be cancelled without performing any further cancel action.
void	setIgnoreMessageError(boolean isIgnoreError) Allows for suppressing automatic error handling.
void	setMessageTimeout(int seconds) Defines a timeout in seconds for asynchronous execution on server side before the agent is returned in a message.
void	setNoReturn(boolean isNoReturn) Tells whether this async agent should never be returned to the sender within a NetMessage.
void	sleepChecked(long millis) Used to delay async execution.
DumpString	toDumpString(DumpString s) This method creates a multi line debug output to display the full content of the agent.
ToString	toString(ToString s) This method creates a single line debug output to display the most important properties of the agent
boolean	wasCancelled() Tells whether this agent ever has been tried to be cancelled.

Methods inherited from class de.esprit.netsuite.netdata.agent.AbstractAgent

createAgentId, doBeforeSend, doFinallyOnClient, doFinallyOnServer, doInitiallyOnClient, doInitiallyOnServer, doOnResponseConfirmed, doOnResponseError, doOnResponseReceived, equals, fetchSession, finished, getAgentId, getArgument, getError, getName, getOwnerSessionId, getPriority, getProcessingDuration, getReceivedTime, getResponseTimeout, getSentTime, getSessionId, getTargetServer, getTaskId, getTotalDuration, getTransferDuration, getZippedArgumentLength, hasError, hashCode, hasRun, isPartialResultsEnabled, isReceived, isReceivedInMessage, isReceivedInResponse, isRejectable, logDebug, logDump, logError, logError, logFatal, logInfo, logVerbose, logWarning, sendForBooleanExecution, sendForExecution, setArgument, setArgument, setFailed, setName, setOwnerSessionId, setPartialResultsEnabled, setPriority, setReceivedInMessage, setReceivedTime, setRejectable, setResponseTimeout, setSentTime, setServerContext, setSessionId, setTargetServer

Methods inherited from class de.esprit.netsuite.netdata.AbstractCrossPlatformObject

checkOnClient, checkOnServer, getClientContext, getLogChannel, getServerContext, isLogDebug, isLogVerbose, isOnClient, isOnServer, setClientContext, setLogChannel

Methods inherited from class de.esprit.common.util.TransferableObject

clone, copy

Methods inherited from class de.esprit.common.util.DumpableObject

configureDumpHeadlineLength, configureDumpMaxElementsPrinted, copyDumpStringValues, copyToStringValues, createDumpHeader, toDumpString, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.esprit.netsuite.netdata.agent.Agent

doBeforeSend, doFinallyOnClient, doFinallyOnServer, doInitiallyOnClient, doInitiallyOnServer, doOnResponseConfirmed, doOnResponseError, doOnResponseReceived, executeOnServer, fetchSession, finished, getAgentId, getArgument, getError, getName, getOwnerSessionId, getPriority, getResponseTimeout, getSessionId, getTargetServer, hasError, hasRun, isPartialResultsEnabled, isReceived, isReceivedInMessage, isReceivedInResponse, isRejectable, sendForBooleanExecution, sendForExecution, setArgument, setArgument, setFailed, setName, setOwnerSessionId, setPartialResultsEnabled, setPriority, setReceivedInMessage, setRejectable, setResponseTimeout, setSessionId, setTargetServer

Methods inherited from interface de.esprit.netsuite.netdata.CrossPlatformObject

isOnClient, isOnServer, setClientContext, setServerContext

Methods inherited from interface de.esprit.netsuite.client.ClientObject

getClientContext

Methods inherited from interface de.esprit.netsuite.server.ServerObject

getServerContext

Methods inherited from interface de.esprit.common.type.Dumpable

toDumpString, toString

Methods inherited from interface de.esprit.common.type.DeepCloneable

copy

Methods inherited from interface de.esprit.netsuite.netdata.agent.TimeMeasurable

getProcessingDuration, getReceivedTime, getSentTime, getTotalDuration, getTransferDuration, setReceivedTime, setSentTime

Methods inherited from interface de.esprit.common.log.SimpleLogSupport

getLogChannel, isLogDebug, isLogVerbose, logDebug, logDump, logError, logError, logFatal, logInfo, logVerbose, logWarning, setLogChannel

Constructor Detail

AbstractSuperAgent

public AbstractSuperAgent(C clientCtx)

AbstractSuperAgent

public AbstractSuperAgent(C clientCtx,
                  boolean isAsync)

AbstractSuperAgent

public AbstractSuperAgent(ClientConnector conn)

AbstractSuperAgent

public AbstractSuperAgent(ClientConnector conn,
                  boolean isAsync)

Method Detail

isIgnoreMessageError

public boolean isIgnoreMessageError()

Description copied from interface: SuperAgent

Tells whether errors are being ignored by the client when the agent is received in a message.

Specified by:

isIgnoreMessageError in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.setIgnoreMessageError(boolean)

setIgnoreMessageError

public void setIgnoreMessageError(boolean isIgnoreError)

Description copied from interface: SuperAgent

Allows for suppressing automatic error handling. If set to true, then errors in an agent message will not be handled by the client.

Specified by:

setIgnoreMessageError in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.isIgnoreMessageError()

getMessageTimeout

public int getMessageTimeout()

Description copied from interface: SuperAgent

Returns the async execution timeout

Specified by:

getMessageTimeout in interface SuperAgent<C extends ClientContext,S extends ServerContext>

setMessageTimeout

public void setMessageTimeout(int seconds)

Description copied from interface: SuperAgent

Defines a timeout in seconds for asynchronous execution on server side before the agent is returned in a message. When execution exceeds this time-limit the returned agent will contain a AgentExecutionTimeoutException. A value of zero indicates that infinite execution is allowed.

Note: a default agent async execution timeout may be set as a ServerStartup parameter

Specified by:

setMessageTimeout in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

ServerStartup.getAsyncAgentTimeout()

isTimedOut

public final boolean isTimedOut()

Description copied from interface: SuperAgent

Tells whether the agent has been cancelled due to an async execution timeout on server side. The agent then contains an AgentExecutionTimeoutException.

Specified by:

isTimedOut in interface SuperAgent<C extends ClientContext,S extends ServerContext>

isAsync

public boolean isAsync()

Description copied from interface: SuperAgent

Tells whether the agent should be executed asynchroneosly on the server in which case it is sent back to the client via a NetMessage.

Specified by:

isAsync in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.setAsync(boolean)

setAsync

public void setAsync(boolean isAsync)

Description copied from interface: SuperAgent

If this flag is set the agent is executed asynchroneosly on the server.

Specified by:

setAsync in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.isAsync()

doOnMessageReceived

public void doOnMessageReceived()
                         throws java.lang.Exception

Is called on the client side when the agent has been received in a message. The default implementation is empty.

Specified by:

doOnMessageReceived in interface SuperAgent<C extends ClientContext,S extends ServerContext>

Throws:

java.lang.Exception

doOnMessageError

public void doOnMessageError()

Is called on the client when the received agent contains an error. Default implementation just delegates to the ClientErrorHandler.

Specified by:

doOnMessageError in interface SuperAgent<C extends ClientContext,S extends ServerContext>

sleepChecked

public void sleepChecked(long millis)

Used to delay async execution. This method may be called within loops in order to be friendly to other tasks and not making the system too busy. Note that when going to and awaking from sleep the cancel state is checked and a CancellationException is thrown just in case.

Throws:

java.util.concurrent.CancellationException - if cancellation was detected during sleep

checkCancelled

public final void checkCancelled()

Throws a CancellationException when the agent was cancelled.

wasCancelled

public boolean wasCancelled()

Description copied from interface: SuperAgent

Tells whether this agent ever has been tried to be cancelled.

Specified by:

wasCancelled in interface SuperAgent<C extends ClientContext,S extends ServerContext>

setCancelledBy

public void setCancelledBy(SessionId killerSessId)

Marks the agent to be cancelled without performing any further cancel action.

Specified by:

setCancelledBy in interface SuperAgent<C extends ClientContext,S extends ServerContext>

getKillerSessionId

public SessionId getKillerSessionId()

Description copied from interface: SuperAgent

Tells which foreign user has cancelled the agent

Specified by:

getKillerSessionId in interface SuperAgent<C extends ClientContext,S extends ServerContext>

doOnClientSideCancellation

public void doOnClientSideCancellation()

Description copied from interface: SuperAgent

Is called by the TaskManager when an AgentId is being cancelled. Within this method the agent may perform any client-side reaction on cancellation. Note that this method is called BEFORE the cancel-request is sent to the server.

Specified by:

doOnClientSideCancellation in interface SuperAgent<C extends ClientContext,S extends ServerContext>

doOnServerSideCancellation

public void doOnServerSideCancellation()

Description copied from interface: SuperAgent

Is called by the AgentExecutorTask when a cancellation has been detected. Within this method the agent may perform any server-side reaction on cancellation.

Specified by:

doOnServerSideCancellation in interface SuperAgent<C extends ClientContext,S extends ServerContext>

isNoReturn

public boolean isNoReturn()

Description copied from interface: SuperAgent

Tells whether this async agent should never be returned to the sender within a NetMessage.

Specified by:

isNoReturn in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.setNoReturn(boolean)

setNoReturn

public void setNoReturn(boolean isNoReturn)

Description copied from interface: SuperAgent

Tells whether this async agent should never be returned to the sender within a NetMessage. The originating client will completely forget about this agent and thus will not be able to cancel it. Note that a no-return agents will not be cancelled even when the client goes off-line. Thus it will continue running on the server until it finishes normally or is stopped due to an async timeout.

Specified by:

setNoReturn in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.setMessageTimeout(int), SuperAgent.isNoReturn()

executeForResponse

public void executeForResponse()
                        throws java.lang.Exception

Description copied from interface: SuperAgent

This method is called on an asynchronous agent only, before it is returned within the NetResponse. After that the agent will be asynchronously executed and finally returned to the client in a NetMessage.

Note that by this way it is possible that an asynchronous agent, which is received in a response, already may have partial results. Further results will be received within a message after the asynchronous execution has finished.

Specified by:

executeForResponse in interface SuperAgent<C extends ClientContext,S extends ServerContext>

Throws:

java.lang.Exception

hasClientParam

public boolean hasClientParam(java.lang.String key)

Description copied from interface: SuperAgent

Checks whether an agent specific parameter exists in the client cache.

Specified by:

hasClientParam in interface SuperAgent<C extends ClientContext,S extends ServerContext>

clearClientParams

public void clearClientParams()

Description copied from interface: SuperAgent

Clears the parameters in the client cache that have been set by this agent.

Specified by:

clearClientParams in interface SuperAgent<C extends ClientContext,S extends ServerContext>

getClientParams

public java.util.Map getClientParams()

Description copied from interface: SuperAgent

Allows an async agent to store an Agent-specific parameter in a client cache. An agent or a sequence of agents can access such parameters when they have been received via message. The client cache is automatically cleared when the agent is done - no matter whether it was cancelled or normally finished.

Specified by:

getClientParams in interface SuperAgent<C extends ClientContext,S extends ServerContext>

putClientParam

public void putClientParam(java.lang.String key,
                  java.lang.Object value)

Putting a null value results in removing the key

Specified by:

putClientParam in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.getClientParams()

getClientParam

public <T> T getClientParam(java.lang.String key)

Description copied from interface: SuperAgent

Fetches an agent specific parameter from the client cache.

Specified by:

getClientParam in interface SuperAgent<C extends ClientContext,S extends ServerContext>

See Also:

SuperAgent.getClientParams()

sendForSilentExecution

public <A extends Agent<C,S>> A sendForSilentExecution()

Description copied from interface: Agent

Same as Agent.sendForExecution() just without throwing an Exception. The returned Agent should be manually checked if it contains an Exception.

Specified by:

sendForSilentExecution in interface Agent<C extends ClientContext,S extends ServerContext>

Overrides:

sendForSilentExecution in class AbstractAgent<C extends ClientContext,S extends ServerContext>

See Also:

Agent.sendForExecution(), Agent.sendForBooleanExecution()

getRenderIcon

public javax.swing.Icon getRenderIcon()

Specified by:

getRenderIcon in interface Renderable

getRenderText

public java.lang.String getRenderText()

Specified by:

getRenderText in interface Renderable

getRenderColor

public java.awt.Color getRenderColor()

Specified by:

getRenderColor in interface Renderable

toString

public ToString toString(ToString s)

Description copied from class: AbstractAgent

This method creates a single line debug output to display the most important properties of the agent

Specified by:

toString in interface Dumpable

Overrides:

toString in class AbstractAgent<C extends ClientContext,S extends ServerContext>

toDumpString

public DumpString toDumpString(DumpString s)

Description copied from class: AbstractAgent

This method creates a multi line debug output to display the full content of the agent.

Specified by:

toDumpString in interface Dumpable

Overrides:

toDumpString in class AbstractAgent<C extends ClientContext,S extends ServerContext>