Slick+Eclipse+JavaWebStart Tutorial

By Paul Gestwicki

This tutorial describes how to use Eclipse to facilitate the process of deploying a Slick-based game using Java WebStart. For more background, refer to the following links.

Configuration

Workspace Configuration

This tutorial assumes that you have the following project configuration in Eclipse.

src: Contains all of your source code
bin: Contains all of your compiled .class files
resources: Contains all of your media resources such as images and sounds

Keystore Configuration

In order for your application to access the native libraries required by Slick, all of the files you distribute must be signed using a digital certificate. The process of purchasing or otherwise acquiring a globally-recognized certificate is beyond the scope of this tutorial. You may choose to self-sign your files. Applications using self-signed certificates will warn a user prior to execution, but as long as the user agrees to run the application, they otherwise behave as any other signed application.

To self-sign your application, you must first have a keystore and a private key. The format for this command is given below.

keytool -genkey -keystore keyStoreLocation -alias name

For example, on a Unix-based system, you could create a keystore as a hidden folder in your home directory, using "me" as your alias, with the following command.

keytool -genkey -keystore ~/.keystore -alias me

The keytool application will ask you to identify yourself with a series of questions. For the sake of this example, I will assume you set the password to "mypassword". Towards the end of the questioning, you will be asked if you want a separate password for your key, separate from the password for your keystore. I will assume that you responded negatively.

Building with Ant

You can collect all of your programs' resources, from class files to sound effects, into a single jar file. However, one of the strengths of Java WebStart is that it allows you to separate your application into multiple downloadable jars. When a client sees that a jar has changed, it only needs to download the one that was modified. For our purposes, we will separate the application into two jars: game.jar will contain the compiled .class files and resources.jar will contain all of the media files.

Kevin Glass' WebStart Walkthrough provides an excellent guide for signing and deploying jars via WebStart, but since we're using Eclipse, we can make our lives much easier. Eclipse integrates support for ant, a language and tool for scripting development builds. Ant is designed to work best with Java, and so we will automate our jar building and signing through Eclipse and Ant.

Ant scripts are XML files, and they use the same comment markers as HTML.

Before delving into the sample ant file, let's first clarify what this script's responsibilities will be. First, the script will be able to create the game.jar and resources.jar files. Second, the script will sign these two jars using the certificate in our keystore. Since we are seasoned programmers, we will define some constants within the script to aid with readability and maintenance.

Script Header and Properties

Create your ant script by creating a file in your project called build.xml. It starts with the project tag, which defines the name of the project, the default build target (explained below), and the base directory. Since the script itself is in the root of your project directory, the current directory (.) is the base directory for the script.

Now we will set some properties, which act like global constants for the build script. The first three properties define the keystore information, and the fourth specifies where our script will dump its output.

Note that the names are arbitrary and can be changed, as long as all their references are also changed. Any string that is within ${ and } is a variable expansion. For example, the variable ${user.home} is set to a user's home directory by ant. Therefore, after our custom properties are processed, the value of ${keystore} will be the .keystore folder in the user's home directory.

Build Targets

Now it's time to define our build targets. When you run an ant script, you can specify which targets are built; if you do not specify, then the default target specified in the project tag is used.

The first target we will define is the customary "all" target, which by convention is used to build everything. In our case, this is done by specifying the names of the three other targets in the script, which are defined later.

<target name="all" depends="init,game.jar,resources.jar" />

No matter which target we are building, we need to ensure that the output directory exists. The init target will take care of this.

<target name="init">  <mkdir dir="${out.dir}" /> </target>

Next, we will define the target that creates game.jar. Note that there is no necessary connection between the name of the target and the file it creates. I have simply used the name of the target's product as a mnemonic.

This target actually does two things. First, it runs the jar tool on the project's bin folder, collecting all of the compiled .class files into a single jar. Then it runs the signjar tool using the properties we defined above. The jar and signjar tags are built into ant, and their attributes describe how the tools are run; that is, these attributes are rearranged by ant into the appropriate command-line arguments for the shell commands jar and signjar. The XML formatting of the ant script tends to make these potentially lenghty command strings much more readable, although admittedly more verbose.

<target name="game.jar"> <jar destfile="${out.dir}/game.jar"> <fileset dir="bin" includes="**/*.class" /> </jar> <signjar alias="${alias}" storepass="${keystore.password}" keystore="${keystore}" jar="${out.dir}/game.jar"/> </target>

The last target is similar to the previous one: this target will collect all of our media resources into a single resource.jar file, then sign it.

<target name="resources.jar"> <jar destfile="${out.dir}/resources.jar" basedir="${basedir}/resources" /> <signjar alias="${alias}" storepass="${keystore.password}" keystore="${keystore}" jar="${out.dir}/resources.jar" /> </target> </project>

Finally, to run your ant script, right-click on the build.xml file and select "Run As..." and "Ant Build". The console will report on the scripts activity. If everything was set up correctly, then you should have two signed jars, game.jar and resources.jar, in your home directory.

This ant build script is relatively simple, but if you're working on a project of nontrivial size, you certainly could make a more robust script. For example, you can define properties for your source and bin folders or separate the resources into images, sound, and music jars. Ant supports a vast range of commands. These are described in the Apache Ant Manual, a great resource if you want to customize your scripts.

JNLP

Now that you have your two signed jars, you are ready to post your game for the world (wide web) to see. For the same of this example, I will make the following assumptions:

Your host is www.cs.bsu.edu
Your username is me, making your homepage http://www.cs.bsu.edu/~me
You are using Java 1.6 or higher
In your game, the main entrypoint is edu.bsu.me.TheGame.

For the sake of this example, I will assume that you are posting your game to the folder ~/game on the host www.cs.bsu.edu and that your username is "me". For simplicity, we will link directly to the Slick libraries hosted at cokeandcode.com. That site is configured to resolve the platform-specific library dependencies. If we did not do this, then we would have to host and sign the native libraries ourselves. If you were to do this, you can find some tips at Kevin Glass' WebStart Walkthrough.

Make a file called game.jnlp. This XML file specifies to the Java Virtual Machine how to run your application. For our example, the file would look like this:

<?xml version="1.0" encoding="utf-8"?> <jnlp spec="1.0+" codebase="http://www.cs.bsu.edu/~me/games" href="game.jnlp"> <information> <title>The Title of my Game</title> <vendor>My Name (or Vendor Name)</vendor> <homepage href="http://www.cs.bsu.edu/~me"/> <description>A description of the game</description> <description kind="short">A one-line description of the game</description> </information> <resources> <j2se href="http://java.sun.com/products/autodl/j2se" version="1.6+"/> <jar href="game.jar"/> <jar href="resources.jar"/> <extension href="http://slick.cokeandcode.com/demos/slick.jnlp"/> </resources> <application-desc main-class="edu.bsu.me.TheGame"/> </jnlp>

Copy game.jar, resources.jar, and game.jnlp to ~/game, and make sure the permissions are correct. For example, in a UNIX-style environment, you can run these commands:

chmod a+rx ~/game chmod a+r ~/game/*

Now, if you have Java installed, you should be able to open http://www.cs.bsu.edu/~me/game/game.jnlp in your favorite web browser, and this will launch your game. If you don't have the requisite version of Java (1.6), then you will be directed to install it. The Slick libraries will download from cokeandcode.com. Since those libraries are signed by their creator and your game files are signed by you, you will have to click through two dialog boxes before the game launches. (Note that, although annoying in this case, this is important. In the JNLP file, we requested that our application have "all-permissions", meaning that it could do something destructive like overwrite or remove files. These dialog boxes disappear if you're willing to pay for a certificate from a recognized certificate authority.)

There are more details you can add to your JNLP file as well. For example, you can use the icon tag to specify an application icon or even a splash screen that is shown while the application is loaded.