HOWTO: Create, run and deploy Java 3D applications using Excelsior JET
Notice Information in this article applies to Excelsior JET version 4.5 and above. For version 4.1, see article #27.
This article was written when the latest version of Java 3D was 1.5.0. It may be not fully correct for newer versions.
The Java 3D(tm) API is an application programming interface used for writing three-dimensional graphics applications. It has been originally developed by Sun Microsystems and later turned into a community source project. This article describes how you can use Excelsior JET to optimize your Java application that utilizes the Java3D API and create an installation package to deploy it to end-user systems. The names and locations of Java 3D files are given for Java 3D 1.5.0.
Note: This article describes only the essential details of optimizing and deploying a Java 3D application with Excelsior JET. If you are a first time Excelsior JET user, please refer to the Excelsior JET online tutorials guiding you through the basics of application optimization and deployment.
Java 3D is a so called optional package, defined in the Java platform documentation as “package of Java classes and associated native code that application developers can use to extend the functionality of the core platform.” An optional package consists of one or more jar files, and may also contain native method libraries, property files and other auxiliary files.
Optional packages are normally installed right into the JRE installation directory. Their jar files are placed in the
lib/ext subdirectory, or right into the
lib subdirectory containing the core platform jar files. Jars from these directories are automatically added to the classpath of any application that runs on that JRE.
Similarly, the native method libraries or an optional package are placed alongside their core platform counterparts. On Windows, that is the
bin subdirectory of the JRE, where the
java launcher resides. On Linux, native method libraries are located in the
lib/i386 subdirectory of the JRE.
JAVA 3D FILES
The runtime part of the Java 3D optional package consists of three jar files:
and a few native method libraries:
You have to compile the jar files into the application executable and make the native method libraries available at run time.
BUILDING A JAVA 3D APPLICATION
Excelsior JET does not depend on a JRE installation and is unable to detect where the Java 3D package is installed on any of the JREs present on the system. Therefore you have to include the Java 3D jars into the compilation set manually.
On the Start page of the JET Control Panel, add the Java 3D jars to the beginning of the classpath. For example if your application is placed in
MyApp.jar file and its main class is
MyMain you should parse command line like this:
java -cp JRE-Home
You also have to ensure that the resulting executable will be able to find the Java 3D native libraries on startup. On Windows, you may simply copy those libraries into the directory where the application EXE resides. If you do not want to do that for any reason, or if you are targeting Linux, you must specify the pathname of the directory containing the Java 3D native method libraries using the
java.library.path system property.
Suppose you will copy the Java 3D native libraries into the
./lib subdirectory relative to the resulting executable. Specify the
java.library.path system property in the following way:
Suppose Java 3D is installed into the JRE located in
/usr/java/jdk1.5.0_06/jre and you do not want to copy the native method libraries. Set
java.library.path as follows:
RUNNING THE COMPILED JAVA 3D APPLICATION
Before you run the compiled application, make sure that the Java 3D native method libraries can be found either:
- in the directory you have specified in the
java.library.pathsystem property, or
- in the directory where the application executable resides (Windows only)
The pathnames of the required libraries relative to the JRE root directory are as follows:
In the next section, we describe how to create an installation package for a Java 3D application compiled with Excelsior JET.
CREATING AN INSTALLATION PACKAGE
Your application needs the Java 3D native method libraries to run, so you must include these libraries into the installation package and ensure that they can be found at run time.
Add the main application executable to the installation package, then add the following native method libraries from the JRE that has Java 3D installed:
On Windows, no Java 3D specific actions are required if you have placed the Java 3D native libraries alongside the application executable. Otherwise, you must specify the
java.library.path system property for that executable. Suppose your installation has Java 3D native libraries placed in the
$(Root)/lib subdirectory. Select the executable of your Java 3D application and specify the said property in the Java System Properties field as follows:
No Java 3D specific actions are required on the further steps of creating the installation package for your compiled application.
Note: We strongly recommend you to perform a trial run before building the installation package in order to check if the package is complete and the application works properly.
BUILDING A MULTI-COMPONENT JAVA 3D APPLICATION
In this section we describe how to build a multi-component Java 3D application with Excelsior JET, compiling the Java 3D jars into a separate dynamic library and the jars of your application into an executable file.
We recommend you to create a multi-component application from the jars that could be flawlessly compiled into a single-component application with Excelsior JET.
Note: Having created a dynamic library from Java 3D jars, you will still need the appropriate Java 3D native method libraries (
j3dcore-d3d.dll, etc.) for your application to run.
On this step we define the content of the dynamic library containing Java 3D classes.
The compilation set should contain all Java 3D jars (
vecmath.jar) to enable Excelsior JET to compile them into a library.
In order to create a library from the compilation set, you should create a project file and compile it using the command line Excelsior JET compiler,
Create an empty directory called, for instance,
MultiCompBuild. In the directory, create an Excelsior JET project file (plain text file with the extension
.prj) using the following template:
% library name without extension: -OUTPUTNAME=j3d -GENDLL+ -PACK=ALL -IGNOREMEMBERABSENCE+ -LOOKUP=*.sym=./sym_j3d -LOOKUP=*.bod=./bod_j3d -LOOKUP=*.rdf=./rdf_j3d -LOOKUP=*.jar=e:\jdk\jdk1.5.0_06\jre\lib\ext % Java 3D jars: !classpathentry j3dcore.jar -pack=noncompiled -protect=nomatter -optimize=all !end !classpathentry j3dutils.jar -pack=noncompiled -protect=nomatter -optimize=all !end !classpathentry vecmath.jar -pack=noncompiled -protect=nomatter -optimize=all !end
Make sure to edit the
-LOOKUP=*.jar= line to point to the location of Java 3D jars on your system.
On this step, you create a project file for the main part of your application.
In the same directory as on a previous step, create another project file using the following template:
% EXE-name without extension: -OUTPUTNAME=testMulti -PACK=ALL -IGNOREMEMBERABSENCE+ -LOOKUP=*.sym=./sym;./sym_j3d -LOOKUP=*.bod=./bod;./bod_j3d -LOOKUP=*.rdf=./rdf;./rdf_j3d % path to application jars: -LOOKUP=*.jar=E:\J3D % main class name: -MAIN=MyMain % Application jars !classpathentry MyApp.jar -pack=noncompiled -protect=all -optimize=all !end
!classpathentry settings as appropriate for your application.
On this step, you compile the project files you have created with the Excelsior JET command-line compiler. Set
MultiCompBuild as the current directory and compile these projects using the commands:
jc =p library-project
jc =p executable-project
Now you can run the resulting executable.
For more comprehensive and detailed instructions on how to create multi-component Java applications with Excelsior JET, please refer to the Excelsior JET User’s Guide, Chapter “Dynamic Linking”, section “Multi-component applications”.
- Article 000022: HOWTO: Build a Multi-component Application
- Java 3D home page: http://java3d.dev.java.net
- Excelsior JET User’s Guide: http://www.excelsior-usa.com/jetdoc.html
Article ID: 28
Last Revised On: 11-Jul-2006