Tutorials

Sections

j3d.org

Java 3D Automatic Installation

With the release of Java 2 1.3 SDK, the problems of dealing with the user not having Java 3D installed are effectively removed. The VM, when instructed will automatically locate and install the right files for you.

Paul Pantera (formerly) from Sun Microsystems has provided us with a very detailed set of instructions on how to do this for Java 3D.

 

The Java Plug-In (JPI) replaces the Java in your browser with Sun's Java. To force your Java program to use the JPI and not your browser's default Java, you need to run your html code through Sun's html converter. The latest version of the Java Plug-In , version 1.3 (released 8 May 2000), supports this automatic installation feature you want. This version is only available for Windows. It is available for download at http://java.sun.com/products/plugin/ You can find the html converter at the same site.

The JPI keeps a list of each installed Java extension, along with version information. Java programs are packaged in jar files which contain manifest files. These manifest files contain information about which Java extensions are required by the program, and where to find them if they are not already installed on the target machine. This is a sample manifest file that I used to jar our HelloUniverse demo: 

Manifest-Version: 1.0
Extension-List: java3d
java3d-Specification-Version: 1.2
java3d-Implementation-Version: 1.2
java3d-Implementation-URL: http://chroma.eng.sun.com/gss-web/java3d.jar
java3d-Extension-Name: javax.media.j3d
Main-Class: HelloUniverse.class
java3d-Implementation-Vendor-Id: com.sun
Class-Path: java3d.jar
Note the 'java3d-Implementation-URL' attribute. This tells the JPI where to get Java 3D if it's not already installed. Sun does not have a signed Java 3D Jar file on a publicly accessible website for you to use. Therefore, you're going to have to serve the file off your own intranet.

     Note
    Extension-Installation is a brand new feature of Java 1.3, and the internal mechanisms aren't in place yet for each Java Optional Package to distribute signed jar files. Sun originally planned to make a signed jar available in Sep 2000. As of Apr 2001, Sun has run into "some legal and export control issues". Their current timeline for public availability is June. Until then, you need to serve the file yourself.

The Java 3D jar file you download from our website (For Windows users, this is part of the installer mechanism - a .exe file. You will need to collect the JAR files yourself from $jre.home\lib\ext) should be suitable because it contains the required manifest attributes. But just in case, this is how is was made. First, here is the manifest file: 

Manifest-Version: 1.0
Implementation-Version: 1.2
Specification-Version: 1.2
Extension-Installation: java3d1_2-win32-opengl.exe
Extension-Name: javax.media.j3d
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Specification-Vendor: Sun Microsystems, Inc
Notice the 'Extension-Installation' attribute. This is the name of the executable installer inside the jar file that gets run to install the extension. The manifest file and installer were jarred like this: 
jar cvfm unsigned_java3d.jar manifest.txt java3d1_2-win32-opengl.exe
This creates the file unsigned_java3d.jar. The java 3D jar file you download from our website will be unsigned as well. In order for the file to be dowloaded and installed, it must be signed. Signing the file lets your users know that what they are installing really is Java 3D and not a virus.

To sign files, you'll need a digital signature. During the installation process, the signature is checked with a Certificate Authority to make sure you are who you claim to be. Getting a signature is a process, so this is how you make a test signature.

Our test signing certificate, TestCert, was created like this: 

d:\jdk1.3\bin\keytool -genkey -dname "cn=Java 3D Team, ou=Computer Systems
Division, o=Sun Microsystems Inc., c=US" -alias TestCert -keypass pw1234
-keystore d:\keystore -storepass pw1234 -validity 1024
This created a "keystore" file to store the keys called d:\keystore. The key was then exported to a file key.cer: 
d:\jdk1.3\bin\keytool -export -alias TestCert -keystore d:\keystore -file
key.cer -keypass pw1234 -storepass pw1234
and then key.cer was double-clicked in the file explorer to install it.

Now that you have created and installed the signature, you can sign the Java 3D jar file: 

d:\jdk1.3\bin\jarsigner -keystore d:\keystore -storepass pw1234 -keypass pw1234
-signedjar java3d.jar unsigned_java3d.jar TestCert
Now you have a signed Java 3D jar file (java3d.jar) to place on your intranet. As long as your app points there, your users should be able to automatically install Java 3D when they try to execute a Java 3D app (as long as they have JPI 1.3). Good luck. Let me know if you find any problems with my instructions, or if you need more help.

For reference, the Extension Mechanism document is here: http://java.sun.com/products/jdk/1.3/docs/guide/extensions/index.html Click on "Optional-Package Versioning" for details on most of the above.

 

Custom Installers

"J. Lee Dixon did some research based on the original topic and found a way of creating your own custom installer. The original problems was that by default Sun's installation routine would default to putting the class files into the JDK 1.2 directory. As most developers were moving to 1.3 at the time this caused a problem because the applet, when run, would not correctly find the Java 3D classes and result in the system crashing. This fix to this is to create your own custom installer.

A custom installer does not need to do much. Firstly it must provide the six basic files: 

   bin/j3daudio.dll
   bin/J3D.dll
   lib/ext/j3daudio.jar
   lib/ext/j3dcore.jar
   lib/ext/vecmath.jar
   lib/ext/utils.jar
You need to create the installer with this set of paths. Now, you need to create the applet's JAR manifest file as before.

For your java3d.jar JAR file, you need to modify the Extension-Installation attribute of the manifest file. In the above example, this points to Sun's installer. As an alternative, you can create your own self extracting zip file that contains the above 6 files. Now, the entry becomes: 

  Extension-Installation: my_java3d_installer.exe
With this all in place, you should be able to automatically install Java 3D on any machine that has the same OS as the installer (Win32 in this case).

 

Notes

The installation process defaults to using JDK 1.2 install directories. Since this is not the required for most people you need to change this at install time. We've spoken with Paul about this and it won't be changed in the current release. However for the J3D 1.2.1 maintenance release it should default to using the JDK 1.3 directory.

This process will not work for Solaris/Sparc because the JPI is not available for that platform yet. However, the Java Extension Mechanism does provide support for different installers to be downloaded based on the user's system. A complete description can be found in this document, referenced at the bottom of my tutorial:

http://java.sun.com/products/jdk/1.3/docs/guide/extensions/index.html

When all of the pieces are in place, Java 3D will provide support for this feature, meaning your Java 3D apps can provide automatic installation of Java 3D for all systems that support Java 3D.

 
[ j3d.org ] [ Aviatrix3D ] [ Code Repository ] [ Java3D ] [ OpenGL ] [ Books ] [ Contact Us ]
Hosted by
Last Updated: $Date: 2006/04/18 18:20:05 $