org.portico.core
Class RTIExec

java.lang.Object
  org.portico.core.RTIExec

public class RTIExec
extends Object

The {#link RTIExce} class is the main component that comprises the RTI. All the other components sit underneath it in some way or another.

It not only holds a collection of active Federation's, but also a number of other important pieces used by the RTI to operate propertly. These include a manager for the set of Bootstrap implementations that are used by remote clients to first contact a particular RTIExec, as well as a MulticastRegistry that is generally used to support the automatic discovery of runnings RTI's. The RTIExec also includes a FedexFactory containing the appropriate configuration information to create new federates and federations as required.

Generally speaking, an RTIExec instance is entirely self-contained, and as such, it is possible to have multiple instances running inside the same JVM at once. However, there are problems with doing this when it comes to the behaviour of certain bootstraps and plugins. One example is the JVMBootstrap which has problems when more than one RTIExec is running at once inside the same JVM. The MulticastRegistry can also cause problems. For these reasons, although it is possible to have more than one RTIExec running at once inside a single JVM, the practice is discouraged.

Field Summary

private BootstrapManager	bootstrapManager
private static String	CONFIG_DEFAULT The location of the default configuration file to be applied before a user file
private boolean	configured
private String	executionName
private Map<String,Federation>	federations
private FedexFactory	fedexFactory
private static org.apache.log4j.Logger	LOG
private org.apache.log4j.Logger	logger
private MulticastRegistry	multicastRegistry
private Reaper	reaper
private boolean	running

Constructor Summary

private

RTIExec() Creates a new RTIExec, creating all its components at the same time (such as the BootstrapManager and the MulticastRegistry.

Method Summary

static void	bootstrapLogging() This method will bootstrap the logging for the RTI.
Federation	createFederationExecution(String name, ObjectModel model) Creates a new Federation and registers it with this execution.
void	destroyFederationExecution(String name) Destroys the federation of the given name.
Set<Federation>	getAllFederations() Get a set of all the currently active federations.
BootstrapManager	getBootstrapManager()
org.apache.log4j.Logger	getExecutionLogger()
String	getExecutionName()
Federation	getFederation(String name) Return the active federation of the given name or null if there is none (for that name)
FedexFactory	getFedexFactory()
MulticastRegistry	getMulticastRegistry()
Reaper	getReaper()
boolean	isConfigured()
boolean	isRunning()
private static void	loadRid(RTIExec rtiexec) This method will look for a configuration file at the location specified in the environment variable RTI_RID_FILE, and if that does not exist, the path given in the PorticoConstants.DEFAULT_RTI_RID variable will be checked.
private void	logNotifications() Logs any additional notifications that might need to added.
static RTIExec	newRTI() Creates a new RTI which uses the default configuration NOTE: If logging has not been configured yet, this method will do so.
static RTIExec	newRTI(String file) Creates a new RTI which first loads the default configuration file and then the given configuration file.
static RTIExec	newRTI(String file, boolean loadDefault) Factory method to create a new RTIExec from the given configuration file.
void	setExecutionName(String name) Sets the execution name, this will only work if the configured switch has not yet been set to true (so that it can only be changed during the configuration process)
void	shutdown() This method contains all the shutdown processing fo the RTI execution.
void	startup() This method contains all the startup processing for the RTI execution (post-configuration).
static void	turnLoggingOff() This method will turn all Portico logging off.
static void	turnLoggingOn(String level) This method will turn Portico logging on and set the level to the given parameter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

private static final org.apache.log4j.Logger LOG

CONFIG_DEFAULT

private static final String CONFIG_DEFAULT

The location of the default configuration file to be applied before a user file

See Also:

Constant Field Values

configured

private boolean configured

running

private boolean running

executionName

private String executionName

logger

private org.apache.log4j.Logger logger

federations

private Map<String,Federation> federations

fedexFactory

private FedexFactory fedexFactory

reaper

private Reaper reaper

multicastRegistry

private MulticastRegistry multicastRegistry

bootstrapManager

private BootstrapManager bootstrapManager

Constructor Detail

RTIExec

private RTIExec()
         throws JException

Creates a new RTIExec, creating all its components at the same time (such as the BootstrapManager and the MulticastRegistry. After the RTI has been created, it must be configured and then started. This constructor is kept private to ensure that these events happen properly. New instances should only ever be created through the newRTI(), newRTI(String) or newRTI(String, boolean) methods.

Throws:

JException

Method Detail

createFederationExecution

public Federation createFederationExecution(String name,
                                            ObjectModel model)
                                     throws JFederationExecutionAlreadyExists,
                                            JErrorReadingFED,
                                            JRTIinternalError

Creates a new Federation and registers it with this execution. If the name or model are null (or the name is nothing but whitespace) a JException will be thrown. If the federation exists or can not be created, an exception will be thrown. NOTE: The configuration of the federations public and private sinks will be taken from the pre-configured tempaltes. If a template with the same name as the one given exists, it will be cloned and used. If there isn't a template with the same name, the default template is used.

The federation that was created is returned.

Parameters:

name - The name of the federation to create

model - The FOM for the federation

Throws:

JFederationExecutionAlreadyExists

JErrorReadingFED

JRTIinternalError

destroyFederationExecution

public void destroyFederationExecution(String name)
                                throws JFederatesCurrentlyJoined,
                                       JFederationExecutionDoesNotExist

Destroys the federation of the given name. If the federation does not exist or still has federates joined, an exception will be thrown.

Parameters:

name - The name of the federation to destroy

Throws:

JFederatesCurrentlyJoined

JFederationExecutionDoesNotExist

startup

public void startup()
             throws JException

This method contains all the startup processing for the RTI execution (post-configuration). Following this method, the execution will be considered to be in the running state.

This method will ONLY throw an exception in cases where a FATAL error has occured and the execution can no longer start up successfully.

NOTE: This method will register a shutdown hook for this RTI to ensure that it shutsdown propertly on exit. However, this will only happen if the MainProperties.useShutdownHook() returns true (which it does by default).

Throws:

JException

logNotifications

private void logNotifications()

Logs any additional notifications that might need to added. This method is called as an RTIExec is starting up. Currently, it is only used to log mom-status information.

shutdown

public void shutdown()
              throws JException

This method contains all the shutdown processing fo the RTI execution. On shutdown, the MulticastRegistry will first be killed, followed by the BootstrapManager (and in doing so, all the associated Bootstrap's).

After this, each of the federations will be asked to shutdown and the running status of this instance set to false so that subsequent calls to this method won't attempt to repeat the process.

Throws:

JException

getFederation

public Federation getFederation(String name)

Return the active federation of the given name or null if there is none (for that name)

getAllFederations

public Set<Federation> getAllFederations()

Get a set of all the currently active federations. NOTE: Any of these may disappear at any time if they are the subject of a destroy request. Please don't hold onto the references and indeirectly cause a memory leak in that case.

getExecutionName

public String getExecutionName()

setExecutionName

public void setExecutionName(String name)

Sets the execution name, this will only work if the configured switch has not yet been set to true (so that it can only be changed during the configuration process)

isConfigured

public boolean isConfigured()

Returns:

true if the RTIExec has finished processing its configuration information, false otherwise.

isRunning

public boolean isRunning()

getExecutionLogger

public org.apache.log4j.Logger getExecutionLogger()

getBootstrapManager

public BootstrapManager getBootstrapManager()

getFedexFactory

public FedexFactory getFedexFactory()

getReaper

public Reaper getReaper()

getMulticastRegistry

public MulticastRegistry getMulticastRegistry()

newRTI

public static RTIExec newRTI()
                      throws JException

Creates a new RTI which uses the default configuration

NOTE: If logging has not been configured yet, this method will do so.

Throws:

JException

newRTI

public static RTIExec newRTI(String file)
                      throws JException

Creates a new RTI which first loads the default configuration file and then the given configuration file.

NOTE: If logging has not been configured yet, this method will do so.

Throws:

JException

newRTI

public static RTIExec newRTI(String file,
                             boolean loadDefault)
                      throws JException

Factory method to create a new RTIExec from the given configuration file. If there is a problem, an exception will be thrown. Before the given configuration file is processed, the default configuration file will be applied. If the given boolean is false, the default configuration will NOT be loaded (thus providing a clean slate for the given configuration file).

NOTE: If logging has not been configured yet, this method will do so.

Parameters:

file - The configuration file for the new execution

loadDefault - Should the default configuration be loaded first?

Throws:

JException - If a new RTIExec can not be created from the configuration file

loadRid

private static void loadRid(RTIExec rtiexec)
                     throws JException

This method will look for a configuration file at the location specified in the environment variable RTI_RID_FILE, and if that does not exist, the path given in the PorticoConstants.DEFAULT_RTI_RID variable will be checked. If the file cannot be found in either locations, nothing will happen and the method will return. If the file does exist, but can't be read, or there is an error processing it, a JException will be thrown.

The contents of the file will be processed by creating a new XMLConfigurator and passing it the file and the given RTIExec.

NOTE: If the rid is a java properties file (and not an xml file), the XMLConfigurator won't do anything. This method will attempt to load the RID file as a java properties file first, but won't mention anything if it can't do so. When Portico is started from the command line, it will attempt to load the RID file as a properties file VERY early on (before bootstrapping the logging) - this way, all settings will have the desired affect. See org.portico.core.Main for more info

Parameters:

rtiexec - The RTIExec to configure with the information from the Rid

Throws:

JException - If the file can't be read, or there is an error processing it

turnLoggingOff

public static void turnLoggingOff()

This method will turn all Portico logging off.

NOTE: If logging has not been configured yet, this method will do so.

turnLoggingOn

public static void turnLoggingOn(String level)

This method will turn Portico logging on and set the level to the given parameter. Valid values are: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", "OFF". If there is a problem doing this, a RuntimeException will be thrown.

NOTE: If logging has not been configured yet, this method will do so.

bootstrapLogging

public static void bootstrapLogging()

This method will bootstrap the logging for the RTI. By default, the logging is configured via code (through the commons framework). However, in order to allow some flexibilty, if a log4j configuration file is provided on the file system, that is used in preference. This method will look for that file in the location specified in PorticoConstants.LOG4J_CONFIG_FILE.