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.