Xj3D Browser Applet Example

Applet HTML

In order to display the above applet within html, the following attributes must be set. These represent a minimum requirement for an X3D scene in the Interchange profile. The jars that are listed as being located at "YourServer" are available as part of the Xj3D Project.

Applet Java

This example uses an embedded applet version of the Java Web Start application and then a custom subapplet that is stored in a seperate jar file. This jar file corresponds to "YourJar" and the name of the subapplet is referenced by the "subapplet.displayname" parameter. The classname that goes into this parameter should be the byte-code .class file that extends Applet. The rest of this tutorial will be structured as follows: First - Desription of the java code required to create a browser. Second - Walkthrough on how to construct the jar file, and the other server-end bits and pieces.

Code Requirements

Imports

The following imports are required for a very simple applet containing a browser:

External

   java.applet.Applet

   java.awt.*
   java.util.HashMap

   Internal

   org.web3d.x3d.sai.*;
   org.xj3d.sai.*
   

Class Declaration

The most basic version just extends Applet and does not need to implement any interfaces.

An example would look like this:

public class Xj3DAppletTutorial extends Applet {

Variables

The only global variable needed is of the type ExternalBrowser in this example we will call it browser.

ExternalBrowser browser;

Constructor

Since this is an applet, very little is guaranteed about the constructor, so the meat of the set-up is in the init method. in fact, in this example the constructor does nothing.

public Xj3DAppletTutorial() {
}

Methods from Applet

The only method that needs to be implemented in Applet is init. We override this to create the layout and the browser, and then to load the scene.

public void init() {
    setLayout(new BorderLayout());

    browser = getBrowser();
    loadScene();
}

Local Methods

There are a few local methods to facilitate creating the browser instance, and to load the scene. The parameters sent to the static createX3DComponent method can be customized or built from applet parameters, but in this case simplicity is the goal, and the console is added to the navigation bar just to make debugging possible.

private ExternalBrowser getBrowser() {
    HashMap<String, Boolean> requestedParameters = new HashMap<String, Boolean>();

    requestedParameters.put("Xj3D_ConsoleShown", Boolean.TRUE);
    requestedParameters.put("Xj3D_LocationShown", Boolean.FALSE);

    X3DComponent comp = BrowserFactory.createX3DComponent(requestedParameters);
    Xj3DBrowser browser = (Xj3DBrowser) comp.getBrowser();

    setBackground(Color.blue);
    add((Component) comp, BorderLayout.CENTER);
    setVisible(Boolean.TRUE);

    return browser;
}

private void loadScene() {
    X3DScene mainScene =
      browser.createX3DFromURL(new String[] {getParameter("modelURL")});

    browser.replaceWorld(mainScene);
}

Jar Walkthrough

Creating the Jar

As part of the Java SDK, there is a tool called jar that can be invoked on the command line. For an in-depth tutorial on how to use this tool, visit the Sun Jar Tutorial; this tutorial will just supply the necissary commands and will assume the environment is correctly setup.

Creating the jar requires a compiled, byte-code version (.class file) of the class created above. On the command line, entering the sequence jar cf JarName.jar ClassName.class will create the required jar in the working directory. This jar must be referenced by the applet, and the ClassName used in the jar must match the "subapplet.classname" parameter. Note that appending .class to the end of the classname will throw a ClassDefNotFoundException and will not work.

Signing the Jars

When an applet is referencing a jar, it must have a valid digital signature attached to it, in order for the JVM to be able to use it. Fortunately, there is a simple tool also included in the SDK called keytool which will create a keystore that will be used to sign jars. All of the jars used by the applet will need to be signed, and so it is convienient to place all of them in the same directory and use a script to automatically call the jarsigner tool to sign them for you.

Now that you have a keystore, and the key is signed, you can invoke jarsigner to actually sign the jar files. This can be done one at a time, with the command line command

jarsigner filename key alias.

This will require passwords for both the store and the key to be supplied. There are optional flags -storepass and -keypass that allow the passwords to be specified on the command line, but they are not manadatory. The alias argument is the name of the key, which the default is mykey. If you are running a UNIX based environment, the following shell script will sign all the jars in the same directory as the script.

#!/bin/sh
for filename in *.jar
do
	jarsigner -keystore [keystore path] -storepass [keystore password] -keypass [key password] $filename [key alias]
done

Once your jars are signed, the applet should run. There is a download size of about 6.5mb on the first start-up of the applet due to the jar files being cached, but on susequent starts within the same JVM session, the applet should start up rather quickly. In addition, making using of the Pack200 compression scheme offered in JDK 1.5 and later will reduce the file sizes to approximately 30% of the original download size.

Source File Examples

These can all be opened in a text editor, in the case that your operating system does not recognize the extensions.:

• Java Source
• Example Applet Tag
• Shell Script