Game Deployment with Java Web Start

Java Web Start is a deployment technology that can automatically download and install your games. All the users have to do is click a link on a web page, and the rest is automatic. It's one of the easiest methods of game deployment. You'll need a few tricks to set up your game to use Java Web Start. Here's an overview:

Put all game resources (images, sounds, and maps) in a jar file.
Sign the jar files.
Create a JNLP file, which descries the game and its resources.
Set up your web server to correctly serve JNLP files.

Retrieving Resources from .jar Files

First, you need to make sure all the game resources are stored in jar files. These can be separate jars, if you like-for example, you could have one jar for code, another for sounds, another for images, and so on. In the game itself, you can retrieve a file from a jar (as long as it's in the classpath) by using the getResource() method of ClassLoader, like this:

String filename = "path/image.png";
ClassLoader classLoader = this.getClass().getClassLoader();
URL url = classLoader.getResource(filename);

This returns the URL to a resource. You can also directly get the InputStream to a resource:

InputStream is = classLoader.getResourceAsStream(filename);

Signing .jar Files

Next, you need to sign the jar files (all of them, even if they don't contain any code). Signing the jar files is required for Java Web Start to assign the correct security permissions to your game. For example, you need security permissions to switch to full-screen exclusive mode. Signing the jar is like signing a contract-you sign it with your name to ensure that you wrote it and that the program will do no harm to the user's machine. First, you need to generate a key by using the keytool command-line tool included with the J2SDK:

keytool -genkey -keystore samplekeystore -alias Nobody

This creates a new key for the alias Nobody stored in the file samplekeystore. This command-line tool prompts you to enter a password and other information about you, including your name, organization, city, state, and country. To sign a jar, you can use the <signjar> task in your Ant build file, like this:

<signjar jar="${basedir}/tilegame.jar"
 storepass="secret"
 alias="Nobody"
 keystore="${basedir}/samplekeystore"/>

Here, you specify the alias Nobody, the password, the keystore, and, of course, the jar to sign. Remember, you've got to sign all jars for your game.

Creating a JNLP File

Next, you need to create a JNLP file. A JNLP file, short for Java Network Launching Protocol, describes the game and what security permissions and resources (jar files) it needs. JNLP files are XML files. You can see an example in Listing 18.4.

Listing 18.4 tilegame.jnlp

<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+"
 codebase="http://www.brackeen.com/javagamebook"
 href="tilegame.jnlp">
 <information>
 <title>Tile-based game</title>
 <vendor>David Brackeen</vendor>
 <homepage href="files\proquest.safaribooksonline.com"/>
 <description>Tile-based game</description>
 <description kind="short">A demo from chapter 5.</description>
 <icon href="icon.gif"/>
 <icon kind="splash" href="splash.gif"/>
 <offline-allowed/>
 </information>
 <security>
 <!-- get all permissions so we can access
 fullscreen exclusive mode -->
 <all-permissions/>
 </security>
 <resources>
 <j2se version="1.4+" initial-heap-size="32m"/>
 <jar href="tilegame.jar"/>
 <jar href="tilegameres.jar"/>
 </resources>
 <app-desc
 main-class="com.brackeen.javagamebook.tilegame.GameManager"/>
</jnlp>

Here you set the codebase for the game (www.brackeen.com/javagamebook) and the reference to the JNLP file (tilegame.jnlp) relative to the codebase. In the information section, there are references to two images: the icon and the splash image. The icon is used with the Java Web Start app Manager, as in Screenshot.

**The Java Web Start app Manager shows an icon for every app, along with the name, home page, and description.**

This shows a 32x32 version of the icon. A 64x64 version of the icon is used when downloading the app (see Screenshot); Java Web Start will resize the icon for any size needed. The icon can be in either the GIF or the JPEG format. Here, we use GIF to take advantage of transparency.

**The Java Web Start app Manager uses a 64x64 icon when downloading the app.**

Icons are used with the operating system's window manager as well-for example, if the user puts a link to the app in the Start menu in Windows. The splash screen is displayed when the app is loading. Java Web Start opens a new instance of the Java VM to run your app, and the splash screen is displayed during this time. If there is no splash screen, it uses the icon and displays something like the download dialog box in Screenshot. Permissions are set in the <security> tag, which you need for full-screen mode. The only choice is All Permissions, so you also can do other things such as save games to the user's computer or access a remote server. The rest of the JNLP file specifies the jar files you need (relative to the codebase) and the main class to start. Note that Java Web Start apps ignore the jar's manifest files: You still need to specify the main class in the JNLP file.

Setting Up a Web Server

There's really only one thing to do to set up a web server for JNLP files, and that's to associate the JNLP files with the correct MIME type: app/x-java-jnlp-file. This is required so that Java Web Start clients can load the file instead of web browsers. If you have your own Apache web server, you'll need to edit the mime.types file (often located at /etc/mime.types). Just add this line to the file:

app/x-java-jnlp-file JNLP

Then restart the server:

/etc/rc.d/init.d/httpd restart

If you're running on a shared web server or otherwise don't have root access, ask your webmaster to make the change. If your webmaster can't or won't, there's one other possible solution: Place a file named .htaccess in the top directory of your website that contains only one line:

AddType app/x-java-jnlp-file .jnlp

Note, however, that this works only on an Apache web server if it is set up to read the AddType command of .htaccess files. Ask your webmaster if you are unsure. It can be confusing to tell whether what you've changed actually works. If you've previously opened the JNLP file in your browser, you might have to restart your browser or even clear your browser's cache. If it is still difficult to tell what is going on, use the code in Listing 18.5 to get the returned MIME type of a remote file.

Listing 18.5 GetContentType.java

public class GetContentType {
 public static void main(String[] args) throws IOException {
 if (args.length != 1) {
 System.out.println("Shows the value of the " +
 "\"content-type\" header field of a remote file.");
 System.out.println("Usage: GetContentType (url)");
 System.out.println(
 "Example: GetContentType http://www.yahoo.com");
 }
 else {
 URL url = new URL(args[0]);
 URLConnection connection = url.openConnection();
 System.out.println(connection.getContentType());
 }
 }
}

You can use this simple program like this:

java GetContentType http://server/path/mygame.jnlp

If you set up your web server correctly, the program prints app/x-java-jnlp-file to the console. If not, it prints text/plain or something similar. That's it for Java Web Start. Another useful feature is some JavaScript and VBScript code to detect whether Java Web Start is installed and even to offer a one-click install of the Java runtime on Windows machines. You can download the JavaScript code at java.oracle.com/products/javawebstart/1.2/docs/developersguide.html.