de.esprit.netsuite.netdata.agent

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

- All Superinterfaces:
    ClientObject<C>, java.lang.Cloneable, CrossPlatformObject<C,S>, DeepCloneable, Dumpable, java.io.Serializable, ServerObject<S>, SimpleLogSupport, TimeMeasurable
  All Known Subinterfaces:
    AsyncAgent<C,S>, LoginAgent<C,S>
  All Known Implementing Classes:
    ABOAccessInfoAgent, ABOCreateAgent, ABODeleteAgent, ABODropAgent, ABOFetchAgent, ABOFindAgent, ABOInfoAgent, ABOUpdateAgent, AbstractAgent, AbstractCommonAgent, AbstractDBAgent, AbstractGroupChangeAgent, AbstractInternalAgent, AbstractLockableAgent, AbstractLoginAgent, AbstractSequencedAgent, AbstractSessionChangeAgent, AbstractTestAgent, AbstractTextViewAgent, AbstractUserChangeAgent, AssignPermissionsAgent, BatchTaskConfigListAgent, BatchTaskConfigSaveAgent, CancelBatchProcessAgent, ChangePasswordAgent, ChatMessageAgent, ClientCommandAgent, ClientInfoUpdateAgent, ClientMessageAgent, CoClientConnectionListAgent, CoServerConnectionListAgent, CoServerExecuteAgent, CoServerFileTransferAgent, CoServerFileTransferCancelAgent, CoServerInfoAgent, CpuLoadConfigAgent, DataSourceListAgent, DBDeleteAgent, DBInsertAgent, DBLoadAgent, DBRehashAgent, DBSelectAgent, DBStoreAgent, DBUpdateAgent, DefaultLoginAgent, DefaultPasswordConfigAgent, DeleteDirectoryAgent, DeleteFileAgent, EmailConfigAgent, EventMessageTypeInfoAgent, EventMessageTypeRegisterAgent, EverBlockingSyncAgent, EverSleepingAsyncAgent, EverWorkingAsyncAgent, ExFileSetTransferAgent, ExFileTransferAgent, ExMixedFileTransferAgent, ExStreamDownloadAgent, FailingAgent, FileEditAgent, FileInfoAgent, FileListAgent, FileReadAgent, FileStoreAgent, FileStreamDownloadAgent, FileTransferAgent, GenerateLogMessagesAgent, GetAssignedPermissionsAgent, GetGroupsAgent, GetGroupsOfUserAgent, GetPathFilterAgent, GetPermissionDefinitionsAgent, GetRootPathInfoAgent, GetRunningRemoteTasksAgent, GetSessionsAgent, GetUserIdsAgent, GetUsersAgent, GetUsersOfGroupAgent, GroupCreateAgent, GroupDeleteAgent, GroupUpdateAgent, HeavyLoadAgent, HeavyLoggingAgent, JournalTaskDeregisterAgent, JournalTaskListAgent, LoadChildrenAgent, LoadTextFileSequencedAgent, LockAcquireAgent, LockDataSourcePoolAgent, LockFindAgent, LockInfoAgent, LockReleaseAgent, LockRetriggerAgent, LogConfigAgent, LogDirListAgent, LogFileListAgent, MemoryEatingAgent, MessageBurstAgent, MessageBurstSequencedAgent, NewLogFileAgent, NoOperationAgent, NoReturnAsyncAgent, PartialResultAsyncAgent, PartialResultSplitAgent, PartialResultSyncAgent, ProbeDataSourceAgent, ProcessConfigReadAgent, ProcessStartAgent, PurgeDirectoryAgent, ReadLogFileAgent, RegisterForProgressEventsAgent, RemoteTaskCancelAgent, RemoteTaskProgessSwitchAgent, RemoteTaskReleaseAgent, RemoteTaskRunStateFlagAgent, RemoteTasksInfoAgent, RemoteTaskStartAgent, RenamePathAgent, ResetPasswordAgent, ResetPathWatcherAgent, RoundTripAgent, SelectDataSourceAgent, SendServerMessageAgent, SequencedParamAgent, ServerActivityInfoAgent, ServerLogMessageAgent, ServerLogTestAgent, ServerMemoryCleanupAgent, ServerParamsInfoAgent, ServerShutdownAgent, ServerStartupInfoAgent, ServerStatisticsInfoAgent, ServerStatisticsRefreshAgent, SessionInfoAgent, SessionKillAgent, SessionResetAgent, SetClientLogLevelAgent, SetGroupMembersAgent, SetPathFilterAgent, TestServerExceptionAgent, ThreadPoolInfoAgent, TimeCompareAgent, TransfersRunningListAgent, UserCreateAgent, UserDeleteAgent, UserUpdateAgent

      public interface Agent<C extends ClientContext,S extends ServerContext>
      extends CrossPlatformObject<C,S>, TimeMeasurable, SimpleLogSupport

  An Agent object is being sent within a `NetRequest` to the server for execution by calling one of its send... methods. The Agent must contain everything that is needed for execution on server side (i.e. processing arguments). The server processes it and sends it back to the client within the `NetResponse`.

  The client checks the received agent for error. If it contains any, the error is handled by the client's `AgentErrorAdapter`. Otherwise the agent is postprocessed by calling it's `doOnResponseReceived()` method.

  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` | `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` | `doOnResponseConfirmed()` Is called on an agent when it was received in a `NetResponse` AFTER the response has been confirmed to the server.
    `void` | `doOnResponseError()` Processes the error contained in the agent received in a response.
    `void` | `doOnResponseReceived()` Is called on an agent when it was received in a `NetResponse` but yet BEFORE the response was confirmed to the server.
    `void` | `executeOnServer()` This is the agent's main execution method called on the server.
    `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.
    `java.lang.String` | `getName()` Returns a meaningful name for debugging purposes.
    `SessionId` | `getOwnerSessionId()` Return the SessionId of the actual originator client which is always a normal client (NOT a CoClient).
    `int` | `getPriority()` Returns the thread priority which is used to execute this agent
    `int` | `getResponseTimeout()` Returns the desired timeout (in seconds) that should apply to this agent, or 0 if no timeout should be used.
    `SessionId` | `getSessionId()` Returns the SessionId of the sender of this agent.
    `java.lang.String` | `getTargetServer()` Returns the target server if one is set.
    `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.
    `boolean` | `hasRun()` Tells whether this agent has been executed on the server.
    `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.
    `void` | `putClientParam(java.lang.String key, java.lang.Object value)` Puts an agent specific parameter into client cache.
    `boolean` | `sendForBooleanExecution()` Same as `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 `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 isZip)` Same as setArgument(Object) but compresses the argument to a zipped byte array.
    `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` | `setName(java.lang.String agentName)` Sets a meaningful name for debugging purposes.
    `void` | `setOwnerSessionId(SessionId origSessId)` 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 state)` Is set when this agent has been received within a message
    `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) that should apply to this agent.
    `void` | `setSessionId(SessionId sessId)` Allows for setting the SessionId of this agent
    `void` | `setTargetServer(java.lang.String targetServer)` Sets the target server.

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

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

- - ### Method Detail

    - #### getSessionId

          SessionId getSessionId()

      Returns the SessionId of the sender of this agent. Note that the sender may be a normal client or a co-client
      See Also:
        `setSessionId(SessionId)`, `getOwnerSessionId()`

    - #### setSessionId

          void setSessionId(SessionId sessId)

      Allows for setting the SessionId of this agent
      See Also:
        `getSessionId()`

    - #### getAgentId

          AgentId getAgentId()

      Returns a server side unique identifier. Note that a client remembers this identifier which is used to cancel an asynchronously running agent.

    - #### setArgument

          void setArgument(java.lang.Object arg)

      Besides any internal variables the agent may optionally carry an arbitrary argument.

    - #### setArgument

          void setArgument(java.lang.Object arg,
                         boolean isZip)

      Same as setArgument(Object) but compresses the argument to a zipped byte array.

    - #### getArgument

          java.lang.Object getArgument()

      Returns the optional argument of this agent. Note that if the argument was zipped it is being unzipped automatically before it is returned.

    - #### getName

          java.lang.String getName()

      Returns a meaningful name for debugging purposes. This name is printed in the toString() method by default.

    - #### setName

          void setName(java.lang.String agentName)

      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.

    - #### getResponseTimeout

          int getResponseTimeout()

      Returns the desired timeout (in seconds) that should apply to this agent, or 0 if no timeout should be used.
      See Also:
        `setResponseTimeout(int)`

    - #### setResponseTimeout

          void setResponseTimeout(int seconds)

      Sets the response timeout (in seconds) that should apply to this agent. If processing on the server would take longer than this timeout, the the client will receive a server timeout error. Note: setting the response timeout to zero actually sets the default response timeout, which is about 15 seconds.
      See Also:
        `getResponseTimeout()`

    - #### doInitiallyOnClient

          void doInitiallyOnClient()
                                   throws java.lang.Exception

      Is executed just before the agent is being sent to the server.
      Throws:
        `java.lang.Exception`

    - #### doFinallyOnClient

          void doFinallyOnClient()
                                 throws java.lang.Exception

      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.

      Throws:
        `java.lang.Exception`

    - #### doInitiallyOnServer

          void doInitiallyOnServer()
                                   throws java.lang.Exception

      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.
      Throws:
        `java.lang.Exception`

    - #### doFinallyOnServer

          void doFinallyOnServer()
                                 throws java.lang.Exception

      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.
      Throws:
        `java.lang.Exception`

    - #### doOnResponseReceived

          void doOnResponseReceived()
                                    throws java.lang.Exception

      Is called on an agent when it was received in a `NetResponse` but yet BEFORE the response was confirmed to the server.
      Throws:
        `java.lang.Exception`

    - #### doOnResponseConfirmed

          void doOnResponseConfirmed()
                                     throws java.lang.Exception

      Is called on an agent when it was received in a `NetResponse` AFTER the response has been confirmed to the server.
      Throws:
        `java.lang.Exception`

    - #### doOnResponseError

          void doOnResponseError()

      Processes the error contained in the agent received in a response.

    - #### executeOnServer

          void executeOnServer()
                               throws java.lang.Exception

      This is the agent's main execution method called on the server.
      Throws:
        `java.lang.Exception`

    - #### setFinished

          void setFinished()

      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.
      See Also:
        `CrossPlatformObject.setServerContext(ServerContext ctx)`

    - #### hasRun

          boolean hasRun()

      Tells whether this agent has been executed on the server. After execution it contains either an error or a valid result if applicable.
      See Also:
        `hasError()`

    - #### isReceived

          boolean isReceived()

      Tells whether this agent yet has been received by the client.

    - #### isReceivedInResponse

          boolean isReceivedInResponse()

      Returns true if the agent has been received within a response.

    - #### isReceivedInMessage

          boolean isReceivedInMessage()

      Returns true if the agent has been received within a message. This is only possible for async agents.
      See Also:
        `setReceivedInMessage(boolean)`

    - #### setReceivedInMessage

          void setReceivedInMessage(boolean state)

      Is set when this agent has been received within a message
      See Also:
        `isReceivedInMessage()`

    - #### isPartialResultsEnabled

          boolean isPartialResultsEnabled()

      Tells whether the agent supports partial results. If set to true then agent postprocessing takes place even if the agent contains an error.
      See Also:
        `setPartialResultsEnabled(boolean)`

    - #### setPartialResultsEnabled

          void setPartialResultsEnabled(boolean isEnabled)

      Tells whether the agent supports partial results. If set to true then agent postprocessing takes place even if the agent contains an error.
      See Also:
        `isPartialResultsEnabled()`

    - #### hasError

          boolean hasError()

      Tells whether the agent had an Exception during execution on server side.
      See Also:
        `getError()`

    - #### getError

          java.lang.Exception getError()

      Returns the Exception that may have been raised during agent execution on the server. You must check with `hasError()` whether an Exception exists in the agent.
      See Also:
        `setFailed(Exception)`, `hasError()`

    - #### getPriority

          int getPriority()

      Returns the thread priority which is used to execute this agent

    - #### setPriority

          void setPriority(int priority)

      Sets the thread priority which is used to execute this agent

    - #### setFailed

          void setFailed(java.lang.Exception error)

      Sets the internal Exception of the Agent. This Exception is set if agent processing failed on the server.
      See Also:
        `getError()`, `hasError()`

    - #### sendForExecution

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

      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.
      Throws:
        `java.lang.Exception` - on failure
      See Also:
        `sendForSilentExecution()`, `sendForBooleanExecution()`

    - #### sendForSilentExecution

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

      Same as `sendForExecution()` just without throwing an Exception. The returned Agent should be manually checked if it contains an Exception.
      See Also:
        `sendForExecution()`, `sendForBooleanExecution()`

    - #### sendForBooleanExecution

          boolean sendForBooleanExecution()

      Same as `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.
      Returns:
        true if the agent succeeded, false if the agent failed.
      See Also:
        `sendForExecution()`, `sendForSilentExecution()`

    - #### getTargetServer

          java.lang.String getTargetServer()

      Returns the target server if one is set.
      See Also:
        `setTargetServer(String)`

    - #### setTargetServer

          void setTargetServer(java.lang.String targetServer)

      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.

      See Also:
        `getTargetServer()`

    - #### getOwnerSessionId

          SessionId getOwnerSessionId()

      Return the SessionId of the actual originator client which is always a normal client (NOT a CoClient). This SessionId is passed from the real originator client through all co-clients to the target co-server.

    - #### setOwnerSessionId

          void setOwnerSessionId(SessionId origSessId)

      Sets the sessionId of the user who creates the agent

    - #### setRejectable

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

    - #### isRejectable

          boolean isRejectable()

      Tells whether this agent can be rejected when the server is on heavy load.

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

Copyright © 2014 EsprIT-Systems. All Rights Reserved.