gov.nasa.arc.brahms.vm.api.components
Interface IVMController


public interface IVMController

The IVMController interface allows external components to control the virtual machine through the actual virtual machine controller. The external component can start, pause, resume and stop the virtual machine. Load in a new model and/or concepts. Get access to the event notifier and logger to register for messages.


Field Summary
static java.lang.String APPDIR
          The application directory of the virtual machine
static java.lang.String NS_HOST
          The property used to retrieve the host name of the name service
static java.lang.String NS_PORT
          The property used to retrieve the port number of the name service
static java.lang.String VM_NAME
          The property indicating the unique name for the virtual machine/agent environment
static java.lang.String WORKINGDIR
          The working directory
 
Method Summary
 AgentName createAgentIdentity()
          Creates a new unique agent identity as required for registering an agent in an agent directory service.
 AgentDirectoryService getAgentDirectoryService()
          Returns the agent directory service used to register agents and to find agents.
 AgentNamingService getAgentNamingService()
          Returns the agent naming service used to uniquely name each agent
 IClock getClock()
          Returns an interface to the clock maintaining the date and time in a simulation.
 IEventNotifier getEventNotifier()
          Returns an interface to the event notifier responsible for distributing events from the virtual machine to external components that register with the event notifier for events.
 IExternalService getExternalService(java.lang.String id)
          Returns the external service with the specified ID if such a service is loaded, otherwise a VMException is thrown.
 ILogger getLogger()
          Deprecated. Use Log4J's Logger class for logging messages instead
 MessageTransportService getMessageTransportService()
          Returns the message transport service required by agents to communicate with one another.
 IModel getModel()
          Returns an interface to the model loaded in the virtual machine providing access to the concepts loaded in the virtual machine.
 org.omg.CORBA.ORB getORB()
          Returns, and if necessary creates, the CORBA ORB that can be used to access or use Brahms Corba services.
 java.lang.Object getProperty(java.lang.String name)
          Returns the property value of the property with the specified name.
 ServiceRoot getServiceRoot()
          Returns the Service Root providing access to the directory service.
 IWorldState getWorldState()
          Returns the virtual machine's world state managing the fact set.
 void loadConcept(java.lang.String sConcept)
          Loads the given concept specified by its fully qualified name in the virtual machine.
 void loadExternalService(java.lang.String className)
          Loads the external service specified with the className in the virtual machine.
 void loadModel(java.lang.String sModel)
          Loads the given model specified by its fully qualified name in the virtual machine.
 void pause()
          Pauses all activated concepts, pausing all the engines and the scheduler.
 void resume()
          Resumes all paused active concepts, resuming the activities of the scheduler and all the engines.
 void start()
          Activates all the concepts loaded in the virtual machine.
 void stop()
          Stops the virtual machine and all the concepts.
 

Field Detail

APPDIR

static final java.lang.String APPDIR
The application directory of the virtual machine

See Also:
Constant Field Values

WORKINGDIR

static final java.lang.String WORKINGDIR
The working directory

See Also:
Constant Field Values

VM_NAME

static final java.lang.String VM_NAME
The property indicating the unique name for the virtual machine/agent environment

See Also:
Constant Field Values

NS_HOST

static final java.lang.String NS_HOST
The property used to retrieve the host name of the name service

See Also:
Constant Field Values

NS_PORT

static final java.lang.String NS_PORT
The property used to retrieve the port number of the name service

See Also:
Constant Field Values
Method Detail

loadExternalService

void loadExternalService(java.lang.String className)
                         throws java.lang.ClassNotFoundException,
                                VMException
Loads the external service specified with the className in the virtual machine. It creates an instance of the class and initializes the service. The external service must implement the IExternalService interface or extend AbstractExternalService.

Note: Each external service instance must have a unique name. The class needs to ensure this if more then one instance is to be loaded from the same class.

Parameters:
className - the name of the external service class to be loaded
Throws:
java.lang.ClassNotFoundException - if the external service class is not found
VMException - if the service could not be loaded due to some internal error.

getExternalService

IExternalService getExternalService(java.lang.String id)
                                    throws VMException
Returns the external service with the specified ID if such a service is loaded, otherwise a VMException is thrown.

Parameters:
id - the unique id for the requested external service
Returns:
IExternalService the external service with the specified id
Throws:
VMException - if no service with the specified id is loaded in the vm.

loadModel

void loadModel(java.lang.String sModel)
               throws ConceptNotFoundException
Loads the given model specified by its fully qualified name in the virtual machine. If a simulation is running it is stopped if a new model is to be loaded. This to properly initialize the new model.

Parameters:
sModel - the fully qualified name of the model to be loaded
Throws:
ConceptNotFoundException - if the model could not be found
ConceptFormatError - if the file does not contain well formed and valid XML based on its DTD

loadConcept

void loadConcept(java.lang.String sConcept)
                 throws ConceptNotFoundException
Loads the given concept specified by its fully qualified name in the virtual machine. If a simulation is running it is temporarily paused if a new concept is to be added to the currently active model. This to properly initialize the new concept.

Parameters:
sConcept - the fully qualified name for the concept to be loaded
Throws:
ConceptNotFoundException - if the concept could not be found
ConceptFormatError - if the file does not contain well formed and valid XML based on its DTD or has invalid references to Brahms constructs

getClock

IClock getClock()
Returns an interface to the clock maintaining the date and time in a simulation.

Returns:
IClock
See Also:
IClock

getEventNotifier

IEventNotifier getEventNotifier()
Returns an interface to the event notifier responsible for distributing events from the virtual machine to external components that register with the event notifier for events.

Returns:
IEventNotifier the virtual machine's event notifier
See Also:
IEventNotifier

getModel

IModel getModel()
                throws ExternalException
Returns an interface to the model loaded in the virtual machine providing access to the concepts loaded in the virtual machine.

Returns:
IModel an interface to the model
Throws:
ExternalException - if an internal error occurs.

getWorldState

IWorldState getWorldState()
                          throws ExternalException
Returns the virtual machine's world state managing the fact set.

Returns:
WorldState the virtual machine's world state
Throws:
ExternalException - if an internal error occurs
See Also:
IWorldState

getORB

org.omg.CORBA.ORB getORB()
                         throws ExternalException
Returns, and if necessary creates, the CORBA ORB that can be used to access or use Brahms Corba services.

Returns:
ORB the CORBA ORB
Throws:
ExternalException - if an error occurs creating or initializing the ORB

getServiceRoot

ServiceRoot getServiceRoot()
                           throws ExternalException
Returns the Service Root providing access to the directory service. naming service and transport service required for the agent architecture.

Returns:
ServiceRoot the service root
Throws:
ExternalException - if an internal error occurs
See Also:
ServiceRoot

getAgentNamingService

AgentNamingService getAgentNamingService()
                                         throws ExternalException
Returns the agent naming service used to uniquely name each agent

Returns:
AgentNamingService the naming service
Throws:
ExternalException - if there's an error retrieving the naming service

getAgentDirectoryService

AgentDirectoryService getAgentDirectoryService()
                                               throws ExternalException
Returns the agent directory service used to register agents and to find agents.

Returns:
AgentDirectoryService the directory service
Throws:
ExternalException - if there's an error retrieving the directory service

getMessageTransportService

MessageTransportService getMessageTransportService()
                                                   throws ExternalException
Returns the message transport service required by agents to communicate with one another.

Returns:
MessageTransportService the transport service
Throws:
ExternalException - id there's an error retrieving the transport service

createAgentIdentity

AgentName createAgentIdentity()
                              throws ExternalException
Creates a new unique agent identity as required for registering an agent in an agent directory service.

Returns:
AgentName a unique agent identity
Throws:
ExternalException - if an internal error occurs.

getLogger

ILogger getLogger()
Deprecated. Use Log4J's Logger class for logging messages instead

Returns an interface to the logger responsible for logging error, warning, debug and informational messages to various log media through log writers.

Returns:
ILogger the virtual machine's logger
See Also:
ILogger

getProperty

java.lang.Object getProperty(java.lang.String name)
Returns the property value of the property with the specified name.

Parameters:
name - the property name
Returns:
Object the property value, or null if the property does not exist.

start

void start()
           throws VMException
Activates all the concepts loaded in the virtual machine. If no concepts are loaded this method does nothing. To activate the concepts this method assigns a context to each concept, initializes the scheduler, creates an engine for each active concept, initializes the engines and starts the scheduler and engines.

Throws:
VMException - if an error occured in the process of starting the concepts

pause

void pause()
           throws VMException
Pauses all activated concepts, pausing all the engines and the scheduler.

Throws:
VMException - if the virtual machine is in a stopped state

resume

void resume()
            throws VMException
Resumes all paused active concepts, resuming the activities of the scheduler and all the engines.

Throws:
VMException - if the virtual machine is in a stopped state

stop

void stop()
          throws VMException
Stops the virtual machine and all the concepts. Resets the virtual machine.

Throws:
VMException - if an error occurs in stopping or resetting the virtual machine