By Daniel
H. Steinberg
October 2003
In the past two articles you have seen how to customize your Java application so that it looks and feels more like a native Macintosh application when running on Mac OS X without changing the end user experience on other platforms. A combination of runtime properties and coding changes that targeted Mac OS X specific APIs made a big difference to that audience.
Recall that Mac OS X is a melding of two worlds. Hard core UNIX programmers can pop open a Terminal window and write their Java code using vi and compile and run it from the command line. There is, however, the more traditional Mac audience that interacts with their computer through a friendly UI that follows Apple Human Interface guidelines.
In this
article, we look at deploying your Java application. The technical geek
audience might be happy with running a class with a main()
method from the command line but the wider
audience expects a double-clickable icon that looks and acts like every other
native application. In this article, we travel from one end of the spectrum to
the other to broaden your potential user base.
Although you should
"test everywhere", your build machine may not be a Mac. Fortunately, as you
will see, a double-clickable Macintosh application is just a directory with
some special contents and a name that ends with .app
. Even on a Windows machine you should be able to
modify your build script to package up a Mac-specific version of your
application.
Because Mac OS X ships with J2SE 1.4.1 and J2SE 1.3.1, you can distribute your application as class files or jar files and - in theory - your customer could run your application from the Terminal application. We start with these models and quickly move to double-clickable jar files and shell scripts.
For this article, use the
Java Sound
Demo as the running example. Download and unzip the zip file. Inside the
JavaSoundDemo
directory you will find
the source files inside of the src
subdirectory, a jar file, audio files, and html files that we will not
use.
As a developer, you don't think twice about
compiling the source files and running the application using the command line.
Compiling the eight files in the src
directory generates fifty class files. You can then run the sample application
from the command line like this.
java JavaSound
The Java Sound Demo starts up. We haven't customized the application in any way so the menu appears at the top of the JFrame and not where Macintosh users expect. The application looks like this out of the box.
You have done this compile and run step so many times that you hardly think twice about it. Think of the least technical person you know and ask whether they would be likely to follow these steps to run your application if a competing application were easier to install and run.
This example demonstrates two separate areas of usability. Once we got the application up and running it looked good and ran fine. You would not, however, want to distribute an application to an end user this way. You would have to somehow bundle up the fifty class files for easy download and installation. You would then have to provide instructions for running the application using, in the case of Mac OS X, the Terminal application.
If you
are going to have to package up the class files for distribution anyways, you
may as well produce a jar file. And, if you are going to produce a jar file,
it ought to be executable. In the case of the Java Sound Demo, the file
JavaSoundDemo.jar
is executable. Because Mac
OS X ships with the Jar Launcher application, the end user needs only double
click on the jar file and the application will launch.
To make the jar
file executable, the manifest must include the name of the Main class file.
Unjar JavaSoundDemo.jar
with the
command jar xvj JavaSoundDemo.jar
.
Here's the file META-INF/MANIFEST.MF
.
Manifest-Version: 1.0 Main-Class: JavaSound Created-By: 1.3.0 (Sun
Microsystems Inc.)
For larger or more complicated applications you are likely to have more than one jar file along with resource files. A common strategy for targeting multiple platforms is to include a batch file and a shell script. Choose the non-platform specific download from the NetBeans homepage. Inside of the bin subdirectory you will find applications for running NetBeans on a variety of platforms.
The shell script runide.sh
can be
run from the command line like this.
sh runide.sh -jdkhome /Library/Java/Home
The NetBeans IDE starts up with this decidedly non-Mac OS X look and feel.
You could, of
course, modify the shell script to modify this look and feel, but the NetBeans
developers decided on a different approach. Even though the typical NetBeans
audience member is technically competent, there should be a friendlier way to
start the IDE. They have created a native Mac OS X application called
NetBeansLauncher
.
The version of
NetBeansLauncher
that is included in the
generic NetBeans download is a good next step. You will see how the team took
it farther in the next section. On a Mac OS X computer you can double click on
the macosx_launcher.dmg
file inside
of the bin
directory. This is a disk
image. Drag the NetBeansLauncher
from
the expanded disk image back into the bin
directory. Now double click on the
NetBeansLauncher
. The ReadMe file that was also in
the disk image provides the following information about usage.
When launched for the first time, NetBeansLauncher needs to find NetBeans root directory. First it looks into NetBeansLauncher.app itself. If it does not find NetBeans root directory there user must specify NetBeans root directory manually.
For this download, the first time the user
starts up the NetBeansLauncher
, they
need to navigate to the netbeans
directory. After that, double clicking on the NetBeansLauncher
starts up the NetBeans IDE as if it were
any other native Mac OS X application.
If you download the Mac OS X disk image from the NetBeans
distribution and mount it you may be surprised at the simplicity of what you
find. Unlike the complex structure visible in the other distributions, you
will see five files with documentation and a single application. To install,
you can move this NetBeansLauncher
application anywhere on your hard drive. Double click on it and the NetBeans
IDE starts right up.
This is the experience that is expected on Mac OS X. The package structure and complexity is hidden from the user and they can't accidentally move a file that renders the IDE unusable. In this section we'll look more closely at the package structure and how to create a Mac OS X application whether or not our build machine is a Mac.
Consider again the sentence from the NetBeansLauncher
instructions that says in order to
locate the NetBeans root directory, "First it looks into NetBeansLauncher.app
itself." This implies that NetBeansLauncher
is a directory with the name
"NetBeansLauncher.app". In the mounted disk image, either right click or
Ctrl-click on the NetBeansLauncher icon and choose to "Show Package
Contents".
The structure
is the same for all Mac OS X applications. There is a Contents
directory with an XML file named
info.plist
, a text file named PkgInfo, a MacOS
directory, and a Resources directory. If you don't have a creator code
registered with Apple the PkgInfo text file should contain only the
following.
AAPL????
If you have a creator code, use it inplace of the question marks. Ordinarily the MacOS folder contains a small stub
file that launches the Java VM. In this case the NetBeans team has written
their own application. We will look more closely at a property list file in
the next section. For now, take a look at the contents of the
Resources
directory.
You can see the contents of the same netbeans
package inside of the Resources
subdirectory. This is your key to deploying on
Mac OS X. Add in the necessary pieces and then just bundle up your ordinary
distribution in the appropriate location. If you have a more flexible build
process you should also strip out those pieces that aren't needed for the Mac
OS X application such as the Windows executables.
If you are interested in digging deeper into the structure of a Mac OS X application, you will find more information in the Apple publication Anatomy of a Bundle.
If you develop on Mac OS X you can use the Jar Bundler
application to turn jar files into Mac OS X
applications. Jar Bundler
is
distributed with the other developer tools and is located in
Developer/Applications/
. Start it, select the
"Classpath and Files" tab and add the file JavaSoundDemo.jar
.
Select the "Build Information"
tab. For "Main Class", navigate to the JavaSoundDemo.jar
file again and select
JavaSound
from the drop down list. This list is
populated by any classes in the jar file containing a main()
method. Accept all of the default settings for the
options. You can use the default Java application icon or you can create your
own. The icon you see below started as a screen shot of the running Java Sound
Demo and was transformed into an icon using the IconComposer
application that is also distributed as part
of the developer tools.
Press "Create Application" and enter the name "JavaSoundDemo". A Mac OS X application is created for you. You can show the package contents of the generated application as before. You can view the property list with Apple's Property List Editor or with any text editor. It is just an XML file with properties stored as name - value pairs.
The Java properties indicate the location of the jar file, the name of the Main class, and the version of the JRE to be used. The other properties include a pointer to the icon file and to the Java application stub file that is the native executable.
Take a look at the contents of the package that was
generated by Jar Bundler
on Mac OS
X.
On another platform you need to duplicate this structure. To create an
application named "JavaSoundDemo" on, say, a Windows machine, start by
creating a directory and naming it JavaSoundDemo.app
. Next, create a subdirectory named
Contents
. Inside of Contents
you will need a MacOS
directory with the JavaAPplicationStub
. You can create the
PkgInfo
text file and your Info.plist
can also be generated by hand and should
contain the following XML.
You will need a Resources
directory with a Java
subdirectory
into which you put the JavaSoundDemo.jar
file. In other words, with the
exception of the JavaApplicationStub
and the music.icns
file, everything
else can be created on another platform.
If you use Ant you can easily add a target that takes your jar files, images, and other resources and bundles it up as a Mac OS X application bundle that includes the plist file and Java application stub in the appropriate locations. Every time you create a new build you will automatically have your Mac OS X version. You can also find a growing number of Ant tasks that automate some of the steps outlined in this article.
When it comes time to deploy your Java application, consider the ease of use of your target audience. Even developers appreciate the double clickable version of the NetBeans IDE. Creating a Java application that looks and feels like a native application does not require a lot of extra work and can easily be integrated into your build process even if your build machine runs a different operating system.