copyright The Portico Project 2008.

org.portico.core
Class RTIExec

java.lang.Object
  extended by 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.


copyright The Portico Project 2008.