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

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:

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.