Article ID: 000028
Last Revised On: 11-Jul-2006
PDF Version: 000028.pdf
The information in this article applies to:
The similar article for Excelsior JET 4.1 can be found here 000027.
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.
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.
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\lib\ext\j3dcore.jar;JRE-Home\lib\ext\j3dutils.jar;
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:
Before you run the compiled application, make sure that the Java 3D native method libraries can be found either:
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.
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.
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 (j3dcore.jar, j3dutils.jar, and 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, jc.
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
Edit -OUTPUTNAME=, -LOOKUP=*.jar=, -MAIN=, and !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”.
© 1999-2012 Excelsior LLC. All Rights Reserved.