Introduction

The installation of nsjava is relatively easy. As a prerequisite, it is necessary to install Postgresql, Aolserver, and a compatible Java Development Kit. Make sure that you obtain a native-threads JDK version. Green threads JDK versions will not work. Currently nsjava only supports the postgresql database, but it could be extended relatively easily to support other databases. After installing Postgresql and Aolserver, obtain the nsjava source code from http://nsjava.sourceforge.net. Most problems with building and installing nsjava relate to problems with setting the executable path to the java build tools, the setting of the LD_LIBRARY_PATH environment variable, and the setting of the CLASSPATH variable in the nsjava module configuration section of aolserver's nsd.tcl configuration file. Since java is closed-source and is not normally available in source form, pre-compiled versions are usually only available. This can sometimes cause problems if the versions of libraries referenced by the java virtual machine do not match the versions used to build the java virtual machine. This problem has occurred with the pthreads library on some Mandrake distributions.

Unpack and Configure nsjava

After obtaining nsjava from http://nsjava.sourceforge.net unpack the source code:

tar -xvzf nsjava-0.0.9.tar.gz

This should result in a new directory nsjava-0.0.9. Please note that the filenames and resulting directories correspond to the a particular version of nsjava, and with each new release the tar file names and corresponding directories change. In this case nsjava-0.0.9 is only used for illustration. After unpacking cd into the new directory:

cd nsjava-0.0.9

Next it is necessary to configure the build process. As input, the "configure" program requires several command line switches, so that the build process can find the location of the Aolserver sources and the location of the JDK libraries. If the bin directory for the JDK that you are using is in your command path, then the configure program should be able to locate it, and the corresponding java libraries. In such a case, set the PATH environment variable and run configure as follows:

export PATH=$PATH:/usr/local/jdk/jdk118_v1/bin (bash)

- or -

setenv PATH ${PATH}:/usr/local/jdk/jdk118_v1/bin (csh/tcsh)

./configure --prefix=/home/nsadmin --with-aolserver-src=/usr/local/aolserver3_2

In the preceding example, it is assumed that the Aolserver source code is located in the /usr/local/aolserver3_2 directory and that the nsjava libraries will be copied into the /home/nsadmin/bin directory when you install them. You may have your Aolserver source code in a different directory, and you may wish to install the nsjava library into another directory, in which case you will need to change the --prefix and --with-aolserver-src switches to reflect those changes. If the JDK that you wish to use is not found, you can either modify your command path by changing your PATH environment variable, or you can tell the configure program the location of the JDK by using the --with-jdk command line switch. Something like the following should work:

./configure --prefix=/home/nsadmin --with-aolserver-src=/usr/local/aolserver3_2 --with-jdk=/usr/local/jdk/jdk118_v1

If configure runs correctly, you should see something like the following when it completes:

        NSJAVA version 0.0.9 configured successfully.
                                                                                                                                            Using c-compiler:      gcc
JDK Version:           1.1
Install libnsjava.so:  /home/nsadmin/bin
Aolserver Version:     3_0_PLUS
Aolserver include:     /usr/local/aolserver3_2/include
Aolserver nsd include: /usr/local/aolserver3_2/nsd
jdk include:           /usr/local/jdk/jdk118_v1/include
jdk platform include:  /usr/local/jdk/jdk118_v1/include/linux
libjava.so dir:        /usr/local/jdk/jdk118_v1/lib/i686/native_threads
java classpath:        "/usr/local/jdk/jdk118_v1/lib/classes.zip"
 
CFLAGS: ' -pipe -fPIC -Wall -Wno-unused -DHAVE_CMMSG=1 -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1'
 
LIBS:   ' -ldl -lpthread -L/usr/local/jdk/jdk118_v1/lib/i686/native_threads -ljava'
 
creating ./config.status
creating Makefile.global                  

Check the highlighted sections and make sure that they correspond to the values that you used when you ran configure. Also make sure that configure located a native threads JDK version.

Build nsjava

To build the nsjava dynamic library and corresponding Java jar file, simply type 'make':

make

When the build process finishes, install the shared library and jarfile:

make install

You should see that the libnsjava.so shared library and the nsjava.jar jarfile are copied to the bin directory which is relative to you prefix specified as part of the configure process.

Configuring Aolserver to Load nsjava

Once nsjava is built and installed, and before you start Aolserver, you need to modify your nsd.tcl file, so that nsjava is loaded correctly. The first thing that you need to do is add nsjava to the modules section as shown in the example below:

# 
# Modules to load 
# 
ns_section "ns/server/${server}/modules" 
        ns_param   nssock          ${bindir}/nssock.so 
        ns_param   nslog           ${bindir}/nslog.so 
        ns_param   nsperm          ${bindir}/nsperm.so 
        ns_param   nsjava          ${bindir}/nsjava.so

The next step is to configure the nsjava module by adding the following section to your nsd.tcl file:

ns_section "ns/server/${server}/module/nsjava"
        ns_param   EnableJava          "on"   ;# Set to on to enable nsjava.
        ns_param   VerboseJvm          "off"  ;# Same as command line -debug.
        ns_param   LogLevel            "Notice"
        ns_param   DestroyJvm          "on"   ;# Destroy jvm on shutdown.
        ns_param   DisableJITCompiler  "off"  
        ns_param   ClassPath           "/usr/local/jdk/jdk118_v1/lib/classes.zip:/home/nsadmin/bin/nsjava.jar" 

It is important to note that nsjava completely ignores any CLASSPATH environment variables that you may have set. The only way to set the CLASSPATH environment variable is to configure it in your nsd.tcl file as shown above. Version 1.1 JDK's as shown above, require the classes.zip file to be added to the CLASSPATH, while 1.2 JDK's do not.

Setting the LD_LIBRARY_PATH Environment Variable

I have tested with JDK versions from Sun, Blackdown and IBM, and they all seem to have different directory structures for their JDK installations. In addition, the 1.1 and 1.2 JDK's have different libraries that they load. Currently I'm using a 1.1 JDK from Blackdown, and the only Java shared library that I need to load is libjava.so. For this particular example, on a Redhat 6.2 machine, libjava.so is located in /usr/local/jdk/jdk118_v1/lib/i686/native_threads. If you look at the configuration script output shown above, you can see that this directory is specified as part of the LIBS build variable. Just take this value and append it to your LD_LIBRARY_PATH environment variable. For 1.2 JDK's, you will, if I remember correctly, need to modify the LD_LIBRARY_PATH so that libjava.so, libhp.so and libjvm.so can be located. In any event, if you don't have all of the correct libraries in the LD_LIBRARY_PATH, nsjava will fail to load. When it fails to load, it will print out an error message indicating the name of the library that it couldn't find. As an example, go to the root directory of you JDK installation and search for the library named in the error message (in this example libjvm.so):

find /usr/local/jdk/jdk122_v1 | egrep 'libjvm\.so'

When you find the library, just add the path for it to your LD_LIBRARY_PATH and restart Aolserver. You might have to repeat this until you find all the libraries that nsjava is looking for to run the java virtual machine. You will also need to add the path to the directory where libjava.so was installed. I usually install libjava.so in the bin directory along with the aolserver executable and shared libraries for the driver and other utilities. Also once you get the library paths worked out, instead of setting the LD_LIBRARY_PATH environment variable, you can configure /etc/ld.so.conf and run ldconfig, so that the loader can find the needed libraries.

Starting Aolserver

Once you have the LD_LIBRARY_PATH worked out, start Aolserver and check for errors. When testing, I usually start Aolserver in the foreground using a shell from within emacs:

M-x shell-mode (from within emacs)

bin/nsd -fkt nsd.tcl (start aolserver in the foreground)

After Aolserver has started, I then use emacs' search capabilities to search backward in the log output to find out if any start-up errors occurred.

Once you are satisfied that aolserver is starting correctly, you can automate the startup, by using one of the usual methods such as a startup script in /etc/rc.d/init.d or by running it from inittab, or by using something like daemontools to control aolserver.

Problems

If you have any problems, it will usually be due to typos in either the CLASSPATH configuration value, or in the LD_LIBRARY_PATH setting. Search back in the log file until you find the first error. Usually the error message will be enough to point you in the right direction. You can also get help with your problems by posting on openacs.org. You might also encounter problems if your are trying to build nsjava on a platform for which I haven't had access to for development and testing. In such a case, contact me, and I will try and help you to get nsjava to build on your particular platform. I will then incorporate the changes into the nsjava build process.