[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.18.2 Java Bindings

Written by Eric Sunshine, [email protected].

The csJava module provides access to Crystal Space from Java in the form of a set of classes in the package `org.crystalspace3d' which can be imported into pure Java programs. The csJava module consists of a JAR package, `crystalspace.jar', and a shared library, `csjava'.

The Crystal Space classes, interfaces, and methods exported to Java are used in almost the same fashion as in C++. Consequently, the Crystal Space Public API Reference can be consulted in most cases. There is also a sample program which shows concretely how to utilize Crystal Space from Java. It performs the same functionality as the first C++ tutorial (see section Simple Tutorial 1: Basic Setup, World Creation).

Presently, the caJava module can be built only by people using Jam or "make" to build Crystal Space. To build csJava, follow these instructions:

  1. Install Swig.

    http://www.swig.org/

  2. Install a Java SDK. Crystal Space has been tested with Sun's Java2 SDK, Standard Edition 1.4.x. After installing Java, be sure that the `java' and `javac' commands are found by your `PATH' environment variable, or set `JAVA_HOME'.

    http://java.sun.com/j2ee/1.4/download.html

  3. Install Ant, a "make"-like tool for Java. After installing Ant, be sure that the `ant' command is found by your `PATH' environment variable, or set `ANT_HOME'.

    http://ant.apache.org/

  4. Configure Crystal Space. The configure script should recognize the `java', `javac', `ant', and `swig' commands, and perform a "Java SDK usability" check. If all checks succeed, continue to the next step.
  5. Build and optionally install Crystal Space. The csJava module will be built along with the rest of the project.

Once Crystal Space is built and optionally installed, you can use the csJava module in your own programs. To do so, follow these instructions:

  1. Tell Java where to find `crystalspace.jar' by setting your `CLASSPATH' environment variable to point at the JAR file. If you installed Crystal Space, then the JAR file will reside at:

    ${prefix}/share/crystalspace/bindings/java/crystalspace.jar

    where ${prefix} is the installation path (typically, `/usr/local'). If you did not install Crystal space, then the JAR file will be in the top-level build directory (this will be the `CS' directory if you configured and built in the `CS' directory). For convenience in testing, you can also point your `CLASSPATH' variable at the current directory (`.').

  2. Tell Java where to find the csJava shared library by setting your `LD_LIBRARY_PATH' environment variable on Unix, your `PATH' variable on Windows, or your `DYLD_LIBRARY_PATH' variable on MacOS/X. On Unix, the library's name is `libcsjava.so'; on Windows it is `csjava.dll'; and on MacOS/X, it is `libcsjava.jnilib'. If you installed Crystal Space, then the library will reside at:

    ${prefix}/share/crystalspace/bindings/java

    If you did not install Crystal Space, then it will be in the top-level build directory.

  3. If necessary, set your `CRYSTAL' environment variable to allow Crystal Space to locate its plugin modules and other resources.
  4. In the directory containing your Java program, `myprog.java', compile it with the `javac' command: `javac myprog.java'
  5. Run your program: `java myprog'

The sample program `SimpleRoom.java' provides a nice example of how to utilize Crystal Space from Java. It provides the same functionality as the first C++ tutorial (see section Simple Tutorial 1: Basic Setup, World Creation). If you installed Crystal Space, then `SimpleRoom.java' will reside at:

${prefix}/share/crystalspace/bindings/java/SimpleRoom.java

If you did not install Crystal Space, then you can find it in the Crystal Space source tree at `CS/scripts/java/SimpleRoom.java'. To experiment with `SimpleRoom.java', copy it to a convenient work directory, compile it with `javac', and run it with `java'. Here is a sample session on GNU/Linux illustrating the above instructions:

 
% cd CS
% ./configure
...
checking for swig... swig
checking if swig version >= 1.3.20... yes (version 1.3.22)
checking for java... /usr/java/j2sdk1.4.2_06/bin/java
checking for javac... /usr/java/j2sdk1.4.2_06/bin/javac
checking if Java2 SDK is usable... yes
checking for ant... /usr/local/ant/bin/ant
...
% jam install # (or 'make install')

% csjavadir=/usr/local/share/crystalspace/bindings/java
% CLASSPATH=$CLASSPATH:.:$csjavadir/crystalspace.jar
% export CLASSPATH
% LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$csjavadir
% export LD_LIBRARY_PATH
% CRYSTAL=/usr/local
% export CRYSTAL
% mkdir $HOME/javatest
% cd $HOME/javatest
% cp $csjavadir/SimpleRoom.java .
% javac SimpleRoom.java
% java SimpleRoom

On Windows and MacOS/X, the procedure is almost identical. The primary difference is that, rather than setting `LD_LIBRARY_PATH', you need to set the `PATH' environment variable on Windows to point at the directory containing `csjava.dll'; or the `DYLD_LIBRARY_PATH' variable on MacOS/X to point at the directory containing `libcsjava.jnilib'.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated using texi2html 1.76.