Jirr and Java Web Start - Draft

[saigumi]

I will be adding this to the wiki as well. But here is a rough draft of the tutorial.

You can download it and all the code at http://www.saigumi.net/files/jirrwebstart.zip


----------------------------
Deploying Jirr applications via Java Web Start

** This tutorial is set up for a Windows environment. However, it should be possible to get it to run in a Linux/Other environment. **

Purpose
The purpose of this tutorial is to make a professional style compilation and deployment system for Java based applications that also happens to use Jirr and Irrlicht.

This will involve all steps from development of the application, building a package, signing a package, and deploying a package. When you are done, you should have an application that can be run off a webpage by a user that takes 3 clicks to run. I wish it could be easier, but in this day of foul programs being deployed over the web, the extra clicks for security certificates and such is increasingly important.

IMPORTANT!

I understand that it's hard to read tutorials sometimes and if your a like me, you skim alot. I will flag anything that is direly critical and needs to be done to save any frustration of something that was missed if you skimmed over it.

Gotcha!

Through the course of setting up my first project in using Jirr and Web Start, I encountered many "Gotchas!" that were did not have not easilly realized solutions. I will attempt to document all of these and include them in the course of the tutorial. Anytime that something just doesn't work properly, look for a "Gotcha!" in the section.

Shortcut!

If you are just fiddling around and don't want to go through some of the hassles involved in a true deployment, I have included a few steps that can be bypassed and not completely hinder functionality. These will save some time and make the whole process slightly simpler.

If there is a shortcut possible, I will put (Shortcut! Available - {Name of Section}) in the title of the section. The name of the section will be included so that you can do a quick search to get to it.

Bibliography

These are the sites I used for information in creating my first application and may be extremely helpful.

Sun's Java Webstart Developer Guide - http://java.sun.com/j2se/1.4.2/docs/gui ... tents.html
Unofficial Webstart FAQ - http://webstartfaq.com/
Richard Dallaway's Java Web Start and Code Signing - http://www.dallaway.com/acad/webstart/
Apache Ant Manual - http://ant.apache.org/manual/index.html

Definitions

JAR - Java Archive. Basically a glorified ZIP file. JARs are compressed archives that contain classes, property files and some special Java related files.


Prerequisite

What you need:
Java 2 Standard Edition SDK version 1.4 or newer - http://java.sun.com.
My Jirr-Webstart files - http://www.saigumi.net/files/jirrwebstart.zip

Optional
Apache Ant - http://ant.apache.org
Jirr Source is already included, but you can get newer versions at http://jirr.sourceforge.net

Using Ant Overview

Apache's Ant handles building and packaging Java-based applications. I highly recommend installing it and integrating it with your current Java IDE as it takes the tedium and repetition out of the compiling process. I have included a build.xml file that will be used to perform the many of the manual steps involved.

When using Ant, you first create a series of steps to be run known as targets. Targets can be link together to enforce running order and such. Since this isn't a tutorial on using Ant, I will directly lay out any commands that need to be run or fields that need to be changed.

To install Ant, extract the contents of the ZIP to a directory like c:/lib/ant. In Windows, go to Control Panel->System->Advanced->Environment Variables. Add the variable ANT_HOME and set it to where you extracted it (c:\lib\ant). Add the ant bin directory (c:\lib\ant\bin) to your PATH as well.

Starting Out

Unzip the contents of jirr-webstart.zip onto one of your drives. For all intents and purposes, I will assume this to be c:\projects\jirr-webstart as there is one place that this needs to be specified exactly.

In this file you will find:
\bin - Location of Windows specific DLLs
\res - Resources like Images and Security Keystore
\src - Source code for Jirr and the sample application jirrwebstart
build.xml - The Ant Build file. This controls how the project is built.
jirrwebstart.jnlp - The Java Webstart file. This controls how your application is deployed to the user.

Security Now - Signing JARs Properly (Shortcut! Available - Signing JARs Yourself for Testing)

Java Webstart requires that all JARs be signed. Signing a JAR is a way of saying to the End User that this code is trusted by you and a third party. This is also a way to instill a little more confidence from the end user as it give information on exactly who made the application and that it hasn't been tampered with since you created it.

There are plenty of third party companies out there that will sell you certificates to sign your code with, but the one I found is a free certificate from Thawte.

Sign up for a free email certificate here - http://www.thawte.com/secure-email/pers ... index.html

IMPORTANT!
Fill everything and confirm your email address until you get to the point that it asks what type of X.509 email certificate that you want. At the bottom of the page is a link that says "Developers of New Security Applications ONLY". This is the one you want. Clicking it should take you to a page that has you select "Paste-in CSR Certificate Enrollment". Click next and you should be at a page that has a large textbox asking for your public key.

On this page, it should display your "common name" as something like XVV6ePaMGHEPJN22. You will need this in a second.

Open up a command prompt (Start->Run and type in "cmd" and hit enter.). Change directories to where you want to keep your keystore. For this example, I put mine in c:\projects\jirr\res. (cd c:\projects\jirr\res)

Now, run the Java Keytool to generate a key for yourself and answer the questions. When it asks for your "first and last name", use the "common name" that Thawte has given you.

keytool -genkey -keyalg RSA -keystore keystore.ks -alias {your alias}

Example:
$ keytool -genkey -keyalg RSA -keystore keystore.ks -alias mr.example
Enter keystore password: trustno1
What is your first and last name?
[Unknown]: XVV6ePaMGHEPJN22
What is the name of your organizational unit?
[Unknown]: Headquarters
What is the name of your organization?
[Unknown]: example.com
What is the name of your City or Locality?
[Unknown]: St. Louis
What is the name of your State or Province?
[Unknown]: Missouri
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=VsrM6zxs7edzfJ57, OU=Headquarters, O=example.com L=St. Louis, ST=Missouri, C=US correct?
[no]: yes

Enter key password for <mr.example>
(RETURN if same as keystore password):
$

Now, export your keystore to a text file using:

keytool -certreq -keystore keystore.ks -file csr.txt -alias {your alias}

Example:

keytool -certreq -keystore keystore.ks -file csr.txt -alias mr.example

Open up csr.txt and copy all of the text inside, including the "CUT HERE" portion. Paste that into the textbox on the Thawte page and click OK.

Thawte will send you an email when it has been signed. Mine too about 15 minutes. When this is done, you can download it. In the file is actually two certificates. Start from the section that says PKCS7, and copy that part to a file called "my.cert". You do not want the Netscape part.

Now, run the keytool to import that certificate into your keystore.

keytool -import -file my.cert -alias {your alias} -trustcacerts -keystore keystore.ks

Example:

keytool -import -file my.cert -alias mr.example -trustcacerts -keystore keystore.ks

You should see the message: Certificate reply was installed in keystore

GOTCHA!

If the import failed with an error code of -96, download this http://www.dallaway.com/acad/webstart/thawtecleaner.jar to your jirrwebstart\res directory (c:\projects\jirrwebstart\res). This download will clean the file for you.

Run it by using:

java -jar thawtecleaner.jar my.cert

Try importing certificate to the keystore again.

You are now ready to sign jars.

Signing JARs Yourself for Testing

** Skip this if you have already created a certified keystore in the previous section - Security Now - Signing JARs Properly**

If you are just testing, or feel that your end users don't care about sercurity one bit. You can sign the JARs yourself with an uncertified keystore.

Open up a command prompt (Start->Run and type in "cmd" and hit enter.). Change directories to where you want to keep your keystore. For this example, I put mine in c:\projects\jirr\res. (cd c:\projects\jirr\res)

Now, run the Java Keytool to generate a key for yourself and answer the questions.

keytool -genkey -keyalg RSA -keystore keystore.ks -alias {your alias}

Example:
$ keytool -genkey -keyalg RSA -keystore keystore.ks -alias mr.example
Enter keystore password: trustno1
What is your first and last name?
[Unknown]: Mr. Example
What is the name of your organizational unit?
[Unknown]: Headquarters
What is the name of your organization?
[Unknown]: example.com
What is the name of your City or Locality?
[Unknown]: St. Louis
What is the name of your State or Province?
[Unknown]: Missouri
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=Mr. Example, OU=Headquarters, O=example.com L=St. Louis, ST=Missouri, C=US correct?
[no]: yes

Enter key password for <mr.example>
(RETURN if same as keystore password):
$

You are now done.

Building the application

Now that you have your keystore in place, you need to configure the signjar calls in the Ant Build.

Open up build.xml for editing.

Find the two "signjar" calls and change the alias to your alias and the storepass to your keystore's password.

Example:
<signjar jar="${basedir}/jirrwebstart.jar"
storepass="tellno1"
alias="mr.example"
keystore="${basedir}/res/keystore.ks"/>

<signjar jar="${basedir}/jirrws-windows.jar"
storepass="tellno1"
alias="mr.example"
keystore="${basedir}/res/keystore.ks"/>

Save the file.

At this point, you can now build the application without any further changes. Open a command prompt to the irrwebstart directory (c:\projects\irrwebstart) and run Ant.

Example:

ant

Seriously, the whole command is "ant". By default, if you did not include any parameters, Ant will run the "build" target as it is configured.

In the build.xml file:
<project name="JIrr - Webstart Example" default="build" basedir=".">

Output:
Buildfile: build.xml

clean:
[delete] Deleting directory c:\projects\jirrwebstart\build
[delete] Deleting: c:\projects\jirrwebstart\jirrwebstart.jar
[delete] Deleting: c:\projects\jirrwebstart\jirrws-windows.jar

compile:
[mkdir] Created dir: c:\projects\jirrwebstart\build
[javac] Compiling 158 source files to c:\projects\jirrwebstart\build

build:
[jar] Building jar: c:\projects\jirrwebstart\jirrwebstart.jar
[jar] Building jar: c:\projects\jirrwebstart\jirrws-windows.jar
[signjar] Signing JAR: c:\projects\jirrwebstart\jirrwebstart.jar
[signjar] Signing JAR: c:\projects\jirrwebstart\jirrws-windows.jar

BUILD SUCCESSFUL
Total time: 38 seconds

We'll take a closer look at the way things are built later, let's run it first instead.

Running On Your Desktop

Before deploying this to a server, you may as well make sure it works by running it on your desktop.

This is where the jirrwebstart.jnlp file comes into play. A JNLP is a Java Webstart file that defines information about your application such as it's name, description, what version of Java you want it run using, etc.


IMPORTANT!

To set this to run, you have to point the codebase to the correct location of where you are placing all of the JAR files.

<jnlp spec="1.0+" codebase="{URL Location}" href="jirrwebstart.jnlp">

Example:

If you are running this on your desktop:

<jnlp spec="1.0+" codebase="file:///c:/projects/irrwebstart/" href="jirrwebstart.jnlp">

Or, if you are running this on your webserver:

<jnlp spec="1.0+" codebase="http://www.example.com/jirr" href="jirrwebstart.jnlp">

GOTCHA!

If you set this incorrectly, Java Webstart will not be able to find the JARs and will sit at the "Starting Application..." screen with a flashing progress bar.

To run your application, you should be able to double click on the jirrwebstart.jnlp file. You should get a Splash sceen and a loading screen and see Java Webstart copying your JARs to the cache. It should then ask if you approve of the signing (with a harsher warning if the signing did not have a certificate). After that, a 640x480 grey window will appear. This is the actual Jirr application. Go ahead and close it.

Messing Around With the Build

Let's take a look at the building process. Open the build.xml file.

This is a very basic setup for creating a build. The "build" target gets run, which depends on the "clean" and "compile" targets, so they run first. "Clean" removes the old jars and build directory. "Compile" runs JavaC on the source directory and puts the classes in the build directory.

"Build" jars the classes into jirrwebstart.jar and sets the manifest to run the net.saigumi.jirrwebstart.Main class as it's Main. It also jars the Windows specific binaries into jirrws-windows.jar. While I could have jar'ed all of these together into just one, seperating out the Windows specific components will mean that you can target the amount of files that you need to actually send to a user. In this same way, we could package up the Linux binaries into a jirrws-linux.jar. The JNLP controls this deployment, so we will get into that later.

The next step is to sign the jars. Since we have gone over this, there isn't a need to do so again.

You may also notice the "javadoc" target is in the build.xml file but is not called. This is on purpose as I didn't feel a need to create javadocs on each compile. If you want to generate some javadocs, run the ant command:

ant javadoc

Java Webstart JNLP

This is the true challenge of getting your application to run. Java Webstart is a relatively new feature of Java that is bundled with Java 1.4+. It has it's share of bugs and is supposively more stable in Windows than it is in Linux. Improperly configuring this file can bring on more and severer headaches than beating your head into a wall.

Open up jirrwebstart.jnlp.

We have talked about the codebase and href a little bit, but just remember to always set it for where you put it.

Now, there is the information section:

<information>
<title>Jirr Webstart</title>
<vendor>John Goewert</vendor>
<homepage href="."/>
<description>An example of using Java Webstart to load an Irrlicht application that uses the Jirr wrapper from a webpage.</description>
<description kind="short">Use Java Webstart, Jirr, and Irrlicht on the web.</description>
<icon href="res/icon.gif"/>
<icon kind="splash" href="res/splash.gif"/>
<offline-allowed/>
</information>

"title" is the name of your application.
"vendor" is you or your company
"homepage" is you or your company's webpage. You could put a real URL or just a period (.) for "Right HERE!"
"description" is to write about what your application does. You can create a short description by adding the kind="short" attribute.
"icon" this is a picture to show during the Java Web loading screen next to the title of the application. This is NOT an icon file (.ico) You can specify a larger splash graphic as well by adding the kind="splash" attribute. This image should appear just before the loading screen comes up, but is known to be problematic.
"offline-allowed" is an element that says that you don't need to be connected to the Internet to run your application.

The security section is something I haven't messed with too much. I suppose you could set it to be read only or disable the use of network connections to make the application safer for the end user. I went with the full permissions mode.

Example:
<security>
<!-- get all permissions so we can access - fullscreen exclusive mode -->
<all-permissions/>
</security>

The application-desc section is just a set of information about how to run your application. The only field needed to be set is the main-class. This may seem redundant to the manifest that you created when jar'ing everything during the build, but this overrides it so that if you have multiple jars that have manifests with main classes, you can finger out the correct one.

Example:
<application-desc main-class="net.saigumi.jirrwebstart.Main"/>

Lastly, is the resource section/sections. In this case you can specify which jars need to be loaded and by what operating system and such. The basic resources section goes something like this:

Example:

<resources>
<j2se version="1.4+" href="http://java.sun.com/products/autodl/j2se"/>
<jar href="jirrwebstart.jar" version="0.1"/>
</resources>

"j2se" defines what version of Java the user should have. You can specify an additional href to run if the user does not have that version installed. In this case, it goes to the Java auto-downloader. This autodownloader only works in Windows.

"jar" specifies the file to load as well as what version to specify. The version isn't important now, but if you plan on WAR'ing up your application and enforce versioning of your own file, it will be.

One other thing to note is that if you plan on including a third party jar and it is already signed by them, you will need to include it via it's own jnlp file.

This is done using the extension element in the resources section

<resources>
<jar href="myjar.jar">
<extension name="OtherJAR" href="someotherjar.jnlp"/>
</resources>

Now, one of the cool thing about resources is that you can segment out pieces to download per OS. In the case of Jirr, there are some Windows specific DLLs that only Window users can use.

Example:

<!-- Windows Specific Resources -->
<resources os="Windows">
<j2se version="1.4+" href="http://java.sun.com/products/autodl/j2se"/>
<nativelib href="jirrws-windows.jar"/>
</resources>

Notice the os="Windows" in the resources element. This says to only load these resources if the OS running is Windows.

The special line here is "nativelib". This is equivalent to the "jar" element except that it tells the operating system to handle the contents as it would normal DLLs and not just as a filesystem.

GOTCHA!

If this was just specified as a JAR, the application will compain about missing the DLL files even though common sense would tell you that if your jar was in the classpath, it should be accessible to be loaded.

You will get a "Could not find Irrlicht.dll" in this instance.

There is one other point of importance here that ties into the source code, so lets look into it.

The Source Code

Open up "src/net/saigumi/jirrwebstart/Main.java". If you have had experience with Jirr, you may notice something funny right off the bat.

If not, open up one of the Jirr examples. Notice this part in Jirr's example:

static {
System.loadLibrary("irrlicht_wrap");
}
Now look back at jirrwebstart's:

static {
System.loadLibrary("D3DX81ab");
System.loadLibrary("D3DX92ab");
System.loadLibrary("Irrlicht");
System.loadLibrary("irrlicht_wrap");
}

Now, your innate Java sense may say "But if you load the irrlicht_wrap library, it will chain load the rest of the libraries it is dependent on!" and you would be correct. However...

GOTCHA! IMPORTANT!

Therei s currently a bug in the Java Web Start that you need to manually handle the dependecies of the libraries you need loaded. Extra annoying is that you need to load the dependecies first.

So, since irrlicht_wrap.dll is dependent on Irrlicht.dll, you need to load Irrlicht.dll first. But since Irrlicht.dll is dependent on D3DX81ab and D3DX92ab, you need to load them first.

Fortunately, we don't have any cyclical dependencies. If we did, Java Web Start could not be used at this time because you would get caught in a loop of X needs Y, but Y needs X, but X needs Y,..... until your CPU explodes or you get a Java error.

Deploying Your Application

Now for the fun part, tossing this sucker up on the web to share and enjoy. Simple? Yes, for the most part.

If you have your own apache server, open up the configuration and make sure these lines are included:

AddType application/x-java-jnlp-file .jnlp
AddType application/x-java-archive-diff .jardiff

Restart Apache.

GOTCHA!

If you are using some sort of shared hosting like Geocities, more than likely, they do not have their server set up to handle jnlp files correctly. The jnlp will open up and display the XML instead of actually running.

You can bypass this in multiple ways.

If your host supports .htaccess files, just create a file called .htaccess where your jars are and put the above lines in.

If they support PHP, add this to the beginning of your jnlp file;:
<? header ("Content-Type: application/x-java-jnlp-file"); ?>

If they support Java Server Pages, use this:
<%@ page contentType="application/x-java-jnlp-file" %>

Open up your irrwebstart.jnlp file and change the codebase to your webserver's URL.

Then Toss the two jars and the jnlp file onto your server.

Now, all you should have to do is point your browser to the location and your application should run.

Conclusion

That's about it. At this point you have a working deployment to run Jirr based applications off of a webpage. I have begun writting a supplement to this Tutorial called "Jirr Webstart - One Step Further" that goes into WAR'ing everything, deploying multiple party vobs, the horrors of classpaths, and such.

[theduck]

Wow! Cool! I'll have to try this out.

By the way, you wouldn't happen to have a tutorial/article about
using Jirr with Netbeans IDE or JBuilder would you? I'm a tad bit confused, being
new to the world of Java (But not programming of course). Thanks in advance!

[pinballwizard]

Deploying Jirr applications via Java Web Start

** This tutorial is set up for a Windows environment. However, it should be possible to get it to run in a Linux/Other environment. **

Has anyone gotten this to work for Linux or Mac OS X?

Also, what about using ODE for physics? I think there is a Java binding for ODE (looks outdated though, not updated for a year). Could you deploy ODE through Java Webstart also?

And, for the final question... what about using Jython so I can program in Python but call Java routines that then call Irrlicht/ODE through JNI? Then I could program in Python but distribute it as a one-click Java Webstart app. Would that work?

[Strong99]

i have downloaded the bins, so what i read you can't run it in a website, but opens a seperated window with the game/app?

[mother_man]

Set up in netbeans :

create a key as describe with keytool

download the JWS pluggin for netbeans

Put the dll in a jar

add this to build.xml

Code: Select all

  <target name="jar" description="Sign JAR file">
        <signjar jar="dist/dll_bind.jar" alias="xxx" storepass="xxx" signedjar="dist/dll_bind.jar"/>
        <signjar jar="dist/jirr13.jar" alias="xxx" storepass="xxx" signedjar="dist/jirr13S.jar"/>
        <signjar jar="dist/appli.jar" alias="xxx" storepass="xxx" signedjar="dist/appli.jar"/>
  </target>    

this will automatticly sign your jars after builds (usefull because building new jar (compilling) erase last signature)

then right click on your project name in the netbeans project explorer
choose -> JWS -> Debug

thats it