de.esprit.netsuite.netdata.agent

## Class AbstractAgent<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>

- All Implemented Interfaces:
    TaskIdHolder, Renderable, SimpleLogSupport, DeepCloneable, Dumpable, ClientObject<C>, Agent<C,S>, AsyncAgent<C,S>, TimeMeasurable, CrossPlatformObject<C,S>, ServerObject<S>, java.io.Serializable, java.lang.Cloneable
  Direct Known Subclasses:
    AbstractInternalAgent, AbstractLockableAgent, AbstractLoginAgent, AbstractSequencedAgent, AssignPermissionsAgent, ClientInfoUpdateAgent, GetAssignedPermissionsAgent, GetPathFilterAgent, GetPermissionDefinitionsAgent, GetRootPathInfoAgent, JournalTaskDeregisterAgent, JournalTaskListAgent, LoadChildrenAgent, RegisterForProgressEventsAgent, RemoteTaskProgessSwitchAgent, RemoteTaskReleaseAgent, RemoteTaskRunStateFlagAgent, RemoteTaskStartAgent, RenamePathAgent, ResetPathWatcherAgent, ServerActivityInfoAgent, ServerStatisticsRefreshAgent, SetPathFilterAgent

      public abstract class AbstractAgent<C extends ClientContext,S extends ServerContext>
      extends AbstractCrossPlatformObject<C,S>
      implements AsyncAgent<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.

  The Agent's main work is done by the method `Agent.executeOnServer()` which must be overridden accordingly.
  In case of async execution you may also override `executeForResponse()` as well. This method is executed synchronously before async execution is started. In fact the client receives the agent twice - once in the response (having `executeForResponse()` executed) and a second time in a message having `Agent.executeOnServer()` executed.
  During async execution the agent should be reactive to cancellation. You achieve this by calling the method `checkCancelled()` in regular time frames.

  Author:
    Rainer Buesch
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractAgent(C clientCtx)`
    `AbstractAgent(C clientCtx, boolean isAsync)`
    `AbstractAgent(ClientConnector conn)`
    `AbstractAgent(ClientConnector conn, boolean isAsync)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkCancelled()` Throws a `CancellationException` when the agent was cancelled.
    `protected void` | `checkPermission(PermissionControlled obj, EspritPermission permission)` Checks whether the current user has permission on the given object for the given action.
    `void` | `clearClientParams()` Clears the parameters in the client cache that have been set by this agent.
    `protected AgentId` | `createAgentId(SessionId sessId)`
    `void` | `doFinallyOnClient()` This method is called on the client, after the agent has completely been processed.
    `void` | `doFinallyOnServer()` This method is called on the server, just before the agent is sent backt to the client.
    `void` | `doInitiallyOnClient()` Is executed just before the agent is being sent to the server.
    `void` | `doInitiallyOnServer()` This method is called on the server, when the agent is received by the server.
    `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` | `doOnResponseConfirmed()` Is called on an agent when it was received in a `NetResponse` AFTER the response has been confirmed to the server.
    `void` | `doOnResponseError()` Is called when the returned agent contains an error.
    `void` | `doOnResponseReceived()` Is called when the agent is received in a response.
    `void` | `doOnServerSideCancellation()` Is called by the `AgentExecutorTask` when a cancellation has been detected.
    `boolean` | `equals(java.lang.Object obj)` Evaluates equality by comparing the AgentId object.
    `void` | `executeForResponse()` This method is called on an asynchronous agent only, before it is returned within the NetResponse.
    `AgentId` | `getAgentId()` Returns a server side unique identifier.
    `java.lang.Object` | `getArgument()` Returns the optional argument of this agent.
    `<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.
    `java.lang.Exception` | `getError()` Returns the Exception that may have been raised during agent execution on the server.
    `SessionId` | `getKillerSessionId()` Tells which foreign user has cancelled the agent
    `int` | `getMessageTimeout()` Returns the async execution timeout
    `java.lang.String` | `getName()` Returns a meaningful name for debugging purposes.
    `SessionId` | `getOwnerSessionId()` Returns session id of the actual originator client (which cannot be a CoClient, but just a normal client)
    `int` | `getPriority()` Returns the thread priority which is used to execute this agent
    `long` | `getProcessingDuration()` Returns the time (in millis) it has taken to process the agent on server side.
    `long` | `getReceivedTime()` Tells when the agent was received by the client
    `java.awt.Color` | `getRenderColor()`
    `javax.swing.Icon` | `getRenderIcon()`
    `java.lang.String` | `getRenderText()`
    `int` | `getResponseTimeout()` Returns the desired timeout (in seconds) that should apply to this agent, or 0 if no timeout should be used.
    `long` | `getSentTime()` Tells when the agent was sent by the client
    `SessionId` | `getSessionId()` Returns the SessionId of the owner of this agent
    `java.lang.String` | `getTargetServer()` Returns the target server if one is set.
    `TaskId` | `getTaskId()` Returns the unique identifier for this task.
    `long` | `getTotalDuration()` Returns the time (in millis) it has taken from sending to finishing postprocessing of the agent.
    `long` | `getTransferDuration()` Returns the time (in millis) it has taken from sending to receiving the agent.
    `protected int` | `getZippedArgumentLength()`
    `boolean` | `hasClientParam(java.lang.String key)` Checks whether an agent specific parameter exists in the client cache.
    `boolean` | `hasError()` Tells whether the agent had an Exception during execution on server side.
    `int` | `hashCode()`
    `boolean` | `hasRun()` Tells whether this agent has been executed on the server.
    `boolean` | `isAsync()` Tells whether the agent should be executed asynchronously 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` | `isPartialResultsEnabled()` Tells whether the agent supports partial results.
    `boolean` | `isReceived()` Tells whether this agent yet has been received by the client.
    `boolean` | `isReceivedInMessage()` Returns true if the agent has been received within a message.
    `boolean` | `isReceivedInResponse()` Returns true if the agent has been received within a response.
    `boolean` | `isRejectable()` Tells whether this agent can be rejected when the server is on heavy load.
    `boolean` | `isTimedOut()` Tells whether the agent has been cancelled due to an async execution timeout on server side.
    `void` | `logDebug(java.lang.String message)`
    `void` | `logDump(java.lang.String message)`
    `void` | `logError(java.lang.String message)`
    `void` | `logError(java.lang.String message, java.lang.Exception error)`
    `void` | `logFatal(java.lang.String message, java.lang.Exception error)`
    `void` | `logInfo(java.lang.String message)`
    `void` | `logVerbose(java.lang.String message)`
    `void` | `logWarning(java.lang.String message)`
    `void` | `putClientParam(java.lang.String key, java.lang.Object value)` Putting a null value results in removing the key
    `boolean` | `sendForBooleanExecution()` Same as `Agent.sendForExecution()` but does not return the agent, rather it returns true if the agent has successfully being processed, false otherwise.
    `<A extends Agent<C,S>> A` | `sendForExecution()` Sends the agent to the server for execution and returns the readily processed agent.
    `<A extends Agent<C,S>> A` | `sendForSilentExecution()` Same as `Agent.sendForExecution()` just without throwing an Exception.
    `void` | `setArgument(java.lang.Object arg)` Besides any internal variables the agent may optionally carry an arbitrary argument.
    `void` | `setArgument(java.lang.Object arg, boolean doZip)` Same as setArgument(Object) but compresses the argument to a zipped byte array.
    `void` | `setAsync(boolean isAsync)` If this flag is set the agent is executed asynchronously on the server.
    `void` | `setCancelledBy(SessionId killerSessId)` Marks the agent to be cancelled without performing any further cancel action.
    `void` | `setFailed(java.lang.Exception error)` Sets the internal Exception of the Agent.
    `void` | `setFinished()` Is called by the server to mark this agent as being processed and stores the processing duration.
    `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` | `setName(java.lang.String agentName)` Sets a meaningful name for debugging purposes.
    `void` | `setNoReturn(boolean isNoReturn)` Tells whether this async agent should never be returned to the sender within a NetMessage.
    `void` | `setOwnerSessionId(SessionId ownerSessId)` Sets the sessionId of the user who creates the agent
    `void` | `setPartialResultsEnabled(boolean isEnabled)` Tells whether the agent supports partial results.
    `void` | `setPriority(int priority)` Sets the thread priority which is used to execute this agent
    `void` | `setReceivedInMessage(boolean isReceivedInMessage)` Is set when this agent has been received within a message
    `void` | `setReceivedTime(long receivedTime)` Is called by the client when the agent is received
    `void` | `setRejectable(boolean state)` If set to false, then the agent cannot be rejected by the server even if the server is on heavy load.
    `void` | `setResponseTimeout(int seconds)` Sets the response timeout in seconds.
    `void` | `setSentTime(long sentTime)` Is called by the client when the agent is sent
    `void` | `setServerContext(S serverCtx)` Sets the server runtime environment
    `void` | `setSessionId(SessionId sessId)` Allows for setting the SessionId of this agent
    `void` | `setTargetServer(java.lang.String targetServer)` Sets the target server.
    `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.AbstractCrossPlatformObject

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

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

      `clone, deepClone`

    - ### 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

      `clearClientParams, executeOnServer, getAgentId, getArgument, getClientParam, getClientParams, getError, getName, getOwnerSessionId, getPriority, getResponseTimeout, getSessionId, getTargetServer, hasClientParam, hasError, hasRun, isPartialResultsEnabled, isReceived, isReceivedInMessage, isReceivedInResponse, isRejectable, putClientParam, sendForBooleanExecution, sendForExecution, sendForSilentExecution, setArgument, setArgument, setFailed, setFinished, 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

      `deepClone`

    - ### 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

    - #### AbstractAgent

          public AbstractAgent(C clientCtx)

    - #### AbstractAgent

          public AbstractAgent(C clientCtx,
                       boolean isAsync)

    - #### AbstractAgent

          public AbstractAgent(ClientConnector conn)

    - #### AbstractAgent

          public AbstractAgent(ClientConnector conn,
                       boolean isAsync)

  - ### Method Detail

    - #### checkPermission

          protected final void checkPermission(PermissionControlled obj,
                             EspritPermission permission)
                                        throws PermissionException

      Checks whether the current user has permission on the given object for the given action.
      Throws:
        `PermissionException`

    - #### isIgnoreMessageError

          public final boolean isIgnoreMessageError()

      Description copied from interface: `AsyncAgent`
      Tells whether errors are being ignored by the client when the agent is received in a message.
      Specified by:
        `isIgnoreMessageError` in interface `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `AsyncAgent.setIgnoreMessageError(boolean)`

    - #### setIgnoreMessageError

          public final void setIgnoreMessageError(boolean isIgnoreError)

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `AsyncAgent.isIgnoreMessageError()`

    - #### getMessageTimeout

          public final int getMessageTimeout()

      Description copied from interface: `AsyncAgent`
      Returns the async execution timeout
      Specified by:
        `getMessageTimeout` in interface `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### setMessageTimeout

          public final void setMessageTimeout(int seconds)

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `ServerStartup.getDefaultAsyncAgentTimeout()`

    - #### isTimedOut

          public final boolean isTimedOut()

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### isAsync

          public final boolean isAsync()

      Description copied from interface: `AsyncAgent`
      Tells whether the agent should be executed asynchronously on the server in which case it is sent back to the client via a NetMessage.
      Specified by:
        `isAsync` in interface `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `AsyncAgent.setAsync(boolean)`

    - #### setAsync

          public final void setAsync(boolean isAsync)

      Description copied from interface: `AsyncAgent`
      If this flag is set the agent is executed asynchronously on the server.
      Specified by:
        `setAsync` in interface `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `AsyncAgent.isAsync()`

    - #### doInitiallyOnClient

          public void doInitiallyOnClient()
                                   throws java.lang.Exception

      Description copied from interface: `Agent`
      Is executed just before the agent is being sent to the server.
      Specified by:
        `doInitiallyOnClient` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### 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 `AsyncAgent<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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### doInitiallyOnServer

          public void doInitiallyOnServer()
                                   throws java.lang.Exception

      Description copied from interface: `Agent`
      This method is called on the server, when the agent is received by the server. If it fails, then the client will receive a request error.
      Specified by:
        `doInitiallyOnServer` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### doFinallyOnServer

          public void doFinallyOnServer()
                                 throws java.lang.Exception

      Description copied from interface: `Agent`
      This method is called on the server, just before the agent is sent backt to the client. On a sync agent this method is called before the agent is sent back in a response. On a async agent this method is called before the agent is sent back in a message.
      Specified by:
        `doFinallyOnServer` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### doFinallyOnClient

          public void doFinallyOnClient()
                                 throws java.lang.Exception

      Description copied from interface: `Agent`
      This method is called on the client, after the agent has completely been processed. On a sync agent this method is called when the agent was received in a response. On a async agent this method is called when the agent was received in a message.

      Note: If the client has got a GUI, this method runs in the EventDispatcher Thread.

      Specified by:
        `doFinallyOnClient` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### doOnResponseReceived

          public void doOnResponseReceived()
                                    throws java.lang.Exception

      Is called when the agent is received in a response. The default implementation is empty
      Specified by:
        `doOnResponseReceived` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### doOnResponseConfirmed

          public void doOnResponseConfirmed()
                                     throws java.lang.Exception

      Description copied from interface: `Agent`
      Is called on an agent when it was received in a `NetResponse` AFTER the response has been confirmed to the server.
      Specified by:
        `doOnResponseConfirmed` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### doOnResponseError

          public void doOnResponseError()

      Is called when the returned agent contains an error. The default implementation is empty.
      Specified by:
        `doOnResponseError` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### doOnClientSideCancellation

          public void doOnClientSideCancellation()

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### doOnServerSideCancellation

          public void doOnServerSideCancellation()

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### executeForResponse

          public void executeForResponse()
                                  throws java.lang.Exception

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception`

    - #### sleepChecked

          public final 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: `AsyncAgent`
      Tells whether this agent ever has been tried to be cancelled.
      Specified by:
        `wasCancelled` in interface `AsyncAgent<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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### getKillerSessionId

          public final SessionId getKillerSessionId()

      Description copied from interface: `AsyncAgent`
      Tells which foreign user has cancelled the agent
      Specified by:
        `getKillerSessionId` in interface `AsyncAgent<C extends ClientContext,S extends ServerContext>`

    - #### isNoReturn

          public final boolean isNoReturn()

      Description copied from interface: `AsyncAgent`
      Tells whether this async agent should never be returned to the sender within a NetMessage.
      Specified by:
        `isNoReturn` in interface `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `AsyncAgent.setNoReturn(boolean)`

    - #### setNoReturn

          public final void setNoReturn(boolean isNoReturn)

      Description copied from interface: `AsyncAgent`
      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 `AsyncAgent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `AsyncAgent.setMessageTimeout(int)`, `AsyncAgent.isNoReturn()`

    - #### 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)

      This method creates a single line debug output to display the most important properties of the agent
      Specified by:
        `toString` in interface `Dumpable`

    - #### toDumpString

          public DumpString toDumpString(DumpString s)

      This method creates a multi line debug output to display the full content of the agent.
      Specified by:
        `toDumpString` in interface `Dumpable`

    - #### createAgentId

          protected AgentId createAgentId(SessionId sessId)

    - #### getClientParams

          public final java.util.Map getClientParams()

      Description copied from interface: `Agent`
      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 `Agent<C extends ClientContext,S extends ServerContext>`

    - #### putClientParam

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

      Putting a null value results in removing the key
      Specified by:
        `putClientParam` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getClientParams()`

    - #### getClientParam

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

      Description copied from interface: `Agent`
      Fetches an agent specific parameter from the client cache.
      Specified by:
        `getClientParam` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getClientParams()`

    - #### hasClientParam

          public final boolean hasClientParam(java.lang.String key)

      Description copied from interface: `Agent`
      Checks whether an agent specific parameter exists in the client cache.
      Specified by:
        `hasClientParam` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### clearClientParams

          public final void clearClientParams()

      Description copied from interface: `Agent`
      Clears the parameters in the client cache that have been set by this agent.
      Specified by:
        `clearClientParams` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Evaluates equality by comparing the AgentId object.
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### getAgentId

          public AgentId getAgentId()

      Description copied from interface: `Agent`
      Returns a server side unique identifier. Note that a client remembers this identifier which is used to cancel an asynchronously running agent.
      Specified by:
        `getAgentId` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getTaskId

          public final TaskId getTaskId()

      Description copied from interface: `TaskIdHolder`
      Returns the unique identifier for this task. This identifier is only valid for a single task execution. When the same task instance executes another time then it will have a new `TaskId`.
      Specified by:
        `getTaskId` in interface `TaskIdHolder`

    - #### getSessionId

          public final SessionId getSessionId()

      Returns the SessionId of the owner of this agent
      Specified by:
        `getSessionId` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.setSessionId(SessionId)`, `Agent.getOwnerSessionId()`

    - #### setSessionId

          public final void setSessionId(SessionId sessId)

      Description copied from interface: `Agent`
      Allows for setting the SessionId of this agent
      Specified by:
        `setSessionId` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getSessionId()`

    - #### setServerContext

          public final void setServerContext(S serverCtx)

      Description copied from interface: `CrossPlatformObject`
      Sets the server runtime environment
      Specified by:
        `setServerContext` in interface `CrossPlatformObject<C extends ClientContext,S extends ServerContext>`
      Overrides:
        `setServerContext` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`
      See Also:
        `ServerObject.getServerContext()`

    - #### isPartialResultsEnabled

          public final boolean isPartialResultsEnabled()

      Description copied from interface: `Agent`
      Tells whether the agent supports partial results. If set to true then agent postprocessing takes place even if the agent contains an error.
      Specified by:
        `isPartialResultsEnabled` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.setPartialResultsEnabled(boolean)`

    - #### setPartialResultsEnabled

          public final void setPartialResultsEnabled(boolean isEnabled)

      Description copied from interface: `Agent`
      Tells whether the agent supports partial results. If set to true then agent postprocessing takes place even if the agent contains an error.
      Specified by:
        `setPartialResultsEnabled` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.isPartialResultsEnabled()`

    - #### setRejectable

          public final void setRejectable(boolean state)

      Description copied from interface: `Agent`
      If set to false, then the agent cannot be rejected by the server even if the server is on heavy load. Is true by default. This feature should be used sparingly because it may lead to overloading the server. A normal rejectable agent is put into the AgentWorkerThreadPool which has a limited capacity. A non-rejectable agent is put into the AgentSleeperThreadPool which as unlimited capacity.
      Specified by:
        `setRejectable` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### isRejectable

          public final boolean isRejectable()

      Description copied from interface: `Agent`
      Tells whether this agent can be rejected when the server is on heavy load.
      Specified by:
        `isRejectable` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getOwnerSessionId

          public final SessionId getOwnerSessionId()

      Returns session id of the actual originator client (which cannot be a CoClient, but just a normal client)
      Specified by:
        `getOwnerSessionId` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### setOwnerSessionId

          public void setOwnerSessionId(SessionId ownerSessId)

      Description copied from interface: `Agent`
      Sets the sessionId of the user who creates the agent
      Specified by:
        `setOwnerSessionId` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getTargetServer

          public final java.lang.String getTargetServer()

      Description copied from interface: `Agent`
      Returns the target server if one is set.
      Specified by:
        `getTargetServer` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.setTargetServer(String)`

    - #### setTargetServer

          public final void setTargetServer(java.lang.String targetServer)

      Description copied from interface: `Agent`
      Sets the target server. The target server may be any server in a cascading server network. The agent is being routed to the target server for execution.

      Note that target server routing is not supported for async agents.

      Specified by:
        `setTargetServer` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getTargetServer()`

    - #### setName

          public void setName(java.lang.String agentName)

      Description copied from interface: `Agent`
      Sets a meaningful name for debugging purposes. This name is printed in the toString() method by default. The default name is the latter part of the class-name.
      Specified by:
        `setName` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getName

          public final java.lang.String getName()

      Description copied from interface: `Agent`
      Returns a meaningful name for debugging purposes. This name is printed in the toString() method by default.
      Specified by:
        `getName` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### setResponseTimeout

          public final void setResponseTimeout(int seconds)

      Sets the response timeout in seconds. A zero value indicates that the DEFAULT_REQUEST_TIMEOUT is being used. A negative value indicates that there is no timeout constraint.
      Specified by:
        `setResponseTimeout` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getResponseTimeout()`

    - #### getResponseTimeout

          public final int getResponseTimeout()

      Description copied from interface: `Agent`
      Returns the desired timeout (in seconds) that should apply to this agent, or 0 if no timeout should be used.
      Specified by:
        `getResponseTimeout` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.setResponseTimeout(int)`

    - #### hasRun

          public final boolean hasRun()

      Description copied from interface: `Agent`
      Tells whether this agent has been executed on the server. After execution it contains either an error or a valid result if applicable.
      Specified by:
        `hasRun` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.hasError()`

    - #### hasError

          public final boolean hasError()

      Description copied from interface: `Agent`
      Tells whether the agent had an Exception during execution on server side.
      Specified by:
        `hasError` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getError()`

    - #### getError

          public final java.lang.Exception getError()

      Description copied from interface: `Agent`
      Returns the Exception that may have been raised during agent execution on the server. You must check with `Agent.hasError()` whether an Exception exists in the agent.
      Specified by:
        `getError` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.setFailed(Exception)`, `Agent.hasError()`

    - #### setFinished

          public final void setFinished()

      Description copied from interface: `Agent`
      Is called by the server to mark this agent as being processed and stores the processing duration. After this method has been called the agent is returned to the client.
      Specified by:
        `setFinished` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `CrossPlatformObject.setServerContext(ServerContext ctx)`

    - #### setFailed

          public final void setFailed(java.lang.Exception error)

      Description copied from interface: `Agent`
      Sets the internal Exception of the Agent. This Exception is set if agent processing failed on the server.
      Specified by:
        `setFailed` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.getError()`, `Agent.hasError()`

    - #### isReceivedInResponse

          public final boolean isReceivedInResponse()

      Description copied from interface: `Agent`
      Returns true if the agent has been received within a response.
      Specified by:
        `isReceivedInResponse` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### isReceivedInMessage

          public final boolean isReceivedInMessage()

      Description copied from interface: `Agent`
      Returns true if the agent has been received within a message. This is only possible for async agents.
      Specified by:
        `isReceivedInMessage` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.setReceivedInMessage(boolean)`

    - #### setReceivedInMessage

          public final void setReceivedInMessage(boolean isReceivedInMessage)

      Description copied from interface: `Agent`
      Is set when this agent has been received within a message
      Specified by:
        `setReceivedInMessage` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      See Also:
        `Agent.isReceivedInMessage()`

    - #### getPriority

          public final int getPriority()

      Description copied from interface: `Agent`
      Returns the thread priority which is used to execute this agent
      Specified by:
        `getPriority` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### setPriority

          public final void setPriority(int priority)

      Description copied from interface: `Agent`
      Sets the thread priority which is used to execute this agent
      Specified by:
        `setPriority` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### setSentTime

          public final void setSentTime(long sentTime)

      Description copied from interface: `TimeMeasurable`
      Is called by the client when the agent is sent
      Specified by:
        `setSentTime` in interface `TimeMeasurable`

    - #### getSentTime

          public final long getSentTime()

      Description copied from interface: `TimeMeasurable`
      Tells when the agent was sent by the client
      Specified by:
        `getSentTime` in interface `TimeMeasurable`

    - #### setReceivedTime

          public final void setReceivedTime(long receivedTime)

      Description copied from interface: `TimeMeasurable`
      Is called by the client when the agent is received
      Specified by:
        `setReceivedTime` in interface `TimeMeasurable`

    - #### getReceivedTime

          public final long getReceivedTime()

      Description copied from interface: `TimeMeasurable`
      Tells when the agent was received by the client
      Specified by:
        `getReceivedTime` in interface `TimeMeasurable`

    - #### isReceived

          public final boolean isReceived()

      Description copied from interface: `Agent`
      Tells whether this agent yet has been received by the client.
      Specified by:
        `isReceived` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getProcessingDuration

          public final long getProcessingDuration()

      Description copied from interface: `TimeMeasurable`
      Returns the time (in millis) it has taken to process the agent on server side.
      Specified by:
        `getProcessingDuration` in interface `TimeMeasurable`

    - #### getTotalDuration

          public final long getTotalDuration()

      Description copied from interface: `TimeMeasurable`
      Returns the time (in millis) it has taken from sending to finishing postprocessing of the agent.
      Specified by:
        `getTotalDuration` in interface `TimeMeasurable`

    - #### getTransferDuration

          public final long getTransferDuration()

      Description copied from interface: `TimeMeasurable`
      Returns the time (in millis) it has taken from sending to receiving the agent.
      Specified by:
        `getTransferDuration` in interface `TimeMeasurable`

    - #### setArgument

          public final void setArgument(java.lang.Object arg,
                         boolean doZip)

      Description copied from interface: `Agent`
      Same as setArgument(Object) but compresses the argument to a zipped byte array.
      Specified by:
        `setArgument` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### setArgument

          public final void setArgument(java.lang.Object arg)

      Description copied from interface: `Agent`
      Besides any internal variables the agent may optionally carry an arbitrary argument.
      Specified by:
        `setArgument` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getArgument

          public final java.lang.Object getArgument()

      Description copied from interface: `Agent`
      Returns the optional argument of this agent. Note that if the argument was zipped it is being unzipped automatically before it is returned.
      Specified by:
        `getArgument` in interface `Agent<C extends ClientContext,S extends ServerContext>`

    - #### getZippedArgumentLength

          protected final int getZippedArgumentLength()

    - #### sendForExecution

          public <A extends Agent<C,S>> A sendForExecution()
                                           throws java.lang.Exception

      Description copied from interface: `Agent`
      Sends the agent to the server for execution and returns the readily processed agent. If the received agent contains an error this error is thrown.
      Specified by:
        `sendForExecution` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Throws:
        `java.lang.Exception` - on failure
      See Also:
        `Agent.sendForSilentExecution()`, `Agent.sendForBooleanExecution()`

    - #### sendForSilentExecution

          public final <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>`
      See Also:
        `Agent.sendForExecution()`, `Agent.sendForBooleanExecution()`

    - #### sendForBooleanExecution

          public final boolean sendForBooleanExecution()

      Description copied from interface: `Agent`
      Same as `Agent.sendForExecution()` but does not return the agent, rather it returns true if the agent has successfully being processed, false otherwise. In the case of agent processing failure the error Exception is stored in the original input agent and can be requested from there.
      Specified by:
        `sendForBooleanExecution` in interface `Agent<C extends ClientContext,S extends ServerContext>`
      Returns:
        true if the agent succeeded, false if the agent failed.
      See Also:
        `Agent.sendForExecution()`, `Agent.sendForSilentExecution()`

    - #### logFatal

          public final void logFatal(java.lang.String message,
                      java.lang.Exception error)

      Specified by:
        `logFatal` in interface `SimpleLogSupport`
      Overrides:
        `logFatal` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logError

          public final void logError(java.lang.String message,
                      java.lang.Exception error)

      Specified by:
        `logError` in interface `SimpleLogSupport`
      Overrides:
        `logError` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logError

          public final void logError(java.lang.String message)

      Specified by:
        `logError` in interface `SimpleLogSupport`
      Overrides:
        `logError` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logWarning

          public final void logWarning(java.lang.String message)

      Specified by:
        `logWarning` in interface `SimpleLogSupport`
      Overrides:
        `logWarning` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logInfo

          public final void logInfo(java.lang.String message)

      Specified by:
        `logInfo` in interface `SimpleLogSupport`
      Overrides:
        `logInfo` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logVerbose

          public final void logVerbose(java.lang.String message)

      Specified by:
        `logVerbose` in interface `SimpleLogSupport`
      Overrides:
        `logVerbose` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logDebug

          public final void logDebug(java.lang.String message)

      Specified by:
        `logDebug` in interface `SimpleLogSupport`
      Overrides:
        `logDebug` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

    - #### logDump

          public final void logDump(java.lang.String message)

      Specified by:
        `logDump` in interface `SimpleLogSupport`
      Overrides:
        `logDump` in class `AbstractCrossPlatformObject<C extends ClientContext,S extends ServerContext>`

Copyright © 2014 EsprIT-Systems. All Rights Reserved.