Portico and JSAF

Much like the experience of using JSAF itself, getting it up and running with Portico requires a few little tricks. The current version of Portico provides the necessary DLC interface to be used as a drop-in replacement for RTI-NG Pro (or any other DLC compliant RTI), however, due to some underlying implementation differences, minor changes are needed and at the minimum, the JSAF application itself will need to be rebuilt/linked.

Here is the old document about Portico v0.8 and JSAF 2007.

Requirements
All the information in this guide was developed using the following:


 * Portico v1.0.1
 * JDK v1.6.0_13
 * DSE, 2008 Release
 * Fedora Core 6

Note: You will also need to have installed all the appropriate development RPMs required to compile JSAF

The DSE will install JSAF into the path: /usr/dse/JSAF and will create a user for you to use.

Environment Variables
Before you get started, you will need to set up a number of environment variables.


 *  : Should point to the location of Portico
 *  : Should point to the place you installed Java
 *  : This needs to include an entry that points to the  library located in your JDK install (typically on the path  ). This is necessary for linking and running applications that use the Portico libraries.

Recompiling JSAF
Before running JSAF successfully with Portico v1.0 you will need to recompile it. Before doing this, a number of things need to be set up and some entries in the configure script changed.

The overall steps required to get Portico and JSAF happy together are (each of these steps has a section below):


 * 1) Set up the externals symbolic link
 * 2) Update the configure file
 * 3) Rebuild JSAF

JSAF Externals Directory
Before starting, you will need to make a link in the /usr/dse/JSAF/external directory to point to. This allows the JSAF compilation scripts to find Portico. In the output below I have got a copy of the Portico source code and built it directly in the  home directory. After you are done, the  link should point at your Portico install directory.

[dseuser@pc-00218 external]$ pwd /usr/dse/JSAF/external

[dseuser@pc-00218 external]$ ln -sf /home/dseuser/portico/codebase/dist/portico-1.0 rti13ng

[dseuser@pc-00218 external]$ ll drwxrwxr-x 21 dseuser dse 4096 Jun 16 2008 IG lrwxrwxrwx  1 dseuser dse   27 May 15 16:24 ngpro-rti13ng -> /usr/dse/RTI-NG-Pro-v4.0.4/ lrwxrwxrwx 1 dseuser dse   47 May 28 17:44 rti13ng -> /home/dseuser/portico/codebase/dist/portico-1.0.1 drwxrwxr-x 42 dseuser dse 4096 Jun 16 2008 rti-s

Edit the Configure Script
Now that the external symlink is set up, the JSAF configure script will attempt to link against Portico when it builds JSAF. However, before it will all work, a couple of changes will need to be made.

Remember to pop back out to the root JSAF directory first (/usr/dse/JSAF).

'''Change 1. Path to DLC Header Files'''

[dseuser@pc-00218 JSAF]$ vim ./configure (because real men use vim)

First, on about like 1569, change:

rtidir="unknown"

to read:

rtidir="."

Secondly, on around line 1575, change:

if test -f $srcdir/external/rti13ng/$rtilibs/librti13.so then rti_ver="RTI-1.3NG -- DLC" rtiinclude=$rtidir/include/1_3DlcApi else

to read:

if test -f $srcdir/external/rti13ng/$rtilibs/librti13.so then rti_ver="RTI-1.3NG -- DLC" rtiinclude=$rtidir/include/dlc13 **change is here** else

'''Change 2. Library Directories'''

Around line 5889 you will see an entry like this:

LDFLAGS="$LDFLAGS -L\$(top_srcdir)/$RTI_LIBRARY_PATH" CPPFLAGS="$CPPFLAGS -I\$(top_srcdir)/$RTI_INCLUDE_PATH"

Change this to include the location to your  file (typically  ). Here I've installed my JDK into the  home directory:

LDFLAGS="$LDFLAGS -L\$(top_srcdir)/$RTI_LIBRARY_PATH -L$JAVA_HOME/jre/lib/i386/client" CPPFLAGS="$CPPFLAGS -I\$(top_srcdir)/$RTI_INCLUDE_PATH"

Change 3: Linked Libraries

Finally, around like 5866 (just above change 2), you will see something like this:

if test -f $srcdir/external/rti13ng/$rtilibs/librti13.so then RTI_INCLUDE_PATH="external/rti13ng/$rtiinclude" RTI_LIBRARY_PATH="external/rti13ng/$rtilibs" RTI_LIBS="-lrti13 -lfedtime13" elif test -d $srcdir/external/rti13ng/$rtilibs

Change this to include  and   like so:

if test -f $srcdir/external/rti13ng/$rtilibs/librti13.so then RTI_INCLUDE_PATH="external/rti13ng/$rtiinclude" RTI_LIBRARY_PATH="external/rti13ng/$rtilibs" RTI_LIBS="-lrti13 -lfedtime13 -ljsig -ljvm" **change here** elif test -d $srcdir/external/rti13ng/$rtilibs

Once this is done, reconfigure everything so as to rebuild all the make files with the new location information:

[dseuser@pc-00218 JSAF]$ ./configure

Rebuild JSAF
Once you have made your edits and run the configure script, it's time to rebuild JSAF. Be warned, this can take a LONG time.

[dseuser@pc-00218 JSAF]$ ./configure [dseuser@pc-00218 JSAF]$ make jsaf

Get JSAF Up and Running
Once the compile and relink is complete, you can fire up JSAF. You will need to include the location to your  on the LD_LIBRARY_PATH. Also, note that at the moment there are known problems with the Portico/JSAF/DDM combination, so you will want to start JSAF with DDM disabled.

[dseuser@pc-00218 JSAF]$ cd src/JSAF [dseuser@pc-00218 JSAF]$ LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386/client ./jsaf -terrain ../../terrain/world_thin_fmt8_7_180W180E75S75N_v01.dir -federation jntc2 -nortiddm

Portico RID Settings
When running JSAF, you will want to change some of the default settings that Portico uses. You can change these settings through the  file. If that file doesn't exist, copy it into the working directory from. If it is in the same directory you execute JSAF from, Portico will find it. Open it up and make the following changes:

Unsupported Exceptions

By default, Portico will thrown exceptions when an RTIambassador call that isn't supported by Portico is made. This can cause JSAF to crash unnecessarily, so we need to disable it:

portico.unsupportedExceptions = false

Duplicate Federate Names

Portico will enforce that each federate in a federation have a unique name. However, when starting multiple JSAF instances this can cause problems. Again, we will turn this checking off in the RID:

portico.uniqueFederateNames = false

For more information on the all the available RID file options, see Configuring Portico

Known Problems
At the moment, the combination of Portico and JSAF is known to cause some problems when the HLA Data Distribution Management services are used. To avoid these issues, you can start JSAF with the  argument. These issues are being addressed and will be part of a future release.

JSAF is crashing with a segfault a lot
This has been known to happen when you haven't set the JSAF compile up to use the signal handler chaining library properly (see full information below). Make sure you are linking to  (same directory as  ) when compiling JSAF.

During development, problems with the default size of the stack were also observed. Another trick to try is to make sure that the operating system defined stack sizes are big enough. You can see the stack size on linux with the  command, and you can get it higher with the   command (where 65536 is the size, set it to whatever you need).

Turning up the Portico Log Output
If you want to turn up the amount of log information the Portico LRC provides, add the following line to the RTI.rid file (where LEVEL is the log level you want, typically either "DEBUG" or "TRACE"):

portico.loglevel=LEVEL

Getting the JSAF PVD running in GDB
Another useful debugging step is to run the JSAF PVD under GDB. To do this you will want to start GDB with a command something like this:

gdb ./jsaf -x gdb-jsaf.args

You will also need the file  in the directory. It should look like this:

set args -terrain ../../terrain/world_thin_fmt8_7_180W180E75S75N_v01.dir -federation jntc2 -nortiddm

Note that GDB is known to cause problems with the JVM. I've noticed intermittent segmentation faults in internal JVM code occurring in GDB that don't seem to affect it when it is executing normally. If you see these, you can often continue through them (with the 'c' command), although sometimes they will bring JSAF down.

JSAF/Portico Signal Handler Problems
The Portico C++ interface uses JNI to wrap around the core Java-based RTI. In normal operation this works well, however, when testing with JSAF a number of random crashes were noticed. After much searching, the problem was narrowed down JSAFs use of signal handlers.

Internally, the JNI uses signals to complete a number of tasks. As such, it expects to be able to have its own signal handlers installed to deal with these problems. Unfortunately, JSAF installed a bunch of its own signal handlers, conflicting with those that the JNI wanted to have installed.

Fortunately, Java provides a nice solution to this in the form of a signal handler chaining library, allowing multiple handlers to be installed for any given signal. To solve this problem, JSAF just has to be recompiled with a reference to the signal handling library. As of version 1.0.1, Portico is also linked against this library.