org.objectweb.mobilitools.smi.goodies
Class RegionManager

java.lang.Object
  |
  +--org.objectweb.mobilitools.smi.goodies.RegionManager

public class RegionManager
extends java.lang.Object

MobiliTools $Name: $, $Id: RegionManager.java,v 1.1.1.1 2003/03/28 14:48:06 dillense Exp $

A RegionManager instance makes it possible to deploy and manage agents, as well as lookup agents and agent systems, through the MAF infrastructure (i.e. implementations of MAFAgentSystem and MAFFinder interfaces). Localization of MAFAgentSystem and MAFFinder servers is based on the CORBA naming service. If one naming service is running for each region, then regions must be interconnected by federating the naming services in the naming context of region name bindings.
RegionManager can also be run as a standalone programme in order to create a set of agents in various existing agencies, by specifying a property file or XML file where all necessary definitions will be read from.


Constructor Summary
RegionManager()
           
RegionManager(org.omg.CORBA.ORB orb)
           
 
Method Summary
 Name createAgent(Location location, java.lang.String classname, java.lang.String codebase, Name name, java.lang.String place, org.omg.CfMAF.AgentProfile profile, java.io.Serializable agent_data, java.lang.Object argObj)
          Creates an agent at the specified agent system location.
 Name createAgent(java.lang.String region, Name agency, java.lang.String classname, java.lang.String codebase, Name name, java.lang.String place, org.omg.CfMAF.AgentProfile profile, java.io.Serializable agent_data, java.lang.Object[] arguments)
          Creates an agent in the named agency of the specified region.
 void deploy(java.util.Properties props)
          Performs agent creations specified by the provided properties.
 void deployFromPropFile(java.lang.String file)
          Parses the specified property file in order to make the specified agent creations.
 void deployFromXMLFile(java.lang.String file)
          Parses the specified XML file in order to make the specified agent creations.
 Location findAgency(java.lang.String region, Name agency)
           
 Location findAgent(java.lang.String region, Name agent)
           
 java.util.Properties getAgentProperties(java.lang.String region, Name name)
           
 boolean isRunning(Location location, Name agent)
           
 boolean isRunning(java.lang.String region, Name agent)
           
 Location[] listAgencies(java.lang.String region, java.util.Properties properties)
           
 Location[] listAgentLocations(java.lang.String region, java.util.Properties properties)
           
 Name[] listAgentNames(java.lang.String region, java.util.Properties properties)
           
 Name[] listAgentsIn(Location location)
           
 Name[] listAgentsIn(Location location, org.omg.CfMAF.AgentProfile profile)
           
static void main(java.lang.String[] args)
          Creates/deploys agents in existing agencies, from definitions read from a property file or an XML file.
 void moveAgent(Location from_location, Name agent, Location to_location, java.lang.String place)
          Moves an agent to the specified location.
 void moveAgent(java.lang.String from_region, Name agent, java.lang.String to_region, Name to_agency, java.lang.String place)
          Moves an agent to the named agency in the specified region.
 void resumeAgent(Location location, Name agent)
          Resumes the activity of the specified agent residing at the specified location.
 void resumeAgent(java.lang.String region, Name agent)
          Resumes the activity of the specified agent in the specified region.
 void suspendAgent(Location location, Name agent)
          Suspends the activity of the specified agent residing at the specified location.
 void suspendAgent(java.lang.String region, Name agent)
          Suspends the activity of the specified agent in the specified region.
 void terminateAgency(Location location)
          Terminates the specified agency in the specified region.
 void terminateAgency(java.lang.String region, Name agency)
          Terminates the specified agency in the specified region.
 void terminateAgent(Location location, Name agent)
          Terminates the specified agent in the specified region.
 void terminateAgent(java.lang.String region, Name agent)
          Terminates the specified agent in the specified region.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RegionManager

public RegionManager(org.omg.CORBA.ORB orb)
              throws BadOperation

RegionManager

public RegionManager()
              throws BadOperation
Method Detail

main

public static void main(java.lang.String[] args)
Creates/deploys agents in existing agencies, from definitions read from a property file or an XML file.
Parameters:
args - shall contain ORB-specific switches first, and then either -xml xml_file or -prop property_file switch.
See Also:
deployFromPropFile(String), deployFromXMLFile(String)

deployFromXMLFile

public void deployFromXMLFile(java.lang.String file)
                       throws java.lang.Exception
Parses the specified XML file in order to make the specified agent creations. This file should contain DEPLOY tags, embracing AGENT tags. If both tags, attributes name, region, agency, place, class, codebase, and arguments may be defined. When an attribute is defined in DEPLOY tag, then its value is the default value for every enclosed AGENT tag.
Parameters:
file - the name of the XML file to be parsed.
Throws:
java.lang.Exception - a variety of exceptions if a parsing error occurs, because of an invalid file format (check the XML content)

deployFromPropFile

public void deployFromPropFile(java.lang.String file)
                        throws java.io.IOException
Parses the specified property file in order to make the specified agent creations.
Parameters:
file - the name of the property file to be parsed.
Throws:
java.io.IOException - if the specified file could not be read.
See Also:
deploy(Properties)

deploy

public void deploy(java.util.Properties props)
Performs agent creations specified by the provided properties. Properties are: Where n increments from 1 and stops as soon as property name.n is undefined. Any of these properties but name.n may be given a default value for every agent by omitting ".n" suffix.

createAgent

public Name createAgent(java.lang.String region,
                        Name agency,
                        java.lang.String classname,
                        java.lang.String codebase,
                        Name name,
                        java.lang.String place,
                        org.omg.CfMAF.AgentProfile profile,
                        java.io.Serializable agent_data,
                        java.lang.Object[] arguments)
                 throws BadOperation
Creates an agent in the named agency of the specified region. The specified agent system is its own class provider.
Parameters:
region - region name
agency - name wrapper for agency MAF name
classname - the agent main class name.
codebase - the codebase for loading the agent classes (interpreted by the specified agent system).
name - the name of the new agent.
place - the name of place where the agent will be located.
profile - new agent profile. The agent type must be compatible with the agent system type of the target agent system.
agent_data - serializable object that will be passed as an argument to the afterBirth() agent method, unless the arguments parameter is not null.
arguments - array of arguments that will be passed as an argument to the afterBirth() agent method. Arguments must be Strings or object wrappers for Java primitive types. If this parameter is null, then the agent_data parameter is considered instead.
Returns:
the actual name of the new agent, or null if the agent creation failed because the location could not be resolved.
Throws:
BadOperation - agent creation failed.
See Also:
MobileObject.afterBirth(AgentSystem, AgentInfo, Object)

createAgent

public Name createAgent(Location location,
                        java.lang.String classname,
                        java.lang.String codebase,
                        Name name,
                        java.lang.String place,
                        org.omg.CfMAF.AgentProfile profile,
                        java.io.Serializable agent_data,
                        java.lang.Object argObj)
                 throws BadOperation
Creates an agent at the specified agent system location. The specified agent system is its own class provider.
Parameters:
location - agent system location where the agent must me created.
classname - the agent main class name.
codebase - the codebase for loading the agent classes (interpreted by the specified agent system).
name - the name of the new agent.
place - the name of place where the agent will be located.
profile - new agent profile. The agent type must be compatible with the agent system type of the target agent system.
agent_data - serializable object that will be passed as an argument to the afterBirth() agent method, unless the arguments parameter is not null.
arguments - array of arguments that will be passed as an argument to the afterBirth() agent method. Arguments must be Strings or object wrappers for Java primitive types. If this parameter is null, then the agent_data parameter is considered instead.
Returns:
the actual name of the new agent, or null if the agent creation failed because the location could not be resolved.
Throws:
BadOperation - agent creation failed.
See Also:
MobileObject.afterBirth(AgentSystem, AgentInfo, Object)

moveAgent

public void moveAgent(java.lang.String from_region,
                      Name agent,
                      java.lang.String to_region,
                      Name to_agency,
                      java.lang.String place)
               throws BadOperation
Moves an agent to the named agency in the specified region.
Parameters:
from_region - the name of the region the agent is currently residing in.
agent - the name of the agent.
to_region - the destination region.
to_agency - the name of the destination agency in the given destination region.
place - the destination place.
Throws:
BadOperation - agent move has failed.

moveAgent

public void moveAgent(Location from_location,
                      Name agent,
                      Location to_location,
                      java.lang.String place)
               throws BadOperation
Moves an agent to the specified location.
Parameters:
from_location - current agent location.
agent - the name of the agent.
to_location - the destination location.
place - the destination place.
Throws:
BadOperation - agent move has failed.

resumeAgent

public void resumeAgent(java.lang.String region,
                        Name agent)
                 throws BadOperation
Resumes the activity of the specified agent in the specified region.
Parameters:
region - the name of the region where the agent is residing.
agent - the name wrapper of the agent MAF name.
Throws:
BadOperation - either the agent was already running, or its resumption failed.

resumeAgent

public void resumeAgent(Location location,
                        Name agent)
                 throws BadOperation
Resumes the activity of the specified agent residing at the specified location.
Parameters:
location - agent location.
agent - the name wrapper of the agent MAF name.
Throws:
BadOperationeither - the agent was already running, or its resumption failed.

suspendAgent

public void suspendAgent(java.lang.String region,
                         Name agent)
                  throws BadOperation
Suspends the activity of the specified agent in the specified region.
Parameters:
region - the name of the region where the agent is residing.
agent - the name wrapper of the agent MAF name.
Throws:
BadOperation - either the agent was already suspended, or it could not be suspended.

suspendAgent

public void suspendAgent(Location location,
                         Name agent)
                  throws BadOperation
Suspends the activity of the specified agent residing at the specified location.
Parameters:
location - agent location.
agent - the name wrapper of the agent MAF name.
Throws:
BadOperation - either the agent was already suspended, or it could not be suspended.

isRunning

public boolean isRunning(java.lang.String region,
                         Name agent)
                  throws BadOperation
Parameters:
region - the name of the region where the agent is residing.
agent - wrapper of the agent MAF name.
Returns:
true if the specified agent in the specified region is currently active.
Throws:
BadOperation - could not get agent activity status.

isRunning

public boolean isRunning(Location location,
                         Name agent)
                  throws BadOperation
Parameters:
location - agent location.
agent - the name wrapper of the agent MAF name.
Returns:
true if the specified agent in the specified region is currently active.
Throws:
BadOperation - could not get agent activity status.

terminateAgent

public void terminateAgent(java.lang.String region,
                           Name agent)
                    throws BadOperation
Terminates the specified agent in the specified region.
Parameters:
region - the name of the region where the agent is residing.
agent - the name wrapper of the agent MAF name.
Throws:
BadOperation -  

terminateAgent

public void terminateAgent(Location location,
                           Name agent)
                    throws BadOperation
Terminates the specified agent in the specified region.
Parameters:
location - agent location.
agent - the name wrapper of the agent MAF name.
Throws:
BadOperation -  

terminateAgency

public void terminateAgency(java.lang.String region,
                            Name agency)
                     throws BadOperation
Terminates the specified agency in the specified region.
Parameters:
region - the name of the region where the agency belongs to.
agency - wrapper of the agency MAF name.
Throws:
BadOperation - agency could not be terminated.

terminateAgency

public void terminateAgency(Location location)
                     throws BadOperation
Terminates the specified agency in the specified region.
Parameters:
location - agency location.
Throws:
BadOperation - agency could not be terminated

listAgentLocations

public Location[] listAgentLocations(java.lang.String region,
                                     java.util.Properties properties)
                              throws BadOperation
Parameters:
region - target region
properties - agent properties to match; may be null if all agents are wanted.
Returns:
an array of agency locations where agents matching the specified properties reside, in the specified region. This array is zero-sized if no agent matches the given properties (or if there is no agent at all).
Throws:
BadOperation - could not get list of agent location

listAgentNames

public Name[] listAgentNames(java.lang.String region,
                             java.util.Properties properties)
                      throws BadOperation
Parameters:
region - target region.
properties - agent properties to match; may be null if all agents are wanted.
Returns:
an array of names of agents matching the specified properties in the specified region. The returned array is zero-sized if no agent matching the given properties could be found.
Throws:
BadOperation - could not get agents list.

listAgentsIn

public Name[] listAgentsIn(Location location)
                    throws BadOperation
Parameters:
location - target agent system location
Returns:
the names of all the agents at the specified agency location. The returned array is zero-sized if there is no agent at given location.
Throws:
BadOperation - could not get agents list.

listAgentsIn

public Name[] listAgentsIn(Location location,
                           org.omg.CfMAF.AgentProfile profile)
                    throws BadOperation
Parameters:
location - target agent system location
profile - agent profile to match.
Returns:
the names of the agents matching a given profile at the specified agency location. The returned array is zero-sized if there is no agent at given location.
Throws:
BadOperation - could not get agents list

listAgencies

public Location[] listAgencies(java.lang.String region,
                               java.util.Properties properties)
                        throws BadOperation
Parameters:
region - target region.
properties - properties that selected agencies must match; may be null if all agencies are wanted.
Returns:
the locations of all the agent systems matching the given properties in the specified region. The returned array is zero-sized if no agent system matches the properties (or if there is no agent system at all).
Throws:
BadOperation - could not get agencies list

findAgent

public Location findAgent(java.lang.String region,
                          Name agent)
                   throws BadOperation
Parameters:
region - target region.
agent - name wrapper of agent MAF name.
Returns:
the location of the named agent residing at the specified region.
Throws:
BadOperation - the agent could not be found.

findAgency

public Location findAgency(java.lang.String region,
                           Name agency)
                    throws BadOperation
Parameters:
region - target region.
agent - name wrapper of agent system MAF name.
Returns:
the location of the named agent system belonging to the specified region.
Throws:
BadOperation - the agency could not be found.

getAgentProperties

public java.util.Properties getAgentProperties(java.lang.String region,
                                               Name name)
                                        throws BadOperation
Parameters:
region - target region.
name - wrapper of agent MAF name.
Returns:
the properties of the named agent residing in the specified region.
Throws:
BadOperation - agent properties could not be obtained.