|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.lang.Thread | +--com.ls.lars.communication.CommunicationTemplate | +--com.ls.lars.server.AgentTemplate
provides everything a lars agent needs to execute its life cycle
All other agents descend from this class. It has core functionalities like logging or answering if a
message was not understood or sending a "pong" reply to a "ping" message.
Introduction to lars agent run levels:
EMBRYONIC
INTERPRET_METHODS_REGISTERED
protected boolean interpretDoSomething(Message)
is called)
CONFIG_FILE_READ
ACTIONS_INITIALIZED
initializeAction()
method without any
unforeseen exceptions/errors.
CONFIG_FILE_INTERPRETED
POOL_INITIALIZED
AgentManager
- the run level instead is reached independently of an agent
running pooled or unpooled.
RUNNING
initializeMessages()
method without any
unforeseen exceptions/errors. executeWhileRunning()
methodSTOPPED
TERMINATED
terminateAction()
.
Incoming Messages: AgentTemplate itself understands the following messages. You should take care that your subclasses will always call their super's methods for interpreting messages if they don't process a message themselves, or information may get lost. If neither the subclass nor AgentTemplate will interpret a message, a message with the service not_understood will be generated and sent back to the sender. ------------------------------------------------------------------------ set_access_privileges (Config) ------------------------------------------------------------------------ Function: Sets the privileges for accessing the services of the current agent. Parameters: serviceAccessPrivileges (Hashtable) Responses: none Note: This message is used for defining access privileges in order to control which agent is allowed to request what services.
The privileges are being set in a two-fold way: - ThespecificSetting
access privileges, which are used for defining detailed rules on the accessibility of specific services. - ThegeneralSetting
access privileges, which will take effect, when no specific privileges are given for the actually requested service. This message will be interpreted only when it was read from the config file - or when the sender equals LARS_INTERNAL. The default access privileges for all services are set toFULL_SERVICE_ACCESS
. Although this settings can be changed in sub classes, just by modifying thedefaultServiceAccessPrivilege
member variable. The general schema for specifying access rulings looks like this:
Configuration example:
This configuration sets the general access to the agent's services to no_access (i.e. no agent is allowed to request the services). Then (within theadditional
tag) the access for {service_name} is granted to all that agents of the platform, the actual agents was born on (i.e. his homeplatform). When you configure the settings for specific services, you can also put an asterisk "*" into the <service> tag, in order to set this rule for all available services. ------------------------------------------------------------------------ set_log ------------------------------------------------------------------------ Function: Sets the name for the log file and the logging verbosity level. Parameters: logFile, logLevel, logType (Map) Responses: none ------------------------------------------------------------------------ register_service (config file only) ------------------------------------------------------------------------ Function: Registers this agent as a service provider agent for the given services. Parameters: service (String) or services (List) The service(s) this agent wants to become a service provider for. To realize the multiple service registration in XML use onetag for each service! Responses: none Note: If this message wasn't read from a config file, it is assumed to be a security violation and the message is ignored (no other agent is allowed to tell me to register myself as a service provider for any service!). ------------------------------------------------------------------------ load_object (config file only) ------------------------------------------------------------------------ Function: Instantiates and possibly configures an object of the given class, that is afterwards stored in this agent's dynamicObjectController
. If a configuration is performed, depends on, if the new object implementsIConfigurable
. If yes,configure(configuration)
with the given Map is called on the new object.
In the end the new object is stored in the dynamicObjectController under the given key. Parameters: class (String): name of the class to instantiate key (String): accessor key for the new object (needed to retrieve it from dynamicObjectController) configuration (optional, Map or String): (if instance of Map): object-dependant XML-structure used for the new object's configuration (if instance of String): config file containing the new object's configuration Responses: none ------------------------------------------------------------------------ define_object (config file only) ------------------------------------------------------------------------ Function: Defines an object of the given class. A new instance of a defined object then can be retrieved withDynamicObjectController.getInstanceFromDefined(java.lang.Object)
from this agent'sdynamicObjectController
. If a configuration is performed after an instantiation, depends on, if the new object implementsIConfigurable
. If yes,configure(configuration)
with the given Map is called on the new object. Parameters: class (String): name of the class to define/instantiate key (String): accessor key for the object definition (needed to retrieve it from dynamicObjectController) configuration (optional, Map or String): (if instance of Map): object-dependant XML-structure used for the new object's configuration (if instance of String): config file containing the new object's configuration Responses: none ------------------------------------------------------------------------ set_run_level ------------------------------------------------------------------------ Function: Sets the run level of the agent to a new value. The new run level can be any of the values TERMINATED, STOPPED or RUNNING. Parameters: runLevel (String) Responses: run_level_set agent's run level was changed run_level_not_set agent's run level could not be changed Both replies contain a map with: agentName: name of the agent who was requested to change the run level requestedRunLevel: run level the agent was asked to enter (lacking, if the content of the request could not be interpreted!) previousRunLevel: run level of the agent before the request was interpreted currentRunLevel: run level of the agent after the request was interpreted ------------------------------------------------------------------------ ping ------------------------------------------------------------------------ Function: Checks whether the agent is alive. If it is, it will reply with a "pong" message. Parameters: none Responses: pong Agent is alive and working. Response message content: time,location (Map); represents the local time and the ID of the platform the agent is running on. ------------------------------------------------------------------------ not_understood ------------------------------------------------------------------------ Function: Writes a warning to the agent's log, that a message was not interpreted by the agent. Check for spelling errors in message services or for a wrong content if you encounter this. Parameters: all fields of a message.toMap of the message, that was not understood plus the following fields: reasonOfFailureText: Ttextual description of the reason for the failure reasonOfFailureCode: code of the failure (seeQualityOfService
) Responses: none ------------------------------------------------------------------------ delivery_failed ------------------------------------------------------------------------ Function: Writes a warning to the agent's log file, that a message for an agent could not be interpreted because the agent was not reached. Parameters: all fields of a message.toMap of the message, that was not deliverable plus the following fields: reasonOfFailureText: textual description of the reason for the failure reasonOfFailureCode: code of the failure (seeQualityOfService
) routeFailedAt (optional): messenger or component, where the failure occurred Responses: none ------------------------------------------------------------------------ access_denied ------------------------------------------------------------------------ Function: Writes a warning to the agent's log file, that a message for an agent could not be interpreted because the recipient denied the interpretation. Parameters: all fields of a message.toMap of the message, that was not interpreted plus the following fields: reasonOfFailureText: textual description of the reason for the failure reasonOfFailureCode: code of the failure (seeQualityOfService
) Responses: none ------------------------------------------------------------------------ interpretation_successful ------------------------------------------------------------------------ Function: Writes an INFO log entry to the agent's log file, that a message for another agent wasinterpreted correctly. Parameters: all fields of a message.toMap of the message, that was interpreted successfully plus the following fields: reasonOfFailureText: contains an "interpretat returned true" text reasonOfFailureCode:QualityOfService.QOS_INTERPRET_TRUE
Responses: none ------------------------------------------------------------------------ get_revision_information ------------------------------------------------------------------------ Function: Reads the revision information of the agent and sends a reply message with that revision information. Parameters: none Responses: revision_information The revision information of the current agent (subclass). ------------------------------------------------------------------------ log_inbox ------------------------------------------------------------------------ Function: Reads the messages of the agent from the inbox and writes the messages in the log file of the agent Parameters: none Responses: none Note: it makes sense that this message hassystem priority
. ------------------------------------------------------------------------ notified_agent, notify_canceled, notify_not_canceled ------------------------------------------------------------------------ Function: These messages are captured without any additional functionality. If your agent cooperates with AgentTimer or AgentCron, it should implement the methods interpretNotifiedAgent(), interpretNotifyCanceled(), interpretNotifyNotCanceled() to deal with those services. Parameters: - Responses: - ------------------------------------------------------------------------ set_pki_environment ------------------------------------------------------------------------ Function: Sets the Public Key Infrastructure (PKI) depending on the given parameters. Parameters: pki_handler: specifies which PKIHandler-class should be used (package lars or internet.auction) pki_provider: specifies which IPKIUtils-implementation should be used (currently, the only known implementation is com.ls.pki.BaltimorePKIUtils) Responses: - Note: This is the base for all following PKI-related messages. Because the PKI-classes are dynamically instantiated through this message. ------------------------------------------------------------------------ set_private_key ------------------------------------------------------------------------ Function: Sets the private key for the Public Key Infrastructure (PKI) to sign or encrypt contents. Parameters: keyfile_name: specifies the name of the private key file. location: specifies the file-location of the private key file. password: specifies the password of the private key file (needed to use it). Responses: - ------------------------------------------------------------------------ set_own_public_key_certificate ------------------------------------------------------------------------ Function: Sets the own public key certificate for the Public Key Infrastructure (PKI). The own Public Key is not really used, but there might reasons to distribute it. Parameters: keyfile_name: specifies the name of the public key certificate file. location: specifies the file-location of the public key certificate file. Responses: - Note: The Public Key Certificate file has to be PEM or DER formatted. Other formats are not supported! ------------------------------------------------------------------------ set_foreign_public_key_certificate ------------------------------------------------------------------------ Function: Sets a public key certificate of a foreign platform for the Public Key Infrastructure (PKI). Parameters: keyfile_name: specifies the name of the public key certificate file location: specifies the file-location of the public key certificate file keyID: the ID to identify this foreign public key certificate Responses: - Note: The Public Key Certificate file has to be PEM or DER formated. Other formats are not supported! ------------------------------------------------------------------------ set_pki_messages ------------------------------------------------------------------------ Function: Sets one or more messages which have to be signed, verified, encrypted, decrypted, signed and encrypted or decrypted and verified. Parameter structure (Attention: this message-tag is a XML-key within the content):
Parameters: service: the message-service for which a PKI-action has
to be done.
action: the action which has to be done:
sending actions: sign, encrypt, sign_encrypt
receiving actions: decrypt, verify,
decrypt_verify
data_key: only used for sending actions. It specified,
which message-dataKeys should be handled.
If no data-key is specified, all content-keys
of the message will be handled.
Responses: -
------------------------------------------------------------------------
check_registered_services
------------------------------------------------------------------------
Function: Monitoring the set PKI services (set_pki_messages).
Logs the registered PKI services of this agent into the
logfile and returns a message "registered_services" with
this information.
Parameters: none
Responses: registered_services
------------------------------------------------------------------------
signature_not_valid
------------------------------------------------------------------------
Function: Used from class PKIHandler to redirect messages with
invalid signatures.
This methods logs the message only to the agents logfile.
Parameters: all keys, that are created by Message.toMap()
verify_message - a detailed trace-message
Responses: none
------------------------------------------------------------------------
startup_constraint
------------------------------------------------------------------------
Function: Defines interdependencies between the current agent and one
or more other agents. This message tells the current agent
to wait for a given set of specified agents. As soon as all
awaited agents are available on the platform, the set of
specified messages will be interpreted.
Parameters: awaitedAgent: agent to wait for. If waiting for multiple
agents, each single agent's name is to be
specified within a separate 'awaitedAgent'
tag.
MESSAGE: The message to be send when all awaited
agents are available on the platform.
You can specify multiple MESSAGE tags,
which then will be interpreted in the order
you specified them.
Example:
Responses: - ------------------------------------------------------------------------- agent_connected ------------------------------------------------------------------------- Function: Notifies the current agent that a defined other agent is available on the local platform. Parameters: agent's name (String) The string message containing the agent's name Responses: - ------------------------------------------------------------------------- send_as_configured (Config) ------------------------------------------------------------------------- Function: Forwards one or more messages as read from this message's content. For more flexibility in configuration the messages can containg $a in order to reference this agent's name. Parameters: one or more MESSAGES Responses: - Note: This message can be send only by setting up this agent's config file. ------------------------------------------------------------------------- Config File: The AgentTemplate itself does not require a config file. For the PKI-stuff the PKI.cfg should be used to do the needed settings.
Field Summary | |
protected byte |
agentMaxPool
the maxim number of agents in the pool |
protected String |
agentMessageRouterName
Name of the local platforms AgentMessageRouter. |
protected byte |
agentMinPool
the minim number of agents in the pool |
protected String |
defaultServiceAccessPermission
the default setting for specific access settings |
protected boolean |
defaultServiceAccessPrivilege
the default setting for general access |
protected DynamicObjectController |
dynamicObjectController
Allows the storage of (configured) objects and of object definitions and the access of those with help of keys. |
protected static boolean |
FULL_SERVICE_ACCESS
constant specifying full access to services |
protected IXMLHandler |
iXMLHandlerForConfigLoader
knows the IXMLHandler, which is to be used for parsing config files |
protected String |
localPlatform
lars platform where this agent currently resides |
protected byte |
maxInvokeStackCounter
allowed number of nested interpret calls for each agent to make sure there is no invocation loop, default: 3 |
protected static boolean |
NO_SERVICE_ACCESS
constant specifying no access to services |
protected String |
revisionInformation
revision information string, managed by our version control system |
static int |
RUN_LEVEL_ACTIONS_INITIALIZED
agent run level constant stating, that the agent finished its initializeAction() method |
static int |
RUN_LEVEL_CONFIG_FILE_INTERPRETED
agent run level constant stating, that the agent finished interpreting its config file |
static int |
RUN_LEVEL_CONFIG_FILE_READ
agent run level constant stating, that the agent finished reading its config file from the file system |
static int |
RUN_LEVEL_EMBRYONIC
agent run level constant stating, that the agent is not yet started |
static int |
RUN_LEVEL_INTERPRET_METHODS_REGISTERED
agent run level constant stating, that the agent finished reading its config file from the file system |
static int |
RUN_LEVEL_POOL_INITIALIZED
agent run level constant stating, that the agent create its pooling |
static int |
RUN_LEVEL_RUNNING
agent run level constant stating, that the agent is running |
static int |
RUN_LEVEL_STOPPED
agent run level constant stating, that the agent stopped its execution - executeWhileRunning() will not be called any more |
static int |
RUN_LEVEL_TERMINATED
agent run level constant stating, that the agent ceases to exists - it at least has started its terminateAction() method |
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 |
Constructor Summary | |
AgentTemplate(String agentName,
String homePlatform,
List configFileNameList)
Constructor, that creates a local messenger and does the basic initialization of a new agent. |
Method Summary | |
void |
executeLifeCycle()
Executes when this agent thread gets started. |
protected void |
executeWhileRunning()
Main method of every agent, that is called in a loop as long as the agent's run level is less than STOPPED. |
String |
getAgentRevisionInformation()
Builds a well formatted string containing the revision information of the subclass (derived agent). |
protected IPKIHandler |
getIPKIHandler()
Method to get the IPKIHandler's Object. |
protected byte[] |
getOwnPublicKeyCertificate()
Gets the PublicKey Certificate as byte-array. |
protected String |
getRevisionInformation()
To make sure that every class (subclass) contains the revision information, this method has to be overwritten in every subclass (derived agent). |
protected void |
initializeAction()
empty implementation Note for developers: If you overwrite this method (e.g. because your agent needs special actions for its initialization like opening files, creating threads, ...), be sure to call the super classes initializeAction() to assure proper agent initialization! |
protected void |
initializeMessages()
Sends a "register" initialization message to the local AgentMessageRouter. Note for developers: If you overwrite this method, because your agent needs to send initialization messages to other agents, be sure to call the super classes initializeMessages() to assure proper agent initialization! |
protected boolean |
interpret(Message currentMessage)
Interprets the given message. |
protected boolean |
interpretAccessDenied(Message currentMessage)
Writes a log entry to the agent's log file, because the recipient of a message, that this agent has sent, denied the acces to the specified service. Note, that the logged message contains a content independent of the configured system log level! |
protected boolean |
interpretAgentConnected(Message currentMessage)
Takes the name of the connected agent and checks whether or not there are more agents to wait for. |
protected boolean |
interpretCheckRegisteredServices(Message currentMessage)
returns the service which are registered for pki-handling |
protected boolean |
interpretCloseConnection(Message currentMessage)
Writes a log entry to the agent's log file, because a "close_connection" message was received. |
protected boolean |
interpretDefineObject(Message currentMessage)
Stores an object definition of the given class in this agent's dynamicObjectController .
|
protected boolean |
interpretDeliveryFailed(Message currentMessage)
Writes a log entry to the agent's log file, because the recipient of a message, that this agent has sent, could not be determined. Note, that the logged message contains a content independent of the configured system log level! |
protected boolean |
interpretGetRevisionInformation(Message currentMessage)
Sends back the revision information. |
protected boolean |
interpretInterpretationSuccessful(Message currentMessage)
Writes a log entry to the agent's log file, that a message, that this agent has sent earlier, was interpreted successfully. |
protected boolean |
interpretLoadObject(Message currentMessage)
Instantiates and possibly configures an object of the given class, that is afterwards stored in this agent's dynamicObjectController .
|
protected boolean |
interpretLogInbox(Message currentMessage)
writes the content of the inbox of the agent to its log file |
protected boolean |
interpretMonitorLookup(Message currentMessage)
makes a lookup for sent messages (messages per minute, messages for all) |
protected boolean |
interpretNotifiedAgent(Message currentMessage)
Writes a log entry the agent's log file, because a "notified_agent" message was received (probably from AgentTimer ). |
protected boolean |
interpretNotifyCanceled(Message currentMessage)
Writes a log entry to the agent's log file, because a "notify_canceled" message was received (probably from AgentTimer ). |
protected boolean |
interpretNotifyNotCanceled(Message currentMessage)
Writes a log entry to the agent's log file, because a "notify_not_canceled" message was received (probably from AgentTimer ). |
protected boolean |
interpretNotUnderstood(Message currentMessage)
Writes a log entry to the agent's log file, because a message, that this agent has sent, caused a reply that states, that this agent's message could not have been interpreted. Note, that the logged message contains a content independent of the configured system log level! |
protected boolean |
interpretPing(Message currentMessage)
sends a pong to the sender of ping |
protected boolean |
interpretRegisterService(Message currentMessage)
Sends the given Message (after some validations) to the AgentMessageRouter instance of the local lars platform to declare this agent as a service provider for the given service(s) contained in the content of the Message as one String or a List of Strings. |
protected boolean |
interpretSendAsConfigured(Message currentMessage)
Forwards one or more messages as read from the config file to the corresponding receivers. |
protected boolean |
interpretSetAccessPrivileges(Message currentMessage)
Sets the service access rules for the current agent, which are effected when any other party request any service of the current agent. The service access rulings consist of two parts: the general and the
specific rulings. |
protected boolean |
interpretSetForeignPublicKeyCertificate(Message currentMessage)
Sets the public key for foreign platforms. |
protected boolean |
interpretSetLog(Message currentMessage)
Configures the log type, log file and log level. |
protected boolean |
interpretSetOwnPublicKeyCertificate(Message currentMessage)
sets the public key for PKI (public key infrastructure). |
protected boolean |
interpretSetPkiEnvironment(Message currentMessage)
configures the PKI (public key infrastructure) environment within the lars-system |
protected boolean |
interpretSetPkiMessages(Message currentMessage)
Sets service(s) of messages which later have to be signed, verified, encrypted, decrypted, signed and encrypted, and decrypted and verified. |
protected boolean |
interpretSetPrivateKey(Message currentMessage)
sets the private key for PKI (public key infrastructure) to sign or encrypt contents |
protected boolean |
interpretSetRunLevel(Message currentMessage)
Sets the run level of this agent and answers with a "run_level_set" or "run_level_not_set" message. |
protected boolean |
interpretSignatureNotValid(Message currentMessage)
This method is automatically called if the signature verification fails. |
protected boolean |
interpretStartupConstraint(Message currentMessage)
registers to the AgentMessageRouter for getting notified when a given set of agents are available |
protected Map |
loadConfigFile(Object fileNameContainer)
Loads one or multiple configuration file(s) into a Map, if such config files exist and are readable. |
protected boolean |
performDefaultBehavior(Message currentMessage)
Performs this agent's default behavior for an incoming message. |
protected boolean |
reconnectAfterMigration()
reconnects an agent on a (guest) platform |
protected void |
registerInterpretMethods()
Registers non-standard message services and corresponding methods to interpret messages with that service. |
protected void |
registerInterpretMethods(String service,
Method method,
String substring)
Initializes, that when receiving a message with the given service, the specified method needs to be invoked. |
protected void |
registerInterpretMethods(String service,
String interpretMethodName)
Initializes, that when receiving a message with the given service, the specified method needs to be invoked. |
void |
reInitializeAction()
empty implementation Note for developers: This method gets called, before the config file is interpreted, but only if this agent inherits from com.ls.lars.mobility.AgentBasicMobility ! |
void |
setAgentMessageRouterName(String agentMessageRouterName)
Sets the name of the agentMessageRouter. |
protected void |
setIXMLHandler(IXMLHandler iXMLHandler)
sets the IXMLHandler to be utilized for reading config files |
protected void |
setLocalPlatform(String localPlatform)
sets the local agent platform's name |
protected boolean |
setPKIMessage(Map messageMap)
Sets a message-service which later have to be signed, verified, encrypted, decrypted, signed and encrypted, and decrypted and verified. |
boolean |
terminateAction()
Executes actions that have to be performed before the agent terminates. |
String |
toString()
returns a string representation of this agent |
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 |
protected static final boolean FULL_SERVICE_ACCESS
protected static final boolean NO_SERVICE_ACCESS
public static final int RUN_LEVEL_EMBRYONIC
public static final int RUN_LEVEL_INTERPRET_METHODS_REGISTERED
public static final int RUN_LEVEL_CONFIG_FILE_READ
public static final int RUN_LEVEL_ACTIONS_INITIALIZED
initializeAction()
methodpublic static final int RUN_LEVEL_CONFIG_FILE_INTERPRETED
public static final int RUN_LEVEL_POOL_INITIALIZED
public static final int RUN_LEVEL_RUNNING
public static final int RUN_LEVEL_STOPPED
executeWhileRunning()
will not be called any morepublic static final int RUN_LEVEL_TERMINATED
terminateAction()
methodprotected String revisionInformation
protected transient String localPlatform
protected transient String agentMessageRouterName
initializeMessages()
) or to register this agent as a service provider. The name of the
AgentMessageRouter instance should be "amr". Otherwise its name needs to be set in this agent by calling the
setAgentMessageRouterName() method in this agent's initializeAction() method.protected byte maxInvokeStackCounter
protected byte agentMinPool
protected byte agentMaxPool
protected DynamicObjectController dynamicObjectController
protected transient IXMLHandler iXMLHandlerForConfigLoader
protected boolean defaultServiceAccessPrivilege
protected String defaultServiceAccessPermission
Constructor Detail |
public AgentTemplate(String agentName, String homePlatform, List configFileNameList)
agentName
- name of the agent (example: xyz )homePlatform
- name of the homePlatform where the agent was created (example: 195.52.158.233-lars)configFileNameList
- list of config files to be read by the agent when it starts upMethod Detail |
public final String getAgentRevisionInformation()
getRevisionInformation()
will be used which
every agent has to overwrite.protected String getRevisionInformation()
// revision information string, managed by our version control system. protected String revisionInformation = "$Revision: 1.70 $"; // method to get the revision information protected String getRevisionInformation() { return revisionInformation; }Make sure that the variable and the method are in the agent.
protected final void setLocalPlatform(String localPlatform)
localPlatform
- the name of the local platform (example: 195.52.158.233/myLars)protected final void setIXMLHandler(IXMLHandler iXMLHandler)
iXMLHandler
- an instance of a class, implementing the IXMLHandlerpublic final void executeLifeCycle()
executeLifeCycle
in class CommunicationTemplate
protected final Map loadConfigFile(Object fileNameContainer) throws IllegalArgumentException
fileNameContainer
- if it is instance of String: name of one config file;
if it is instance of List: names (Strings) of multiple config filesIllegalArgumentException
- if is the fileNameContainer is neither a String nor a Listprotected void initializeAction()
Note for developers:
If you overwrite this method (e.g. because your agent needs special actions for its initialization like
opening files, creating threads, ...), be sure to call the super classes initializeAction() to assure proper
agent initialization!
This method gets called, before the config file is interpreted!
public void reInitializeAction()
Note for developers:
This method gets called, before the config file is interpreted, but only
if this agent inherits from com.ls.lars.mobility.AgentBasicMobility
!
protected void initializeMessages()
Note for developers:
If you overwrite this method, because your agent needs to send initialization messages to other agents,
be sure to call the super classes initializeMessages() to assure proper agent initialization!
This method gets called, after the config file got interpreted!
protected void executeWhileRunning()
interpret(com.ls.lars.communication.Message)
for that message.
Only if an agent needs to do additional tasks between receiving a message from the inbox and interpreting it, this method needs to be overwritten.
protected final boolean interpret(Message currentMessage)
IPKIHandler.doReceivingPKIHandling(com.ls.lars.communication.Message)
. PKIBaseException
), the appropriate
interpret-method is called (see below to understand, what is meant by "appropriate" in this context). performDefaultBehavior(com.ls.lars.communication.Message)
is called. If that returns false,
CommunicationTemplate.checkSendSystemReply(com.ls.lars.communication.Message, java.lang.String, int, java.lang.String)
is called.
Note:
Since lars v2.5 message services and the methods, that will interpret those services, need to be registered
at agent start up. As long as the message services are conform to the standard (they consist of lower case
words, that are separated by an underscore ("_") e.g. "set_constants") and the interpreting methods are
named "interpret", followed by the converted service name (according to the Java Style Guide, this means
capitalized words without underscores, e.g. "interpretSetConstants"), this registration is done
automatically. For non-standard message services, agents need to implement
registerInterpretMethods()
.
currentMessage
- message to be interpretedprotected boolean performDefaultBehavior(Message currentMessage)
currentMessage
- message with a service, where no corresponding interpretXXX() method is registered forpublic boolean terminateAction()
super.terminateAction()
terminateAction
in class CommunicationTemplate
protected boolean interpretSetRunLevel(Message currentMessage)
RUN_LEVEL_STOPPED
, terminateAction()
is executed, which then
decides, if the run level will be set to STOPPED or not.currentMessage
- message with a "set_run_level" requestprotected boolean interpretLoadObject(Message currentMessage)
dynamicObjectController
.
If a configuration is performed, depends on, if the new object implements
IConfigurable
. If yes,
configure(configuration)
with the given Map is
called on the new object. Note: This message will be interpreted only, if it was read from a config file.
Example:
currentMessage
- "load_object" messagedynamicObjectController
,
DynamicObjectController.loadObject(Object,String,Map)
protected boolean interpretDefineObject(Message currentMessage)
dynamicObjectController
.
(The configuration parameter is used at instantiation time to configure the defined object, see
DynamicObjectController.getInstanceFromDefined(java.lang.Object)
).
Note: This message will be interpreted only, if it was read from a config file.
Example:
currentMessage
- "define_object" messagedynamicObjectController
,
DynamicObjectController.defineObject(Object,String,Map)
protected boolean interpretPing(Message currentMessage)
currentMessage
- "ping" messageprotected boolean interpretMonitorLookup(Message currentMessage)
currentMessage
- "monitor_lookup" messageprotected boolean interpretSetLog(Message currentMessage)
currentMessage
- message that contains logFile and logLevel in its contentHashpublic final void setAgentMessageRouterName(String agentMessageRouterName)
agentMessageRouterName
- name of agentMessageRouter (how it is called on the localPlatform)protected boolean interpretRegisterService(Message currentMessage)
currentMessage
- Message containing the service(s) that should be registeredprotected boolean interpretGetRevisionInformation(Message currentMessage)
low priority
!currentMessage
- "get_revision_information" messageprotected boolean interpretLogInbox(Message currentMessage)
currentMessage
- (not evaluated)protected boolean interpretNotUnderstood(Message currentMessage)
currentMessage
- "not_understood" messageprotected boolean interpretDeliveryFailed(Message currentMessage)
currentMessage
- "delivery_failed" messageprotected boolean interpretAccessDenied(Message currentMessage)
currentMessage
- "access_denied" messageprotected boolean interpretInterpretationSuccessful(Message currentMessage)
currentMessage
- "interpretation_successful" messageprotected boolean interpretNotifiedAgent(Message currentMessage)
AgentTimer
).currentMessage
- "notified_agent" messageprotected boolean interpretNotifyCanceled(Message currentMessage)
AgentTimer
).currentMessage
- "notify_canceled" messageprotected boolean interpretNotifyNotCanceled(Message currentMessage)
AgentTimer
).currentMessage
- "notify_not_canceled" messageprotected boolean interpretCloseConnection(Message currentMessage)
currentMessage
- "close_connection" messageprotected IPKIHandler getIPKIHandler() throws PKIBaseException
PKIBaseException
- If a PKI-error occurs (the IPKIHandler wasn't instantiate before)protected boolean interpretSetPkiMessages(Message currentMessage)
currentMessage
- "set_messages"-messageprotected boolean setPKIMessage(Map messageMap) throws PKIBaseException
messageMap
- contains 'service' (the service which has to be set),
'pkiType' (the pki-type to which the service has to be set), ...PKIBaseException
- if a PKI-error occurs (no IPKIHandler instantiated before)protected boolean interpretSignatureNotValid(Message currentMessage)
currentMessage
- message to be interpretedprotected boolean interpretCheckRegisteredServices(Message currentMessage)
currentMessage
- message to be interpretedprotected boolean interpretSetOwnPublicKeyCertificate(Message currentMessage)
currentMessage
- "set_own_public_key_certificate"-messageprotected byte[] getOwnPublicKeyCertificate() throws PKIBaseException
PKIBaseException
- If a PKI error occurs (PublicKey Certificate wasn't set before)protected boolean interpretSetForeignPublicKeyCertificate(Message currentMessage)
currentMessage
- "set_foreign_public_key_certificate"-messageprotected boolean interpretSetPrivateKey(Message currentMessage)
currentMessage
- "set_private_key" messageprotected boolean interpretSetPkiEnvironment(Message currentMessage)
currentMessage
- "set_pki_environment" messageprotected final boolean interpretStartupConstraint(Message currentMessage)
currentMessage
- "startup_constraint" messageprotected boolean interpretAgentConnected(Message currentMessage)
Note for developers: As this implementation is absolutely necessary for solving startup constraints between multiple agents, it is absolutely necessary for inherited agents to call super.interpretAgentConnected(currentMessage) when overwriting this method with own implementations.
currentMessage
- "agent_connected" messageprotected final boolean interpretSetAccessPrivileges(Message currentMessage)
general
and the
specific
rulings. The general rulings are effected as long as no
specific rules for a defined service and a defined requestor do exist.currentMessage
- the incoming "define_access_ruling" messageprotected final boolean interpretSendAsConfigured(Message currentMessage)
content
tag of this
send_as_configured
message.currentMessage
- the "send_as_configured" messageprotected void registerInterpretMethods()
This method is intentionally left empty to achieve downward compatibility of lars v2.5 and higher to
lars v2.4: The agent programmer uses this method, to call registerInterpretMethods(String,String)
for registering message services, that do not fulfill the service standard.
Examples for a non-standard service would be: "do_Something" or "makeSomething_Else". To assure, that when
receiving a message with the service "do_Something", the method
protected boolean interpretDoSomething(Message)
is called, one would implement a
registerInterpretMethods() like:
protected void registerInterpretMethods() { super.registerInterpretMethods(); registerInterpretMethods("do_Something", "interpretDoSomething"); }
Note: Each registerInterpretMethods() implementation has to call the super.registerInterpretMethods() as first instruction, because all parent classes need to be able to register their own services and methods and if you want to override a method, the chronological order must be correct.
Note: If an agent does not use non-standard message services, there is no need to implement this method.
protected final void registerInterpretMethods(String service, Method method, String substring)
service
- service of a Message
method
- method to be invoked when receiving a message with given servicesubstring
- substring of method name to identify if this service should be
interpreted as a synchronized messageprotected final void registerInterpretMethods(String service, String interpretMethodName)
registerInterpretMethods(String,Method,String)
is called.service
- service of a Message
interpretMethodName
- name of the method that shall be invokedprotected boolean reconnectAfterMigration()
reconnectAfterMigration
in class CommunicationTemplate
public String toString()
toString
in class Thread
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |