FT-CORBA Infrastructure

User Manual for the FT-CORBA Infrastructure

(written by Diana Szentivanyi)

0. In the home directory on the host where the infrastructure/application is running, a file called OpenORB.xml should be found. A sample OpenORB.xml file is provided with the rest of resources.

1. Packets needed:

a) Extended OpenORB distribution (OpenORB-1.2.0.zip): contains all the modified (and extra) OpenORB core classes in a Java archive under the lib directory: openorb-1.2.0-ft.jar. The Java archive openorb-1.2.0.jar is also in lib - it contains the original OpenORB core classes. When the FT infrastructure is used, the classpath should contain the path to openorb-1.2.0-ft.jar , and not to openorb-1.2.0.jar. There is a zip file containing those OpenORB Java sources that were modified (NEW_EXT_ORB_Sources.zip). Note that OpenORB service packages (e.g. NamingService, TimeService, etc.) are not provided with this distribution. If those are needed, they should be downloaded from the OpenORB web page (http://www.exolab.org).

    b) Distribution with classes specified in the FT-CORBA standard: Classes.jar. Contains classes such as ReplicationManager, FaultNotifier, FaultDetector, FTCPRServerRequestInterceptor, etc. A distribution of sources in the form Sources.zip is also available. The IDL file in which the definitions of the interfaces and structures are is also provided (FTC.idl). The files that are not generated from this IDL are the ones whose names end with "_impl", and the interceptor, initializer, and CORBA object launcher classes (names ending with "L"). Each of the non-generated file contains a license text that has to be read carefully before using the files. The IDL file contains also a license text that refers to the files generated by compiling the it.
    c) A sample application object factory - NOTE: THE CODE OF THE OBJECT FACTORY CANNOT BE USED IN ITS PRESENT FORM TO DO ANY USEFUL OBJECT CREATION: It is the role of the application writer (OR YOURS) to fill out the code of the Application Object Factory with data about the objects it can create, the method signature tables for those objects and initialization operations for those objects
    d) A sample ServerLauncher file, that shows how to set the properties to be sent to the ReplicationManager when it is asked to create a replica group.

For any questions, please contact diasz@ida.liu.se.

2. Setting up the infrastructure:

First of all set the java CLASSPATH to contain the path to the ORB classes, as well as the infrastructure specific classes (where these latter are needed)

If sources are modified, or if a recompilation is needed, then use the command:
javac -d path_where_to_place_the_classes -bootclasspath $CLASSPATH path_where_the_sources_are/*.java

When using the IdlCompiler to generate files from the FTC.idl file (only in case the files need to be re-generated) the command should be:
java org.openorb.compiler.IdlCompiler FTC.idl

When using the IdlCompiler to generate application related files from an IDL written for the specific application then a command line argument has to be given, in order for the idl compiler to generate the right stub and skeleton files:
java org.openorb.compiler.IdlCompiler appl.idl -application

Whenever recompiling of files is needed and it generates errors please use the -bootclasspath $CLASSPATH option (of course, where the CLASSPATH contains the paths where the needed class files are)

The same observation is valid when running a Java file (java SomeClass ....), use the -Xbootclasspath:$CLASSPATH to make sure it will work.

    a) change the OpenORB.xml file (a sample is sent) if needed -> ORB profile names are given in the file, to be used to run the applications with different interceptors; if needed, profile names can be given to the ORB in the command line when launching the different servers
    b) a way of knowing the hosts in the fault tolerance domain has to be chosen. For example, in the present ServerLauncher, a file FT_DOMAINS is parsed for reading the hosts in the fault tolerance domain where the application is supposed to replicate itself.
    c) start the servers:
        -- ReplicationManager on one host (X)
        -- FaultNotifier on one host (Y; possibly Y<>X) (NOTE: ReplicationManager has to be started before FaultNotifier)
        -- ObjectFactory on all hosts where replicas can be created (Z, T, U, V, etc.; possibly Z<>X, Z<>Y, T<>X, T<>Y, etc.)
        -- FaultDetector on all hosts where replicas can be created (Z, T, U, V, etc.; possibly Z<>X, Z<>Y, T<>X, T<>Y, etc.)
        -- LoggingRecoveryController (RecoveryHelper) on all hosts where replicas can be created (Z, T, U, V, etc.; possibly Z<>X, Z<>Y, T<>X, T<>Y, etc.)
        -- other servers (e.g. CORBA services: Naming, Notification, etc.) needed by the application

Command line examples for starting the infrastructure servers:

ReplicationManager:

java -Xbootclasspath:$CLASSPATH org.omg.FT.ReplicManagerL firstDomain -ORBPort=2125 org.omg.FT.ReplicationManager_impl

FaultNotifier:

java -Xbootclasspath:$CLASSPATH org.omg.FT.AFaultNotifierL

ObjectFactory (you have to write your own factories and may launch them the way you want):

java -Xbootclasspath:$CLASSPATH package.of.the.application.FactoryL firstDomain object_factory_class_name 1/0

(1 is for CORBA debug on, 0 is for CORBA debug off)

FaultDetector:

java -Xbootclasspath:$CLASSPATH org.omg.FT.FaultMonitorL firstDomain

LoggingRecoveryMechanism:

java -Xbootclasspath:$CLASSPATH org.omg.FT.LoggingRecoveryMechL firstDomain logging_recovery_mech_class_name

"firstDomain" is the name of the fault tolerance domain. You can change the value of this parameter if you use a different name for the fault tolerance domain.

-ORBPort=2125 is the port number on which the ReplicationManager CORBA object is created and runs. This value is given in the OpenORB.xml file (see profile name="user-mods" where the NameService port is also set). If you want to have a different port number, you have to change in the OpenORB.xml file.

An example from the OpenORB.xml file:

............................................
    <profile name="ftpwpr">
    <import profile="default" />
    <import module="ftwprm" />
    </profile>
    ............................................

    where the definition of the module ftwprm is:
    <module name="ftwprm" initializer="org.omg.FT.WarmPassiveReplicationInitializer">
    </module>

In the file WarmPassiveReplicationInitializer that has a certain form, the instance(s) of the corresponding interceptor(s) is(are) created.
If no interceptor is supposed to be used then the ORBProfile argument can be omitted.

If profile names are changed, corresponding changes have to be made in the command lines.

If new profiles have to be defined, proper initializers have to be configured in the OpenORB.xml configuration file. Maybe new initializer classes have to be written.

The java option -Xbootclasspath might not be necessary. You can try without and see if it works.

d) Start the application, i.e. the part of it that asks the ReplicationManager to create the group (see the sample ServerLauncher.java file). The parameters that should be provided for such an application are: the number of replicas to be created, the checkpointing interval (if any), the fault monitoring interval, replication style, the application object class name to be replicated.

NOTE: in this version of the infrastructure, the server launcher reads the hosts from the
fault tolerance domain, from a file (FT_DOMAINS). The list of hosts is sent to the Replication
Manager as a property. When the Replication Manager then is asked to create, e.g. 3 replicas, it
creates 3 replicas on the first three hosts from the list it received. This part needs
improvement, from the server launcher point of view, as well as from the ReplicationManager
(infrastructure) point of view.

For any questions, please contact diasz@ida.liu.se.

3. Setting up a scenario for measurements

3.1. Setting up a non-replicated scenario for measurements

Start the server application by using one of the profiles from the OpenORB.xml file corresponding to a non-replicated scenario: for example -ORBProfile=nftpscp.
Also, start the client by using a non-replicated scenario profile name, to add the appropriate interceptors: nftpc. Of course, the interceptors have to contain the appropriate trace method calls in the appropriate places.

3.2. Setting up a replicated scenario for measurements

This scenario looks like a replicated scenario with no measurements, the difference being that the interceptors contain calls to the trace method in the appropriate places with the appropriate parameters.

4. Compiling the trace files

Use the Compiler file (SampleTraceCompiler.java contains more info about command line arguments when running java Compiler) in order to process the trace files generated when running replicated or non-replicated scenarios including time tracing operations. After running java Compiler... a set of files corresponding to the different method calls and request travel segment are generated. These files contain the set of values for the times spent on those segments.
The files can further be parsed and processed by using ComputeStatistics. This uses utilities provided in the file Statistics. Here, utilities for computing averages and standard deviations are devised. It is possible to compute averages by removing n largest or smallest values of the value set. Of course, both the Compiler.java file and the ComputeStatistics.java file can be modified so that they are tuned to new needs.