com.ls.lars.communication
Class MessageRouter

java.lang.Object
  |
  +--com.ls.lars.communication.MessageRouter

public class MessageRouter
extends Object

This class is managing all messengers of the agents and has methods for the routing of messages

Version:
$Revision: 1.32 $
Author:
Last modified by $Author: MHeitz $

Field Summary
protected static String SERVICE_PROVIDER_RANGE_DECREASED
          Constants specifying that the number of providers for a service has decreased
protected static String SERVICE_PROVIDER_RANGE_INCREASED
          Constants specifying that the number of providers for a service has increased
 
Method Summary
 boolean addAgentToWatch(String connectedAgent)
          Adds an agent to the list of watched agents, i.e. when that agent gets connected the AgentMessageRouter will be notified about that.
 boolean addForward(String agentName, String amrForward)
          adds a forward to an agent to the forward list
 boolean addMessenger(String agentName, com.ls.lars.communication.Messenger messenger)
          Adds a messenger of an agent to the list of messengers.
 boolean addPlatform(String platform, String ip, int port)
          adds a platform to the list of connected platforms
 void allMessengersCloseConnection()
          sends a 'close_connection' message to all connected messengers
 void controlInboxSize(int delimiter)
          Checks the size of the inbox of all known messengers, whether or not the given delimiter is reached.
static void createMessageRouter(String theLocalIpAddress, String theHomePlatform)
          creates the message router of this platform
 void deregisterFromServiceStatusChangedNotification(String agent)
          Deregisters the given agent from getting notified on the status changing of any service
 Set getAllMessageGroupMemberNames()
          returns a set of the names of all agents, that are currently subscribed to any message group
 Set getAllServiceProviderNames()
          returns a set of the names of all agents, that are currently registered as a service provider for any service
 Collection getGroupMembers(String groupName)
          returns the collection of names of all agents, that are subscribed to the specified message
static String getHomePlatform()
          returns the name of the local platform
static String getLocalIpAddress()
          returns the IP address of the local platform
 com.ls.lars.communication.Messenger getMessenger(String messengerName)
          returns the object reference of a messenger given the name of the messenger
static MessageRouter getPlatformMessageRouter()
          returns the message router of this platform
 Collection getServiceProviderMembers(String serviceName)
          returns the names, as a HashSet, of the agents that are regitered for a service specified by the parameter
 boolean isAvailable(String agentName)
          Checks, if a messenger entry already exists for the passed agent name.
 Set listAllProvidedServices()
          Returns a list of all services, which are currently provided on this platform.
 Map listPlatforms()
          returns a list of all platforms to which this platform is connected...
 void registerForServiceStatusChangedNotification(String service, String agent, String replyId)
          Registers the given agent for getting notified when the status of the given service changes (e.g. the service becomes available or unavailable)
 void registerService(Object service, String agentName)
          adds an agent to the list(s) of service providers for the specified service(s)
 boolean removeAgentToWatch(String connectedAgent)
          Removes an agent from the list of watched agents.
 boolean removeForward(String agentName)
          removes the forward for the passed agent name from the forward list
 void removeMessageGroup(String groupName)
          Removes a complete message group.
 boolean removeMessenger(String agentName)
          Removes the messenger entry for the passed agent name from the list of messengers.
 boolean removePlatform(String platformName)
          removes the platform entry for the passed platform name
 void routeMessage(GroupMessage message)
          Sends given message to all agents of a message group (the groupname specifies the recipients of the message).
 void routeMessage(Message message)
          Routes a message from the sender messenger to the receiver messenger.
 void routeMessage(MulticastMessage message)
          Sends given message to all agents from the list of the receivers.
 void routeMessage(ServiceBroadcastMessage message)
          Sends given message to all known providers of the requested service (the service is the subject of the message) Failure behaviour: An error with reason QualityOfService.QOS_SERVICE_NOT_REGISTERED is produced, if the service is known, but no service providers are registered.
 void routeMessage(ServiceSingleMessage message)
          Sends given message to all known providers of the requested service (the service is the subject of the message) Failure behaviour: An error with reason QualityOfService.QOS_SERVICE_NOT_REGISTERED is produced, if the service is known, but no service providers are registered.
 void routeMessage(SingleMessage message)
          routes a message from the sender messenger to the receiver messenger
 void setEncapsulatingAgentName(String agentName)
          sets the name of the agent, which encapsulates this message router (i.e. the agent, which adds agent behavior to the message router)
 void subscribeToMessageGroup(String groupName, Object agentNames, boolean isTransaction)
          adds an agent to a message group
 String toString()
          returns a string representation of this message router containing if system log level is TRACE5: all registered messengers (take care: includes all messages in the inboxes) if system log level is TRACE5: all known forwards all known platforms all known services
 void unregisterAllServices(String agentName)
          removes an agent from all service provider lists
 void unregisterService(Object service, String agentName)
          removes an agent from the specifed service provider list(s)
 void unsubscribeFromAllMessageGroups(String agentName)
          Removes an agent from all message groups it is subscribed to.
 void unsubscribeFromMessageGroup(String groupName, Object agentName)
          Removes an agent from the specified message group.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SERVICE_PROVIDER_RANGE_INCREASED

protected static final String SERVICE_PROVIDER_RANGE_INCREASED
Constants specifying that the number of providers for a service has increased

SERVICE_PROVIDER_RANGE_DECREASED

protected static final String SERVICE_PROVIDER_RANGE_DECREASED
Constants specifying that the number of providers for a service has decreased
Method Detail

isAvailable

public boolean isAvailable(String agentName)
Checks, if a messenger entry already exists for the passed agent name.
Parameters:
agentName - name of the agent
Returns:
true, if a messenger entry already exists for the agent name

addAgentToWatch

public boolean addAgentToWatch(String connectedAgent)
Adds an agent to the list of watched agents, i.e. when that agent gets connected the AgentMessageRouter will be notified about that.
Parameters:
connectedAgent - name of the agent, which connection is awaited
Returns:
true, if the connectedAgent has been added successfully

removeAgentToWatch

public boolean removeAgentToWatch(String connectedAgent)
Removes an agent from the list of watched agents.
Parameters:
connectedAgent - name of the agent, which shall be removed
Returns:
true, when the connectedAgent has been removed successfully

addMessenger

public boolean addMessenger(String agentName,
                            com.ls.lars.communication.Messenger messenger)
Adds a messenger of an agent to the list of messengers.
Parameters:
agentName - name of the agent to which the messenger belong
messenger - Messenger that has to be added.
Returns:
true, if the messenger was added successfully; false, if the agent name already exists.

removeMessenger

public boolean removeMessenger(String agentName)
Removes the messenger entry for the passed agent name from the list of messengers. If that succeeds, it unregisters the given agent name as service provider and removes it from all message groups, where it is registered to.
Parameters:
agentName - agent name for which the messenger entry has to be removed
Returns:
true, if the messenger is removed successfully; false else

controlInboxSize

public void controlInboxSize(int delimiter)
Checks the size of the inbox of all known messengers, whether or not the given delimiter is reached. If so, the method logs a warning into the systems log file.
Parameters:
delimiter - the delimiter to check against

allMessengersCloseConnection

public void allMessengersCloseConnection()
sends a 'close_connection' message to all connected messengers

addForward

public boolean addForward(String agentName,
                          String amrForward)
adds a forward to an agent to the forward list
Parameters:
agentName - name of the agent to which the messenger belongs
amrForward - address of the agent message router where the agent is currently located
Returns:
false, if a forward entry already exists; true else

removeForward

public boolean removeForward(String agentName)
removes the forward for the passed agent name from the forward list
Parameters:
agentName - agent name for which the messenger entry has to be removed
Returns:
true, if the forward is removed successfully; false else

addPlatform

public boolean addPlatform(String platform,
                           String ip,
                           int port)
adds a platform to the list of connected platforms
Parameters:
platform - Name of the platform for which a entry should be added
ip - IP address of the platform
port - port number of the platform
Returns:
true, if the platform was added successfully; false, if the platform already exists

removePlatform

public boolean removePlatform(String platformName)
removes the platform entry for the passed platform name
Parameters:
platformName - name of the platform which entry has to be removed from the known platforms
Returns:
true, if the platform is removed successfully; false else

listPlatforms

public Map listPlatforms()
returns a list of all platforms to which this platform is connected...
Returns:
the list as map or null, if no platforms are known

registerService

public void registerService(Object service,
                            String agentName)
                     throws ServiceException
adds an agent to the list(s) of service providers for the specified service(s)
Parameters:
service - String or List containing the service(s), for that the agent wants to be registered as a service provider
agentName - name of the service provider agent
Throws:
ServiceException - if service is null or if service is neither instance of String nor instance of Collection

getServiceProviderMembers

public Collection getServiceProviderMembers(String serviceName)
returns the names, as a HashSet, of the agents that are regitered for a service specified by the parameter
Parameters:
serviceName - name of the service
Returns:
the collection of agents registered as provider for the specified service (empty, if the service is unknown or has no providers)

getMessenger

public com.ls.lars.communication.Messenger getMessenger(String messengerName)
returns the object reference of a messenger given the name of the messenger
Parameters:
messengerName - name of the messenger
Returns:
returns the object reference of a messenger given the name of the messenger.

unregisterAllServices

public void unregisterAllServices(String agentName)
                           throws ServiceException
removes an agent from all service provider lists
Parameters:
agentName - Name of the agent that has to be removed from the subscriber lists
Throws:
ServiceException - if agentName is null or empty

unregisterService

public void unregisterService(Object service,
                              String agentName)
                       throws ServiceException
removes an agent from the specifed service provider list(s)
Parameters:
service - String or List of Strings specifying the services, for which the agent does not want to be a provider any more
agentName - Name of the agent that has to be removed from the subscriber lists
Throws:
ServiceException - if agentName is null or empty or if service is null or if service is neither instance of String nor instance of Collection

getAllServiceProviderNames

public Set getAllServiceProviderNames()
returns a set of the names of all agents, that are currently registered as a service provider for any service
Returns:
set of the names of all agents, that are currently registered as a service provider for any service

registerForServiceStatusChangedNotification

public void registerForServiceStatusChangedNotification(String service,
                                                        String agent,
                                                        String replyId)
Registers the given agent for getting notified when the status of the given service changes (e.g. the service becomes available or unavailable)
Parameters:
service - the name of the service to watch
agent - the name of the registering agent
replyId - the id to be used when notifying the agent

deregisterFromServiceStatusChangedNotification

public void deregisterFromServiceStatusChangedNotification(String agent)
Deregisters the given agent from getting notified on the status changing of any service
Parameters:
agent - the name of the deregistered agent

listAllProvidedServices

public Set listAllProvidedServices()
Returns a list of all services, which are currently provided on this platform.
Returns:
list of all provided services, null if no services are provided

subscribeToMessageGroup

public void subscribeToMessageGroup(String groupName,
                                    Object agentNames,
                                    boolean isTransaction)
                             throws ServiceException
adds an agent to a message group
Parameters:
groupName - name of the group to subscribe to
agentNames - String or Collection containing a single or multiple agent names
isTransaction - if true, the subscription of a collection of agent names to a message group is a transaction: all of the agents are added to the group or none of them; if false, as many agents (contained in agentNames) as possible are added
Throws:
ServiceException - if groupName is null or if agentName is neither a String nor a Collection

getGroupMembers

public Collection getGroupMembers(String groupName)
returns the collection of names of all agents, that are subscribed to the specified message
Parameters:
groupName - the name of the group
Returns:
the collection of agents from a group (empty, if the group is unknown or has no subscribers)

unsubscribeFromAllMessageGroups

public void unsubscribeFromAllMessageGroups(String agentName)
                                     throws ServiceException
Removes an agent from all message groups it is subscribed to.
Parameters:
agentName - name of the agent that has to be removed from the message group
Throws:
ServiceException - if agentName is null or empty

unsubscribeFromMessageGroup

public void unsubscribeFromMessageGroup(String groupName,
                                        Object agentName)
                                 throws ServiceException
Removes an agent from the specified message group.
Parameters:
groupName - name of the group to subscribe to
agentName - String or collection containing a single or multiple agent names
Throws:
ServiceException - if groupName is null or no valid group name or agentName is neither a String nore a Collection

removeMessageGroup

public void removeMessageGroup(String groupName)
                        throws ServiceException
Removes a complete message group.
Parameters:
groupName - name of the message group that is removed
Throws:
ServiceException - if groupName is null or empty

getAllMessageGroupMemberNames

public Set getAllMessageGroupMemberNames()
returns a set of the names of all agents, that are currently subscribed to any message group
Returns:
set of the names of all agents, that are currently subscribed to any message group

createMessageRouter

public static void createMessageRouter(String theLocalIpAddress,
                                       String theHomePlatform)
creates the message router of this platform
Parameters:
theLocalIpAddress - IP address of the local platform
theHomePlatform - name of the local platform
See Also:
#getMessageRouter

getPlatformMessageRouter

public static MessageRouter getPlatformMessageRouter()
                                              throws SecurityException
returns the message router of this platform
Returns:
reference to the message router of this platform; null, if such a thing is not initialized (because no lars platform is running)
Throws:
SecurityException - if the caller of this method is not allowed to get a reference to the platform's message router

setEncapsulatingAgentName

public void setEncapsulatingAgentName(String agentName)
sets the name of the agent, which encapsulates this message router (i.e. the agent, which adds agent behavior to the message router)
Parameters:
agentName - the name of the encapsulating agent

routeMessage

public void routeMessage(Message message)
                  throws UnsupportedOperationException
Routes a message from the sender messenger to the receiver messenger. Supported message types are: SingleMessage, ServiceBroadcastMessage, ServiceSingleMessage, GroupMessage, MulticastMessage.

Failure behaviour:

Programming tip: If you know the type of a message object at point of calling routeMessage, always cast the Message object yourself to avoid the determination of the type at runtime.

Parameters:
message - message to be routed
Throws:
UnsupportedOperationException - if message type is unsupported

routeMessage

public void routeMessage(SingleMessage message)
routes a message from the sender messenger to the receiver messenger
Parameters:
message - Message to be routed

routeMessage

public void routeMessage(ServiceSingleMessage message)
Sends given message to all known providers of the requested service (the service is the subject of the message) Failure behaviour:
Parameters:
message - message that has to be passed to all known service providers

routeMessage

public void routeMessage(ServiceBroadcastMessage message)
Sends given message to all known providers of the requested service (the service is the subject of the message)

Failure behaviour:

Parameters:
message - message that has to be passed to all known service providers

routeMessage

public void routeMessage(GroupMessage message)
Sends given message to all agents of a message group (the groupname specifies the recipients of the message).

Failure behaviour:

Parameters:
message - message that has to be passed to all agents of the group

routeMessage

public void routeMessage(MulticastMessage message)
Sends given message to all agents from the list of the receivers.
Parameters:
message - message that has to be passed to all agents from he list of receivers

getLocalIpAddress

public static String getLocalIpAddress()
returns the IP address of the local platform
Returns:
IP address of the local platform (null, if not initialized from lars.cfg)

getHomePlatform

public static String getHomePlatform()
returns the name of the local platform
Returns:
name of the local platform

toString

public String toString()
returns a string representation of this message router containing
Overrides:
toString in class Object
Returns:
all notification requests as a string