systemic.sif.sifcommon.agent
Class SIFBaseAgent

java.lang.Object
  extended by openadk.library.Agent
      extended by systemic.sif.sifcommon.agent.SIFBaseAgent
Direct Known Subclasses:
SIFCommonAgent

public abstract class SIFBaseAgent
extends openadk.library.Agent

This class forms the base of all agents developed with the SIFCommon Framework. An agent implementation should extend this class and implement the abstract classes. In most cases nothing else needs to be changes but there is the occasional time where there is the need to override a particular behaviour (ie. change the way logging is initialised, how to deal with custom objects etc).

It is not recommended to override any other method since this class builds up the relationship between subscribers and publishers that make up an agent, all driven by the SIFAgent.properties file.

Author:
Joerg Huber

Field Summary
 
Fields inherited from class openadk.library.Agent
LOG_IDENTIFIER
 
Constructor Summary
SIFBaseAgent(java.lang.String agentID)
          Constructor.
SIFBaseAgent(java.lang.String agentID, java.lang.String propertiesFileName)
          Constructor.
 
Method Summary
 openadk.library.tools.cfg.AgentConfig getAgentConfig()
          This methods gets all properties from the actual agent.cfg file.
 java.lang.String getAgentID()
           
 openadk.library.tools.mapping.Mappings getAgentMappings()
           
 openadk.library.AgentProperties getAgentProperties()
          This method returns the agent's property values for the agent configuration file (generally called SIFAgent.properties).
 SIFCommonProperties getFrameworkProperties()
           
 java.lang.String getHomeDir()
          Ensure that a known directory is used as the working directory.
 java.util.List<BasePublisher> getInitialisedPublishers()
          This method returns all publishers that are initialise (after startAgent() call).
 java.util.List<BaseSubscriber> getInitialisedSubscribers()
          This method returns all subscribers that are initialise (afterstartAgent() call).
 openadk.library.tools.mapping.Mappings getMappings(java.lang.String mappingID)
          This method return mappings for the given mapping ID of the agent's configuration file.
 java.util.List<openadk.library.Zone> getZones()
          Returns the list of Zones this agent is connected to.
abstract  void initCustomObjects()
          This method initialises custom objects that have been created with Pearson's ADKGen.
 void setAgentID(java.lang.String agentID)
           
 void setAgentMappings(openadk.library.tools.mapping.Mappings mappings)
           
 void setFrameworkProperties(SIFCommonProperties frameworkProperties)
           
 void startAgent()
          Convenience method.
 void startAgent(boolean implementShutdownHook)
          Convenience method.
 void startAgent(boolean implementShutdownHook, java.util.Collection<BasePublisher> publishers, java.util.Collection<BaseSubscriber> subscribers)
          This method starts the agent.
 void startAgent(java.util.Collection<BasePublisher> publishers, java.util.Collection<BaseSubscriber> subscribers)
          Same as above method except that shutdown hook is defaulted to true.
 void stopAgent()
          This method must be called to shut down the agent in full and release all resources.
 
Methods inherited from class openadk.library.Agent
addMessagingListener, getConfigurationSource, getDefaultHttpProperties, getDefaultHttpsProperties, getDefaultTransportProperties, getDefaultZoneProperties, getErrorHandler, getId, getLog, getLog, getMessagingListeners, getName, getProperties, getPublisher, getQueryResults, getReportPublisher, getServerLog, getServerLog, getSubscriber, getThreadPoolManager, getTopicFactory, getTransportManager, getZoneFactory, initialize, isInitialized, isShutdown, makeGUID, purgeQueue, removeMessagingListener, setConfigurationSource, setErrorHandler, setId, setName, setPublisher, setPublisher, setQueryResults, setQueryResults, setReportPublisher, setSubscriber, setSubscriber, shutdown, shutdown, sleep, wakeup
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SIFBaseAgent

public SIFBaseAgent(java.lang.String agentID,
                    java.lang.String propertiesFileName)
             throws java.lang.Exception
Constructor. This creates an SIF agent object with an id of 'agentID'. The passed in 'propertiesFileName' is used to read environmental data for the agent. Note only the file name without the extension of '.properties' is required. The properties for various agents can use the same property file. The properties for each agent are identified by the property name that holds the 'agentID' as part of it:

agent..some.property=value

This method will initialise the agent but won't connect it to any ZIS. To connect it to any ZIS listed in the agent's config file the startAgent method must be called.

Parameters:
agentID - The unique ID of this Agent. This should be the same value as in the agent id reference in the SIFAgent.propertiess file.
propertiesFileName - The name of the SIFAgent.properties file
Throws:
java.lang.Exception

SIFBaseAgent

public SIFBaseAgent(java.lang.String agentID)
             throws java.lang.Exception
Constructor. Convenience method to above. It assumes that the properties file name is 'SIFAgent.properties'.

Parameters:
agentID -
Throws:
java.lang.Exception
Method Detail

initCustomObjects

public abstract void initCustomObjects()
This method initialises custom objects that have been created with Pearson's ADKGen. Generally that would look something like this:

CustomObjectDTD customObjects = new CustomObjectDTD();
customObjects.load();

If there are no custom objects then this method can be nulled out. This method will be called as part of the constructor of this class.


getAgentID

public java.lang.String getAgentID()

setAgentID

public void setAgentID(java.lang.String agentID)

getFrameworkProperties

public SIFCommonProperties getFrameworkProperties()

setFrameworkProperties

public void setFrameworkProperties(SIFCommonProperties frameworkProperties)

getInitialisedSubscribers

public java.util.List<BaseSubscriber> getInitialisedSubscribers()
This method returns all subscribers that are initialise (afterstartAgent() call). It is assumed that the subscribers are initialised using this framework and therefore should be identical to the list of subscribers in the SIFAgent.properties file.

Returns:
See description.

getInitialisedPublishers

public java.util.List<BasePublisher> getInitialisedPublishers()
This method returns all publishers that are initialise (after startAgent() call). It is assumed that the publishers are initialised using this framework and therefore should be identical to the list of publishers in the SIFAgent.properties file.

Returns:
See description.

getAgentMappings

public openadk.library.tools.mapping.Mappings getAgentMappings()

setAgentMappings

public void setAgentMappings(openadk.library.tools.mapping.Mappings mappings)

startAgent

public void startAgent(boolean implementShutdownHook,
                       java.util.Collection<BasePublisher> publishers,
                       java.util.Collection<BaseSubscriber> subscribers)
                throws java.lang.Exception
This method starts the agent. It connects to all required zones and events, request and queries as described in the agent config file.

NOTE: The publishers will be assigned this agent in each BasePublisher object as part of this call. The subscribers will be assigned this agent in each BaseSubscriber object as part of this call.

Parameters:
implementShutdownHook - If set to true then a shotdownHook is installed that captures the CTRL-C to terminate the agent
publishers - A list of publishers that are registered with the zones of this agent
subscribers - A list of subscribers that are registered with the zones of this agent
Throws:
java.lang.Exception - An underlying issue such as failing to initialise the publishers, subscribers etc. An error is logged and an appropriate message is stored in the exception.

startAgent

public void startAgent(java.util.Collection<BasePublisher> publishers,
                       java.util.Collection<BaseSubscriber> subscribers)
                throws java.lang.Exception
Same as above method except that shutdown hook is defaulted to true. Most agent would use this method.

Throws:
java.lang.Exception

startAgent

public void startAgent()
                throws java.lang.Exception
Convenience method. It will start the agent with shutdown hook defaulted to true and call the getPublishers() and getSubscribers() automatically.

Throws:
java.lang.Exception
See Also:
getPublishers(), getSubscribers()

startAgent

public void startAgent(boolean implementShutdownHook)
                throws java.lang.Exception
Convenience method. It will start the agent with shutdown hook set as given by the parameter and call the getPublishers() and getSubscribers() automatically.

Throws:
java.lang.Exception
See Also:
getPublishers(), getSubscribers()

stopAgent

public void stopAgent()
This method must be called to shut down the agent in full and release all resources. Ideally it is called in a 'finally' block of the agent executable to guarantee that the stopAgent() method is called in all cases.


getAgentProperties

public openadk.library.AgentProperties getAgentProperties()
This method returns the agent's property values for the agent configuration file (generally called SIFAgent.properties). The agent configuration file is identified by the following properties in the 'propertiesFileName' passed to the constructor of this class:

agent._agenttID_.cfg.location=_dir_of_config_file_
agent._agenttID_.cfg.name=_name_of_config_file_

Returns:
See description.

getAgentConfig

public openadk.library.tools.cfg.AgentConfig getAgentConfig()
This methods gets all properties from the actual agent.cfg file.

Returns:
See description

getMappings

public openadk.library.tools.mapping.Mappings getMappings(java.lang.String mappingID)
This method return mappings for the given mapping ID of the agent's configuration file. If no such mapping exists or the retrieval of the mappings caused an error then the error is logged and null is returned.

Parameters:
mappingID - The ID for which the mappings shall be returned.
Returns:
See description.

getZones

public java.util.List<openadk.library.Zone> getZones()
Returns the list of Zones this agent is connected to.

Returns:
List of zones.

getHomeDir

public java.lang.String getHomeDir()
Ensure that a known directory is used as the working directory. If the value is not set the default is used which generally is the directory where the agent is started from.

Overrides:
getHomeDir in class openadk.library.Agent