Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.ifs.agents.common
Class IfsAgent

    java.lang.Object

      |

      +--oracle.ifs.common.BaseMain

            |

            +--oracle.ifs.common.BaseApp

                  |

                  +--oracle.ifs.agents.common.IfsAgent

All Implemented Interfaces:
  Agent, java.lang.Runnable

public abstract class IfsAgent
extends oracle.ifs.common.BaseApp
implements Agent

An IfsAgent is an abstract class that acts as a base class for all iFS agents.

IfsAgent implements the Agent interface, which is a required by ServerManager who manages the running of the agent. This class simplifies agent writing by reducing the number of methods that need to be implemented, and by hiding the threading considerations that are involved.

A class that extends IfsAgent will normally need to override the following methods that are declared by IfsAgent (using the same constructor/method signatures decalred in this class):

- a constructor. subclasses must invoke `super`.
- registerDetails(). subclasses must invoke `super`.
- run(). subclasses do not invoke `super`.
- handleEvent(). subclasses do not invoke `super`.
- processEvent(). subclasses do not invoke `super`.
- handleStopRequest(). subclasses must invoke `super`.
- handleSuspendRequest(). subclasses must invoke `super`.
- handleResumeRequest(). subclasses must invoke `super`.
- handleTimerExpired(). subclasses must invoke `super`.
- postRun(). subclasses must invoke `super`.

IfsAgent also implements convenience methods used by subclasses, for session management, timer management, etc.

Constructor Summary
`IfsAgent(java.lang.String name, java.lang.String[] args, java.lang.String parameterTableSection, oracle.ifs.agents.manager.ServerManager manager)` Constructs an IfsAgent.

Method Summary
`LibrarySession` | `checkSession()` Gets the session used by this agent.
`LibrarySession` | `connectSession()` Connects a session for use by the agent.
`void` | `disconnectSession()` Disconnects the session used by this agent.
`AgentLogger` | `getAgentLogger()` Gets the logger used by the Agent.
`java.util.Date` | `getLastTimerActivation()` The time at which this Agent last received a Timer expired event.
`java.lang.String` | `getName()` Gets the name of this Agent.
`java.util.Date` | `getNextTimerActivation()` The time at which this Agent is expected to receive a Timer expired event.
`ParameterTable` | `getParameterTable()` Gets the ParameterTable which defines the configuration options for this agent.
`int` | `getPriority()` Gets the priority of this Agent.
`java.lang.Long` | `getServerDetailId()` Gets the SERVERDETAIL Id that represents this agent.
`LibrarySession` | `getSession()` Gets the session used by this agent.
`protected void` | `handlePriorityChangeRequest()` handle priority change request.
`protected void` | `handleRequests()` Handle any status requests.
`protected void` | `handleResumeRequest()` handle the resume request.
`protected void` | `handleStopRequest()` handle the stop request.
`protected void` | `handleSuspendRequest()` handle the suspend request.
`protected void` | `handleTimerExpired()` handle the timer expired request.
`boolean` | `isAlive()` Gets whether this Agent is alive.
`boolean` | `isSuspended()` Gets whether this Agent is suspended.
`protected boolean` | `isTimerActive()` Return indication of timer being active.
`void` | `postRun()` Performs post-run tasks for this Agent.
`void` | `processEvent(IfsEvent event)` Process an event that has been queued.
`void` | `processEvents()` Process all events that have been queued.
`void` | `publishDetail(java.lang.String propertyName, java.lang.Object value)` Publish new detailed status information or updated previously registered property in this agent's SERVERDETAIL object.
`void` | `publishStatusDetail()` Publish the agent's status.
`protected void` | `queueEvent(IfsEvent event)` Queues next IfsEvent for processing.
`void` | `registerDetails()` Register detailed status information into our ServerDetail.
`void` | `run()` Runs this Agent.
`void` | `setAgentLogger(AgentLogger logger)` Sets the logger to be used by the Agent.
`void` | `setPriority(int priority)` Sets the priority of this Agent.
`protected void` | `startTimer()` Starts a timer, that will post "timer expired" events at a specified interval.
`protected void` | `stopTimer()` Stops the timer, if it was started via startTimer().
`protected void` | `waitAgent()` Wait for the next request or event.

Constructor Detail

### IfsAgent

    public IfsAgent(java.lang.String name,
                    java.lang.String[] args,
                    java.lang.String parameterTableSection,
                    oracle.ifs.agents.manager.ServerManager manager)
             throws IfsException

  Constructs an IfsAgent.

  Agent subclass constructors define a constructor with this signature, and must invoke super to invoke this constructor.

  Parameters:
    `name` - the Agent name
    `args` - a ParameterTable argument list
    `parameterTableSection` - the section in the ParameterTable that contains parameters for this Agent
    `manager` - the managing ServerManager
  Throws:
    `IfsException` - (IFS-46000) if the operation fails

Method Detail

### getName

    public java.lang.String getName()

  Gets the name of this Agent.
  Specified by:
    `getName` in interface `Agent`
  Returns:
    the name

### getSession

    public LibrarySession getSession()

  Gets the session used by this agent. Returns null if no session is active for the agent.
  Returns:
    the session.

### checkSession

    public LibrarySession checkSession()
                                throws IfsException

  Gets the session used by this agent. This performs an additional check to verify that the session is still connected to iFS, and has not timed out or otherwise been disconnected. Returns null if no session is active for this agent.
  Returns:
    the session.

### getServerDetailId

    public java.lang.Long getServerDetailId()

  Gets the SERVERDETAIL Id that represents this agent.
  Returns:
    the ServerDetail Id

### registerDetails

    public void registerDetails()
                         throws IfsException

  Register detailed status information into our ServerDetail. This is called by ServerManager after an agent is constructed, whether or not the agent is actually started. The implementation in IfsAgent publishes the status and priority information. Subclasses of IfsAgent will often extend this to publish other agent information - if so, the subclasses must invoke super.
  Throws:
    `IfsException` - if the operation fails

### publishStatusDetail

    public void publishStatusDetail()

  Publish the agent's status. This adds or updates the "Status" and "NumericStatus" properties in the agent's SERVERDETAIL object.

  If no session is active when this method is invoked, a session will be created temporarily in order to update the status information, and then disconnected when complete.

### publishDetail

    public void publishDetail(java.lang.String propertyName,
                              java.lang.Object value)
                       throws IfsException

  Publish new detailed status information or updated previously registered property in this agent's SERVERDETAIL object.
  Parameters:
    `propertyName` - The name of the property.
    `value` - The value for the property.
  Throws:
    `IfsException` - if the operation fails

### connectSession

    public LibrarySession connectSession()
                                  throws IfsException

  Connects a session for use by the agent. If there is already a session established, no additional action is taken. If a new session is created, administration mode is enabled automatically.
  Returns:
    the session.
  Throws:
    `IfsException` - if the operation fails

### disconnectSession

    public void disconnectSession()

  Disconnects the session used by this agent. If no session is active for the agent, this method does nothing.

### getAgentLogger

    public AgentLogger getAgentLogger()

  Gets the logger used by the Agent.
  Specified by:
    `getAgentLogger` in interface `Agent`
  Returns:
    logger the AgentLogger used by the Agent for logging.

### setAgentLogger

    public void setAgentLogger(AgentLogger logger)
                        throws IfsException

  Sets the logger to be used by the Agent.
  Specified by:
    `setAgentLogger` in interface `Agent`
  Parameters:
    `logger` - the AgentLogger to be used for logging.
  Throws:
    `IfsException` - if the operation fails

### getParameterTable

    public ParameterTable getParameterTable()

  Gets the ParameterTable which defines the configuration options for this agent. This ParameterTable reflects the options defined in the agent section of the ServerManager configuration file, unioned with the options defined in the configuration file header. The section options take precedence in case the same option is defined in both the header and in the agent section.
  Specified by:
    `getParameterTable` in interface `Agent`
  Overrides:
    `getParameterTable` in class `oracle.ifs.common.BaseMain`
  Returns:
    the agent options ParameterTable

### getPriority

    public int getPriority()
                    throws IfsException

  Gets the priority of this Agent.

  The priority must be between `Thread.MIN_PRIORITY` and `Thread.MAX_PRIORITY`, inclusive.

  Specified by:
    `getPriority` in interface `Agent`
  Returns:
    the priority
  Throws:
    `IfsException` - (IFS-46013) if the operation fails

### setPriority

    public void setPriority(int priority)
                     throws IfsException

  Sets the priority of this Agent.

  The priority must be between `Thread.MIN_PRIORITY` and `Thread.MAX_PRIORITY`, inclusive.

  Specified by:
    `setPriority` in interface `Agent`
  Parameters:
    `priority` - the priority
  Throws:
    `IfsException` - (IFS-46014) if the operation fails

### waitAgent

    protected void waitAgent()
                      throws IfsException

  Wait for the next request or event. This should only be called from within the main loop inside `run()`.

  This returns immediately if there are pending requests or events.

### handleRequests

    protected void handleRequests()
                           throws IfsException

  Handle any status requests. This results in calls to `handleStopRequest()`, `handleSuspendRequest()`, `handleResumeRequest()`, `handleTimerExpired()`, or `handlePriorityChangeRequest()` for all pending status requests.

### handleStopRequest

    protected void handleStopRequest()
                              throws IfsException

  handle the stop request. Subclasses can override this to perform custom tasks as part of a Stop request, but must invoke super first.
  Throws:
    `IfsException` - if operation fails

### handleSuspendRequest

    protected void handleSuspendRequest()
                                 throws IfsException

  handle the suspend request. Subclasses can override this to perform custom tasks as part of a Suspend request, but must invoke super first.
  Throws:
    `IfsException` - if operation fails

### handleResumeRequest

    protected void handleResumeRequest()
                                throws IfsException

  handle the resume request. Subclasses can override this to perform custom tasks as part of a Resume request, but must invoke super first.
  Throws:
    `IfsException` - if operation fails

### handleTimerExpired

    protected void handleTimerExpired()
                               throws IfsException

  handle the timer expired request. Subclasses typically override this to perform custom timed tasks, but must invoke super first.
  Throws:
    `IfsException` - if operation fails

### handlePriorityChangeRequest

    protected void handlePriorityChangeRequest()
                                        throws IfsException

  handle priority change request. Subclasses can override this to perform any custom tasks, but must invoke super first.
  Throws:
    `IfsException` - if operation fails

### queueEvent

    protected void queueEvent(IfsEvent event)

  Queues next IfsEvent for processing. This is called from within handleEvent() for event-based agents. These queued events are processed by the call to `processEvents()`. *
  Parameters:
    `event` - the event.

### processEvents

    public void processEvents()
                       throws IfsException

  Process all events that have been queued. This calls the processEvent method for all queued IfsEvents. This method should only be called from within the main loop inside `run()`.
  Throws:
    `IfsException` - if operation fails.

### processEvent

    public void processEvent(IfsEvent event)
                      throws IfsException

  Process an event that has been queued. Subclasses override this method to handled the event as appropriate for the agent. The subclass should not invoke super() for this method.
  Parameters:
    `event` - the event.
  Throws:
    `IfsException` - if operation fails.

### isAlive

    public boolean isAlive()
                    throws IfsException

  Gets whether this Agent is alive.

  An Agent is alive if it has been started and has not stopped nor been requested to stop.

  Specified by:
    `isAlive` in interface `Agent`
  Returns:
    whether it is alive
  Throws:
    `IfsException` - (IFS-46030) if the operation fails

### isSuspended

    public boolean isSuspended()
                        throws IfsException

  Gets whether this Agent is suspended.

  An Agent is suspended if it has been started and then suspended, and has not resumed or stopped.

  Specified by:
    `isSuspended` in interface `Agent`
  Returns:
    whether it is suspended
  Throws:
    `IfsException` - (IFS-46031) if the operation fails

### getLastTimerActivation

    public java.util.Date getLastTimerActivation()

  The time at which this Agent last received a Timer expired event.
  Returns:
    the time of the last timer event, or null if the timer is not active or has not yet triggered a Timer expired event

### getNextTimerActivation

    public java.util.Date getNextTimerActivation()

  The time at which this Agent is expected to receive a Timer expired event.
  Returns:
    the time of the last timer event, or null if the timer is not activated.

### run

    public void run()

  Runs this Agent.

  Override this method with the tasks to be performed by this Agent. If this method returns (either explicitly or by throwing an Error), `postRun` is invoked and the Agent is stopped.

  Specified by:
    `run` in interface `Agent`

### postRun

    public void postRun()

  Performs post-run tasks for this Agent.

  This method is invoked when an agent is stopped, and has returned fomr the `run()` method. Subclasses can override this to perform custom tasks, such as disconnecting the session and stopping the timer, but must invoke super first.

  Specified by:
    `postRun` in interface `Agent`

### startTimer

    protected void startTimer()

  Starts a timer, that will post "timer expired" events at a specified interval.

  The timer options are specified in the agent section of the ServerManager configuration file. The options that are supported are:

  - ActivationPeriod - the frequency of timer events. This option must be set for the timer to be activated. The value can be specified in terms of hours, minutes, seconds, or milliseconds; using an integer followed by the time unit as a single character suffix. The default unit suffices are 'H' for hours, 'M' for minutes, and 'S' for seconds. If no suffix, the unit is in milliseconds. Examples are:
    - ActivationPeriod = 4h (for 4 hour frequency)
    - ActivationPeriod = 90m (for 1.5 hour frequency)
    - ActivationPeriod = 3500 (for 3.5 second frequency)
  - InitialTimeOfDay - the time of day for the first timer event. If omitted, the initial time is determined from the InitialDelay option. The value is specified using a 24-hour clock specification for the time-of-day, using the format HH:mm:ss. Examples are:
    - InitialTimeOfDay = 3:30:00 (initial event will be 3:30 a.m.)
    - InitialTimeOfDay = 20:00:00 (initial event will be 8:00 p.m.)
  - InitialDelay - the initial delay before posting the first timer event, relative to the time the agent is started. If this option is not set and the InitialTimeOfDay option is not set, the initial delay is the same as the ActivationPeriod. The value uses the same format as described for the ActivationPeriod. Examples are:
    - InitialDelay = 30m (first timer event occurs 30 minutes after starting)
    - InitialDelay = 90s (first timer event occurs 1.5 minutes after starting)

  The last and next timer events are published in the agent's SERVERDETAIL object once the timer is started.

### stopTimer

    protected void stopTimer()

  Stops the timer, if it was started via startTimer().

### isTimerActive

    protected boolean isTimerActive()

  Return indication of timer being active.
  Returns:
    true if timer is active.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD