This chapter finishes the book by explaining the all-important subject of how to deploy your Java applet-based games to the web. I assume you already have some knowledge about how to use FTP to copy your game to a web server. I will show you how to prepare the applet so that it will run from your own web page! (Even if you use a free hosting service, if you can upload the files to your website, then very likely the game will run from your site.) You will also learn how to use the Java Archive tool to bundle your entire game (with class files and all media files together) in a Java Archive file.
Here are the key topics in this chapter:
Packaging an applet in a Java Archive (JAR)
Using the JAR command-line program
Packaging Galactic War into a JAR file
Creating a host HTML file for the applet
The Java Development Kit (JDK) comes with a command-line tool called jar.exe that is used to create Java Archive files. JARs, as they are known, use the ZIP compression method when storing files. JARs can greatly reduce the size of a Java applet—which is crucial for web deployment.
To use the JAR tool, you will need to open a command-prompt window (also known as a shell in some operating systems), and then set the path to the JDK if it is not already set. By default, on a Windows system, the JDK is installed at C:Program FilesJava, and under this folder there will be a folder containing the JDK and the Java Runtime Environment (JRE). You need to set the path to include the in folder located in the JDK. This will differ depending on the version of JDK you have installed. Currently on my system, the jar.exe tool is located here:
C:Program FilesJavajdk1.6.0_22in
You can open the command prompt by going to Start, Program Files, Accessories. You can also run cmd.exe manually using Start, Run. On Linux and Mac systems, the JDK is usually already added to the path when it is installed.
Tip
If you added Java to your system path as described back in Chapter 1, then you should be able to run jar.exe from anywhere.
The JAR tool is a bit finicky. If you don’t use the parameters exactly right and in the correct order, JAR will complain and fail to create the JAR file you wanted it to create. The order of the parameters should not be significant, but it is in this case. The general syntax of the JAR command can be viewed by typing JAR at the command line. The output looks something like Figure 16.1.
The parameters in this Help listing are deceptive. Not only should you not use the dash (—), but these parameters must be specified in a specific order. For instance, we use the “c” parameter to tell JAR to create a new JAR file. But this parameter must be used along with “f” to specify the filename. I can’t imagine a situation where you would want to use the JAR tool without using a JAR file, but I guess that’s just me. After the “cf” parameters, you specify the JAR file name, and then the files you want to add. Here is an example:
jar cf test.jar *.class
This command will create a new JAR file called test.jar and add all .class files found in the current folder to the JAR file. After doing so, if the JAR tool successfully created the new JAR file, it will simply exit and not print anything out. (So remember, no display equals no problems.)
To display the contents of a JAR file, use the “tf” parameter, like so:
jar tf test.jar
You can also include the “v” option to display the contents of the JAR file with details. This option also works when creating a new JAR file, but you must be careful to include the “v” option after the “c” or “t” parameter. Here’s an example of both cases:
jar cvf test.jar *.class jar tvf test.jar
You can extract a single file or all files from a JAR file using the “x” option, like this:
jar xvf test.jar *.*
You can update a JAR file using the “u” parameter. Any files you specify will replace existing files in the archive, and any new files will be added.
jar uvf test.jar HelloWorld.class
Java archives can include a manifest file that tells the JRE the name of the .class file it should run (automatically) when it opens the JAR file. Since this is a fairly common occurrence, and manifest files are a cinch, it makes sense to include one in a JAR file that will run on the web. The general format of the manifest file looks like this:
Main-Class: Filename
You should not include the .class extension. There are more options for manifest files, but this is the only one you need to be concerned with when the goal is to run an applet stored in a JAR file on the web.
Caution
Be sure to add a blank line after this single line in the manifest file, or the JAR tool will complain.
To use a manifest file when creating a new archive, you can use the “m” parameter option. Just be sure that this is the last letter in the options you include.
jar cvfm test.jar manifest.txt *.class *.png
The JAR program is fairly easy to use once you get used to its specific requirements. Now let’s use this tool to package Galactic War into a Java archive. This will save a little space and will keep the game together in a single file so you won’t leave any media files behind when copying the game or uploading it to a website.
Caution
You must load files in a certain way in your code so that the JRE will know how to read them from a JAR file when you have deployed the applet to a website. I’ve shown you a couple of different ways to load images and other media files in this book.
The method you must use when a game is deployed in a JAR uses the java.net.URL class and the getResource() method to create a URL that you can pass to the appropriate image or sound loader. The getResource() method is available from this.getClass(). This method will correctly pull a media file from the local file system or from a JAR file when resources are stored within a JAR. Here is an example:
URL url = this.getClass().getResource(filename);
The first order of business is to copy your project folder to a new location so you don’t accidentally mess up the original. Essentially, this new folder contains the runtime files for the game—the .class files and all assets. You do not need to add the .java files to the .jar file that will be distributed to the web server.
Now let’s create a Java archive to contain the files needed by this game. The manifest.txt file and index.html file (covered next) are found in the GalacticWar folder. I have copied all of the Galactic War media and class files into a folder called GalacticWarproject. Included are 30 image (PNG) files, two audio files, and one MIDI file. In addition, we have these nine Java class files:
AnimatedSprite.class
BaseGameEntity.class
Game.class
ImageEntity.class
Point2D.class
Sprite.class
GalacticWar.class
MidiSequence.class
SoundClip.class
These files were compiled using Java SE 6. That’s a lot of files for a single game! The last thing I want to do is deploy this game to a web server by copying all of the files along with index.html, although that is definitely a workable option. In fact, if you just edit the HTML file (which you’ll learn to do here shortly), you can simply copy these files to a website and run the game over the web. But a Java archive works so much better, and it saves some space too. Instead of streaming all of those many dozens of bitmaps, classes, and audio clips to the applet, it just streams the single .jar file.
Using the CD command in the command prompt, I’ve changed the current folder to chapter12GalacticWar. (This may be slightly different on your system.) You can perform this step from any folder where your project files are located. I’ve copied all of the class and media files to a subfolder called “project” to keep things tidy. So, all I have in this main GalacticWar folder are index.html, manifest.txt, and the project subfolder (see Figure 16.2).
The manifest.txt file for Galactic War contains this line:
Main-Class: GalacticWar
This tells the JRE which of the .class files to open up and start running after opening the JAR file. (Be sure to include a blank line after the Main-Class property line.)
You will need to use an optional parameter of the JAR program that lets you specify a subfolder where the actual files are located. You don’t want to just tell it to include .project*.* because that will add .project to the internal structure of the JAR file. Instead, you want to grab all the files inside of .project, but not include the folder name. The option is “C” (uppercase is important). Here’s the command to create the GalacticWar.jar file:
jar cvfm GalacticWar.jar manifest.txt -C project *.*
This line tells JAR to create a new Java archive called GalacticWar.jar, to include the manifest information stored in manifest.txt, to use the project subfolder, and to add all files in that subfolder to the JAR file. Figure 16.3 shows the output of the command.
If these additional steps get on your nerves, just lump everything together in a single folder and run the JAR program in the same folder as all your Java project’s files, without using the C option, like so:
jar cvfm GalacticWar .jar manifest.txt *.*
HTML is short for Hypertext Markup Language, and it is the water flowing through the world wide web. To run a Java applet on the web, you have to embed the applet inside a webpage. This involves creating an HTML file with an <applet> tag that specifies the details about how to run the applet and where it is contained. If you use an IDE such as NetBeans, then just launch the program as an applet and the IDE will generate the HTML container file for you. But, if you want to deploy your applet to a web server, then you do need to create your own HTML file.
The most basic format for an HTML file that will host an applet looks like the following code. This code assumes that a file called game.class is available in the same web folder as the HTML file.
<html><head> <title>This is my game</title> </head> <body> <applet code = game.class width=800 height=600> </applet> </body> </html>
The key to running an applet inside a Java archive is to add another option within the <applet> tag called archive.
<applet code=game.class
archive=game.jar
width=800 height=600>
</applet>
The webpage file is usually called index.html because that is the name of a file that web servers will send the web browser automatically if you don’t specify the HTML file directly. For instance, when you go to www.jharbour.com, the web server delivers index.html automatically. You can create this simple HTML file using a text editor such as Notepad (as shown in Figure 16.4). If you want your applet to be stored with your other web files, including your already-existing index file, then just use a different name, such as GalacticWar.html.
When you have the HTML host file and a JAR file ready to go, it’s time to upload them to your web server. I’ve created a folder on my web server called /BeginningJava that I’ll use to deploy the Galactic War files. The index.html and GalacticWar.jar files are both uploaded to www.jharbour.com/BeginningJava and are ready to run from this location. When you open this URL, the web browser fires up the JRE, which displays an attractive logo image and a progress bar while it downloads the JAR file (see Figure 16.5). (Note that this logo may look slightly different on your system.)
Tip
The great thing about an applet is that your web browser will store it in the web cache. That is why the applet seems to just open up immediately when you go to the same URL again. The applet does not need to be downloaded again when it is stored in the local web cache.
When the applet has completely downloaded to your local system, it will access the files in the JAR locally rather than hitting the web server for every file. Remember the list of 40+ media files in Galactic War? If the game were deployed to the web server with all of those individual files, the applet would have to download every single file individually over the Internet. That’s a lot of file transfers! But when your applet is stored in a JAR, that single JAR file is downloaded to your PC, and the applet runs from there. All media files are drawn directly from the JAR file instead of from the web server. If all goes well during the downloading of the JAR file, the game should come up as shown in Figure 16.6.
Java applets can grow quite large when you are writing a game because most games use dozens of media files. By packaging a Java applet-based game into a Java Archive (JAR) file, you dramatically improve the time it takes to download and run the game from a web server. You also cut down on the number of transfers that must be made when individual files are stored directly on the server instead of inside an archive file.
Here are the key topics you learned:
Packaging an applet inside a Java archive
Creating an HTML host file for your applet
Running the applet from a website
The following questions will help you to determine how well you have learned the subjects discussed in this chapter. The answers are provided in Appendix A, “Chapter Quiz Answers.”
This concludes the final chapter of the book! I hope you have enjoyed this book and learned a lot from it. I’ll admit that it was quite a challenge! For a while I didn’t think this Galactic War game would ever see the light of day. There are so many advanced topics that we didn’t have time to cover in this book, the likes of which a diehard Java programmer would have liked to see. However, I believe a completely functional game, created from scratch and actually finished within the pages of a book, is far more educational than any “advanced” material we might have spent more time studying instead. The game engine developed in the previous chapter, which was based on all the material in this book, is a viable game engine that can be used for many different types of games. My hope is that you have learned enough from this book to build your own blockbuster Java game for the online casual game market. Good luck!