com.ls.lars.server
Class AgentCron

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--com.ls.lars.communication.CommunicationTemplate
              |
              +--com.ls.lars.server.AgentTemplate
                    |
                    +--com.ls.lars.server.AgentCron
All Implemented Interfaces:
ICommunication, IToLars, Runnable, Serializable

public class AgentCron
extends AgentTemplate


to Class Specification
The role of this agent is: if an agent wants to do a job periodically; then that agent sends a request to AgentCron to be notified at a specified period of time to do a specified job. AgentCron internally stores and parses the messages into a queue.
Further on the clients of agent cron can send a message that a job sould be removed or modified (modification of a job can be done in two messages: one to erase the job and one to request a new job).

Note: AgentCron is depending on the services of AgentTimer!

 Incoming Messages:
      AgentCron understands messages for the following services.
      Input parameters you have to specify are listed with the messages
      and must be transmitted using a Map.
      ------------------------------------------------------------------------
      notify_agent
      ------------------------------------------------------------------------
      Function:   Inserts a notification request into the cron queue.

      Parameters: expression of period, agent, job to be done (Map)
                  The syntax is explained below in detail in the section
                  "content of a notify_agent message".

      Responses:  notified_agent      The notification request was added to
                                      the timer queue.

                  agent_not_notified  The request was malformed (i.e. bad
                                      period of time) and was not added to
                                      the queue.

                  Both responses use the reply ID of the incoming message and
                  send back the original parameter map as content. This
                  can be saved, for instance, to be able to cancel a
                  notification later on. The quality of service of either
                  reply is QualityOfService.QOS_NONE.
      ------------------------------------------------------------------------
      cancel_notify
      ------------------------------------------------------------------------
      Function:   Removes a notification from the cron queue.

      Parameters: expression of period, agent, job to be done (Map)

      Responses:  notify_canceled      The notification request was removed
                                       from the cron queue.

                  notify_not_canceled  The notification could not be removed
                                       because of a malformed specification
                                       of the time or because the notification
                                       request does not exist.

                  Both responses use the reply ID of the incoming message and
                  send back the original parameter map as content.
                  The quality of service of either reply is
                  QualityOfService.QOS_NONE.
      ------------------------------------------------------------------------
      wake_up
      ------------------------------------------------------------------------
      Function:   AgentTimer informs AgentCron, that he now needs to
                  send one or multiple message to his client agents
                  (those agents, that requested the notification).

      Parameters: none (content is not needed and ignored)

      Responses:  the message that the agent requested to be notified
                  at the specified time
      ------------------------------------------------------------------------
      response_group_members
      ------------------------------------------------------------------------
      Function:   AgentMessageRouter informs AgentCron, what are the agents that
                  compose a message group (depending on the message that
                  AgentCron sends to AgentMessageRouter).
                  This message is used to determine if a group(s) has any agent
                  alive.

      Parameters: the current message with the list of agents

      Responses:  none
      ------------------------------------------------------------------------
      response_service_provider_members
      ------------------------------------------------------------------------
      Function:   AgentMessageRouter informs AgentCron, what are the agents that
                  are register as 'service provider' (depending on the message
                  that AgentCron sends to AgentMessageRouter). This message is
                  used to determine if there are still agents alive, which are
                  registered as service providers.

      Parameters: the current message with the list of agents

      Responses:  none
      ------------------------------------------------------------------------
      sender_rip
      ------------------------------------------------------------------------
      Function:   Removes all notification requests of the sender from the
                  cron queue, because that agent just died.

      Parameters: none (content is not needed and ignored)

      Responses:  Due to the termination of the requesting agent no answer is
                  sent.
 -----------------------------------------------------------------------------
 Config File:
      AgentCron does not need to have a config file. If it has one, it can
      contain any notification request(s).
 
The content of a notify_agent message must have the following format: <content> <period> <type> </type> <minute> </minute> <hour> </hour> <day> </day> <day_of_month> </day_of_month> </period> <MESSAGE> <service> </service> <receiver> </receiver> <content> </content> </MESSAGE> </content> The possible values for the tag type from the period are: CRON, INTERVAL and TIME.

CRON: specifies the exact period in time the notification has to be send

- "minute" - can be an integer in the interval (0,59) or the symbol "*" - "hour" - can be an integer in the interval (0,23) or the symbol "*" - "day" - can be one of the days of the week in english or the symbol "*" - "day_of_month" - can be one of the days of the month an integer between 1 and 31, it can not be the symbol "*" Attention : 1. the char "*" means "every" (so when you specify this symbol in the minute field you expect to receive the message every minute of the specified period)! 2. the fields "day" and "day_of_month" can be both specified at the same time, but is necesary that at least one of them to be specified. example: <content> <period> <type>CRON</type> <minute>5</minute> <hour>*</hour> <day>MONDAY</day> <day_of_month>3</day_of_month> </period> <MESSAGE> <service>notification_service</service> <receiver>agent_A</receiver> <content> </content> </MESSAGE> </content> - means: notify "agent_A" with the message "notification_service" on each Monday at the minute 5 of the every hour of the day.

INTERVAL: specifies interval of time between notifications

- "minute" - can be an positive integer greater than 0 or "0" - "hour" - can be an positive integer greater than 0 or "0" - "day" - can be an positive integer greater than 0 or "0" Attention : 1. the "0" is the neutral! 2. the field "day_of_month" is not alowed example: <content> <period> <type>INTERVAL</type> <minute>5</minute> <hour>0</hour> <day>2</day> </period> <MESSAGE> <service>notification_service</service> <receiver>agent_A</receiver> <content> </content> </MESSAGE> </content> - means: notify "agent_A" with the message "notification_service" at an interval of 2 days and 5 minutes.

TIME: specifies a point in time when the the notification is needed

- "minute" - can be an integer in the interval (0,59) - "hour" - can be an integer in the interval (0,23) - "day" - can be one of the day of the week in english - "day_of_month" - can be one of the days of the month an integer between 1 and 31 Attention : 1. it is a normal date and a request like that is satisfied only once! 2. the fields "day" and "day_of_month" can be both specified at the same time, but is necesary that at least one of them to be specified. example: <content> <period> <type>TIME</type> <minute>5</minute> <hour>0</hour> <day>Monday</day> <day_of_month>3</day_of_month> </period> <MESSAGE> <service>notification_service</service> <receiver>agent_A</receiver> <content> </content> </MESSAGE> </content> - means: notify "agent_A" with the message "notification_service" will be notified on Monday at hour 0 and minute 5. Attention: For security reasons an agent can't send requests for notification for another agent!

Version:
$Revision: 1.23 $
Author:
Last modified by $Author: ODrugan $
See Also:
Serialized Form

Field Summary
protected  String revisionInformation
          revision information string, managed by our version control system.
 
Fields inherited from class com.ls.lars.server.AgentTemplate
agentMaxPool, agentMessageRouterName, agentMinPool, defaultServiceAccessPermission, defaultServiceAccessPrivilege, dynamicObjectController, FULL_SERVICE_ACCESS, iXMLHandlerForConfigLoader, localPlatform, maxInvokeStackCounter, NO_SERVICE_ACCESS, RUN_LEVEL_ACTIONS_INITIALIZED, RUN_LEVEL_CONFIG_FILE_INTERPRETED, RUN_LEVEL_CONFIG_FILE_READ, RUN_LEVEL_EMBRYONIC, RUN_LEVEL_INTERPRET_METHODS_REGISTERED, RUN_LEVEL_POOL_INITIALIZED, RUN_LEVEL_RUNNING, RUN_LEVEL_STOPPED, RUN_LEVEL_TERMINATED
 
Fields inherited from class com.ls.lars.communication.CommunicationTemplate
agentName, homePlatform, iPKIHandler, logger, STATUS_CONNECTED, STATUS_NOT_CONNECTED
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Fields inherited from interface com.ls.lars.communication.ICommunication
AUTHENTICATION_PASSWORD, AUTHENTICATION_USER, COMPRESSION_AUTO_COMPRESSION, COMPRESSION_AUTO_COMPRESSION_START_SIZE, COMPRESSION_LEVEL, COMPRESSION_TYPE, COMPRESSION_ZIP_ENTRY_NAME, CONNECTION_TYPE, HOST_ID, HOST_IP, HOST_PORT, HTTP, J_SECURE_SOCKET, J_SOCKET, JMS, JMS_INITIAL_CONTEXT_FACTORY, JMS_JMSMESSENGER_APPLICATION_LOCATION, JMS_PROVIDER_URL, JMS_RECEIVING_QUEUE_NAME, JMS_SECURITY_CREDENTIALS, JMS_SECURITY_PRINCIPAL, JMS_SENDING_QUEUE_NAME, MAXIMUM_MESSAGE_LENGTH, PROTOCOL, RMI, SOCKET, TIMEOUT, USE_OUTBOX
 
Constructor Summary
AgentCron(String agentName, String homePlatform, List agentConfigFiles)
          Constructor with the agentName, its homePlatform and a List containing the names of the configuration file(s) of the new agent.
 
Method Summary
protected  String getRevisionInformation()
          gets the revision information of this agent
protected  void initializeAction()
          Initializes the immediateList, the requestedList, CronQueue and CronThread components. This method gets called, before the config file is interpreted!
 void initializeMessages()
          Calls super.initializeMessages() and afterwards registers AgentTimer as a service provider for the service "sender_rip".
protected  boolean interpretCancelNotify(Message currentMessage)
          Cancels the notification, specified in the content of the message, of an agent.
protected  boolean interpretNotifiedAgent(Message currentMessage)
          Writes a log message to the system's log file and to the agent's log file, because a "notified_agent" message was received (probably from AgentTimer).
protected  boolean interpretNotifyAgent(Message currentMessage)
          Registers the agent to be notified at a specific period of time.
protected  boolean interpretNotifyCanceled(Message currentMessage)
          Implements the reaction that the agent should have in case that it receives a notification of a cancel.
protected  boolean interpretResponseGroupMembers(Message currentMessage)
          Interprets the message 'response_group_member', it verifies if the message contains the tag "error" in its content message.
protected  boolean interpretResponseServiceProviderMembers(Message currentMessage)
          Interprets the message 'response_service_provider_member', it verifies if the message contains the tag "error" in its content message.
protected  boolean interpretSenderRip(Message currentMessage)
          Cancels all notifications for the sender of the given message, because that agent just died.
protected  boolean interpretWakeUp(Message currentMessage)
          Sends a new request for notification to the AgentTimer when it receive a notification for wake up for the next element from the immediateRequestlist and try to send a notification to the agent or agents that need the notification at that time.
 boolean terminateAction()
          Checks, if the corresponding cron requestedList has any notification requests.
 
Methods inherited from class com.ls.lars.server.AgentTemplate
executeLifeCycle, executeWhileRunning, getAgentRevisionInformation, getIPKIHandler, getOwnPublicKeyCertificate, interpret, interpretAccessDenied, interpretAgentConnected, interpretCheckRegisteredServices, interpretCloseConnection, interpretDefineObject, interpretDeliveryFailed, interpretGetRevisionInformation, interpretInterpretationSuccessful, interpretLoadObject, interpretLogInbox, interpretMonitorLookup, interpretNotifyNotCanceled, interpretNotUnderstood, interpretPing, interpretRegisterService, interpretSendAsConfigured, interpretSetAccessPrivileges, interpretSetForeignPublicKeyCertificate, interpretSetLog, interpretSetOwnPublicKeyCertificate, interpretSetPkiEnvironment, interpretSetPkiMessages, interpretSetPrivateKey, interpretSetRunLevel, interpretSignatureNotValid, interpretStartupConstraint, loadConfigFile, performDefaultBehavior, reconnectAfterMigration, registerInterpretMethods, registerInterpretMethods, registerInterpretMethods, reInitializeAction, setAgentMessageRouterName, setIXMLHandler, setLocalPlatform, setPKIMessage, toString
 
Methods inherited from class com.ls.lars.communication.CommunicationTemplate
addConnectionParameter, checkSendSystemReply, connect, createReplyId, disconnect, disconnectForMigration, finalize, forwardMessage, forwardMessage, getAgentName, getConnectionParameters, getInboxSize, getLarsHost, getNumberOfProcessedMessages, getNumberOfProcessedMessagesPerMinute, getStartTime, isConnected, logInbox, receiveBlockedMessage, receiveBlockedMessage, run, sendMessage, sendSynchronousRequest, sendSynchronousRequest, setConnectionParameters, setLog, setMeantimeBetweenConnectionCheck, waitForConnection, waitForConnection
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, yield
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.ls.lars.communication.IToLars
start
 

Field Detail

revisionInformation

protected String revisionInformation
revision information string, managed by our version control system.
Constructor Detail

AgentCron

public AgentCron(String agentName,
                 String homePlatform,
                 List agentConfigFiles)
Constructor with the agentName, its homePlatform and a List containing the names of the configuration file(s) of the new agent.
Parameters:
agentName - name of the agent. (example: xyz)
homePlatform - the name of the homePlatform where the agent was created. (example: 195.52.158.233/lars)
agentConfigFiles - the config file(s), which should be read by the agent when it starts up.
Method Detail

getRevisionInformation

protected String getRevisionInformation()
gets the revision information of this agent
Overrides:
getRevisionInformation in class AgentTemplate
Returns:
the revision information

initializeAction

protected void initializeAction()
Initializes the immediateList, the requestedList, CronQueue and CronThread components. This method gets called, before the config file is interpreted!
Overrides:
initializeAction in class AgentTemplate

initializeMessages

public void initializeMessages()
Calls super.initializeMessages() and afterwards registers AgentTimer as a service provider for the service "sender_rip". This assures, that AgentTimer gets to know, if any of its clients (agents, that want to be notified) ceases to exist and allows AgentTimer, to remove the (then unused) notification requests.
Overrides:
initializeMessages in class AgentTemplate

interpretNotifyAgent

protected boolean interpretNotifyAgent(Message currentMessage)
Registers the agent to be notified at a specific period of time. First verifies the message to be to have a valid structure for the period and for the message that has to be sent as a notification. And register the request into the cronQueue.
Parameters:
currentMessage - message with a notification request of an agent
Returns:
true if the message has been interpreted

interpretCancelNotify

protected boolean interpretCancelNotify(Message currentMessage)
Cancels the notification, specified in the content of the message, of an agent. First verifies the request message to have a valide form (valid structure for the period and for the message). This usually happends when the notification is not nedded any more or the agent ends before the notification has to be sent.
Parameters:
currentMessage - message with a cancel request of an Agent
Returns:
true if the message has been interpreted

interpretNotifyCanceled

protected boolean interpretNotifyCanceled(Message currentMessage)
Implements the reaction that the agent should have in case that it receives a notification of a cancel.
Overrides:
interpretNotifyCanceled in class AgentTemplate
Parameters:
currentMessage - message with a notification for cancel
Returns:
true if the message has been interpreted

interpretWakeUp

protected boolean interpretWakeUp(Message currentMessage)
Sends a new request for notification to the AgentTimer when it receive a notification for wake up for the next element from the immediateRequestlist and try to send a notification to the agent or agents that need the notification at that time.
Parameters:
currentMessage - message with a notice request from a previous request.
Returns:
true if the message has been interpreted

interpretSenderRip

protected boolean interpretSenderRip(Message currentMessage)
Cancels all notifications for the sender of the given message, because that agent just died. Due to the termination of the requesting agent no answer is sent.
Parameters:
currentMessage - message with cancel request
Returns:
true, if successful; false else

interpretResponseGroupMembers

protected boolean interpretResponseGroupMembers(Message currentMessage)
Interprets the message 'response_group_member', it verifies if the message contains the tag "error" in its content message.
Parameters:
currentMessage - the mesage with the service 'response_group_member'
Returns:
always true

interpretResponseServiceProviderMembers

protected boolean interpretResponseServiceProviderMembers(Message currentMessage)
Interprets the message 'response_service_provider_member', it verifies if the message contains the tag "error" in its content message.
Parameters:
currentMessage - the mesage with the service 'response_service_provider_member'
Returns:
always true

interpretNotifiedAgent

protected boolean interpretNotifiedAgent(Message currentMessage)
Writes a log message to the system's log file and to the agent's log file, because a "notified_agent" message was received (probably from AgentTimer).
Overrides:
interpretNotifiedAgent in class AgentTemplate
Parameters:
currentMessage - "notified_agent" message
Returns:
always true

terminateAction

public boolean terminateAction()
Checks, if the corresponding cron requestedList has any notification requests. If not, the cron thread is stopped and super.terminateAction is called.
Overrides:
terminateAction in class AgentTemplate
Returns:
false, if the corresponding cron list has any more agent notification requests; super.terminateAction() else
See Also:
AgentTemplate.terminateAction()