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.

Version:

$Revision: 1.4 $ $Date: 2008/08/05 21:27:59 $ $Author: rvhoof $

Author:

Ron van Hoof

Field Summary

static java.lang.String	APPDIR The application directory of the virtual machine
static int	DISTRIBUTED_MODE The virtual machine's real-time mode of operation
static java.lang.String	MODE_PROPERTY VM Mode of operation property
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 int	REALTIME_MODE The virtual machine's real-time mode of operation
static int	SIMULATION_MODE The virtual machine's simulation mode of operation
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

void	addProcessListener(IProcessListener listener) Adds the specified process listener to this virtual machine to be notified when the virtual machine exits.
gov.nasa.ci.api.asp.IActorServiceProvider	getASP() Returns the collaborative infrastructure actor service provider used to make Brahms agents available as CI actors.
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
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.
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	registerTimeSyncHook(ITimeSyncHook hook) Register an external time synchronization hook
void	removeProcessListener(IProcessListener listener) Removes the specified listener as a process listener for the virtual machine.
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

MODE_PROPERTY

static final java.lang.String MODE_PROPERTY

VM Mode of operation property

See Also:

Constant Field Values

SIMULATION_MODE

static final int SIMULATION_MODE

The virtual machine's simulation mode of operation

See Also:

Constant Field Values

REALTIME_MODE

static final int REALTIME_MODE

The virtual machine's real-time mode of operation

See Also:

Constant Field Values

DISTRIBUTED_MODE

static final int DISTRIBUTED_MODE

The virtual machine's real-time mode of operation

See Also:

Constant Field Values

Method Detail

addProcessListener

void addProcessListener(IProcessListener listener)

Adds the specified process listener to this virtual machine to be notified when the virtual machine exits.

Parameters:

listener - the IProcessListener to be registered

removeProcessListener

void removeProcessListener(IProcessListener listener)

Removes the specified listener as a process listener for the virtual machine.

Parameters:

listener - the IProcessListener to be removed.

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

getASP

gov.nasa.ci.api.asp.IActorServiceProvider getASP()
                                                 throws ExternalException

Returns the collaborative infrastructure actor service provider used to make Brahms agents available as CI actors.

Note: The virtual machine must be started as a HostingEnvironment

Returns:

IActorServiceProvider the ASP

Throws:

ExternalException - if there was a problem obtaining the ASP

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

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

registerTimeSyncHook

void registerTimeSyncHook(ITimeSyncHook hook)

Register an external time synchronization hook

Parameters:

hook - the hook object that will synchronize with the external time manager.