de.esprit.netsuite.netdata.agent

## Interface SuperAgent<C extends ClientContext,S extends ServerContext>

- All Superinterfaces:
    Agent<C,S>, ClientObject<C>, java.lang.Cloneable, CrossPlatformObject<C,S>, DeepCloneable, Dumpable, Renderable, java.io.Serializable, ServerObject<S>, SimpleLogSupport, TimeMeasurable
  All Known Subinterfaces:
    LoginAgent<C,S>
  All Known Implementing Classes:
    ABOAccessInfoAgent, ABOCreateAgent, ABODeleteAgent, ABODropAgent, ABOFetchAgent, ABOFindAgent, ABOInfoAgent, ABOUpdateAgent, AbstractCommonAgent, AbstractDBAgent, AbstractGroupChangeAgent, AbstractInternalAgent, AbstractLockableAgent, AbstractLoginAgent, AbstractSequencedAgent, AbstractSuperAgent, AbstractTestAgent, AbstractTextViewAgent, AbstractUserChangeAgent, BatchTaskConfigSaveAgent, CancelBatchProcessAgent, ChangePasswordAgent, ChatMessageAgent, ClientCommandAgent, ClientInfoRequestAgent, ClientInfoUpdateAgent, ClientListAgent, ClientMessageAgent, CoClientConnectionListAgent, CoServerConnectionListAgent, CoServerExecuteAgent, CoServerFileTransferAgent, CoServerFileTransferCancelAgent, CoServerInfoAgent, CpuLoadConfigAgent, DataSourceListAgent, DBDeleteAgent, DBInsertAgent, DBLoadAgent, DBRehashAgent, DBSelectAgent, DBStoreAgent, DBUpdateAgent, DefaultLoginAgent, DefaultPasswordConfigAgent, EmailConfigAgent, EverBlockingSyncAgent, EverSleepingAsyncAgent, EverWorkingAsyncAgent, ExFileSetTransferAgent, ExFileTransferAgent, ExMixedFileTransferAgent, ExStreamDownloadAgent, FailingAgent, FileDeleteAgent, FileEditAgent, FileInfoAgent, FileListAgent, FileReadAgent, FileStoreAgent, FileStreamDownloadAgent, FileTransferAgent, GenerateLogMessagesAgent, GetRegisteredMessageTypesAgent, GetRunningRemoteTasksAgent, GroupCreateAgent, GroupDeleteAgent, GroupListAgent, GroupUpdateAgent, HeavyLoadAgent, HeavyLoggingAgent, JournalTaskDeregisterAgent, JournalTaskListAgent, LockAcquireAgent, LockDataSourcePoolAgent, LockFindAgent, LockInfoAgent, LockReleaseAgent, LockRetriggerAgent, LogConfigAgent, LogDirListAgent, LogFileListAgent, MemoryEatingAgent, MessageBurstAgent, NewLogfileAgent, NoOperationAgent, NoReturnAsyncAgent, PartialResultAsyncAgent, PartialResultSplitAgent, PartialResultSyncAgent, ProbeDataSourceAgent, ProcessConfigReadAgent, ProcessStartAgent, PurgeDirectoryAgent, ReadLogFileAgent, RegisterForProgressEventsAgent, RegisterMessageTypeAgent, RemoteTaskCancelAgent, RemoteTaskProgessSwitchAgent, RemoteTaskReleaseAgent, RemoteTaskRunStateFlagAgent, RemoteTasksInfoAgent, RemoteTaskStartAgent, ResetPasswordAgent, RoundTripAgent, SelectDataSourceAgent, SendServerMessageAgent, SequencedParamAgent, ServerActivityInfoAgent, ServerBatchTaskConfigListAgent, ServerLogMessageAgent, ServerLogTestAgent, ServerMemoryCleanupAgent, ServerParamsInfoAgent, ServerShutdownAgent, ServerStartupInfoAgent, ServerStatisticsInfoAgent, ServerStatisticsRefreshAgent, SetClientLogLevelAgent, TestServerExceptionAgent, ThreadPoolInfoAgent, TimeCompareAgent, TransfersRunningListAgent, UserCreateAgent, UserDeleteAgent, UserListAgent, UserUpdateAgent

      public interface SuperAgent<C extends ClientContext,S extends ServerContext>
      extends Agent<C,S>, Renderable

  This interface adds support for running an agent asynchronously on the server. If executed async the server will send the agent back to the client via a `NetMessage`. The client keeps a local copy of the `AgentId` in order to be able to cancel the agent any time.

  Note that besides a normal exception this agent may contain a RuntimeException that raised during asynchronous execution on the server. This error will automatically be handled by the clients message receiver.

  Author:
    Rainer Buesch

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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()` Processes the error contained in the agent that was received in a message.
    `void` | `doOnMessageReceived()` Is called on the client side when the agent has been received in a NetMessage and does not contain an error.
    `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
    `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)` Puts an agent specific parameter into client cache.
    `void` | `setAsync(boolean isAsync)` If this flag is set the agent is executed asynchroneosly on the server.
    `void` | `setCancelledBy(SessionId killerSessionId)` Sets the agent into the cancelled state.
    `void` | `setIgnoreMessageError(boolean isHandleError)` 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.
    `boolean` | `wasCancelled()` Tells whether this agent ever has been tried to be cancelled.

    - ### 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, sendForSilentExecution, 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, toDumpString, toString, 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`

    - ### Methods inherited from interface de.esprit.common.gui.Renderable

      `getRenderColor, getRenderIcon, getRenderText`

- - ### Method Detail

    - #### isAsync

          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.
      See Also:
        `setAsync(boolean)`

    - #### setAsync

          void setAsync(boolean isAsync)

      If this flag is set the agent is executed asynchroneosly on the server.
      See Also:
        `isAsync()`

    - #### getMessageTimeout

          int getMessageTimeout()

      Returns the async execution timeout

    - #### setMessageTimeout

          void setMessageTimeout(int seconds)

      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

      See Also:
        `ServerStartup.getAsyncAgentTimeout()`

    - #### doOnMessageReceived

          void doOnMessageReceived()
                                   throws java.lang.Exception

      Is called on the client side when the agent has been received in a NetMessage and does not contain an error.

      Note: This method runs client message receiver thread and thus should not perform any GUI updates. For GUI updates you should use `Agent.doFinallyOnClient()` instead.

      Throws:
        `java.lang.Exception`

    - #### doOnMessageError

          void doOnMessageError()

      Processes the error contained in the agent that was received in a message. Is never called when teh `setIgnoreMessageError(boolean)` flag is set.

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

    - #### isNoReturn

          boolean isNoReturn()

      Tells whether this async agent should never be returned to the sender within a NetMessage.
      See Also:
        `setNoReturn(boolean)`

    - #### setNoReturn

          void setNoReturn(boolean isNoReturn)

      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.
      See Also:
        `setMessageTimeout(int)`, `isNoReturn()`

    - #### executeForResponse

          void executeForResponse()
                                  throws java.lang.Exception

      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.

      Throws:
        `java.lang.Exception`

    - #### getClientParams

          java.util.Map getClientParams()

      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.

    - #### putClientParam

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

      Puts an agent specific parameter into client cache. Putting a null value removes the according key.
      See Also:
        `getClientParams()`

    - #### getClientParam

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

      Fetches an agent specific parameter from the client cache.
      See Also:
        `getClientParams()`

    - #### clearClientParams

          void clearClientParams()

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

    - #### hasClientParam

          boolean hasClientParam(java.lang.String key)

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

    - #### getKillerSessionId

          SessionId getKillerSessionId()

      Tells which foreign user has cancelled the agent

    - #### isTimedOut

          boolean isTimedOut()

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

    - #### isIgnoreMessageError

          boolean isIgnoreMessageError()

      Tells whether errors are being ignored by the client when the agent is received in a message.
      See Also:
        `setIgnoreMessageError(boolean)`

    - #### setIgnoreMessageError

          void setIgnoreMessageError(boolean isHandleError)

      Allows for suppressing automatic error handling. If set to true, then errors in an agent message will not be handled by the client.
      See Also:
        `isIgnoreMessageError()`

    - #### setCancelledBy

          void setCancelledBy(SessionId killerSessionId)

      Sets the agent into the cancelled state. The `AgentExecutorTask` may later on discover the cancellation and actually stop the execution.

    - #### wasCancelled

          boolean wasCancelled()

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

    - #### doOnServerSideCancellation

          void doOnServerSideCancellation()

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

    - #### doOnClientSideCancellation

          void doOnClientSideCancellation()

      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.

Copyright © 2012 EsprIT-Systems. All Rights Reserved.