< Previous PageNext Page >

Hide TOC

Java Deployment Options for Mac OS X

When deploying Java applications in Mac OS X, you have access to the Java Plug-in and Java Web Start as you do on other platforms. There are also two additional deployment technologies in Mac OS X. You may deploy applications as double-clickable JAR files or as native Mac OS X application bundles. This chapter discusses these four deployment technologies. Note that there are three different Java implementations currently available on Mac OS X, Java 1.4.2 and J2SE 5.0. Make sure that you are using the correct Java implementation for your application. Information on what you need to do to specify the correct Java implementation is included in the following sections.

Double-Clickable JAR Files

The simplest way to deploy an application is to distribute it as a JAR file. The biggest advantage of this technique is that it requires very little, if any, changes from the JAR files you distribute on other platforms. This technique, however, has drawbacks for your users. Applications distributed as JAR files are given a default Java applications icon, instead of one specific to that application, and do not allow you to easily specify runtime options without doing so either programatically or from a shell script. If your application has a graphical interface and will be run by general users, you should consider wrapping the JAR file as a Mac OS X application bundle. You can find more information on how to do this in “Mac OS X Application Bundles.”

Double-clickable JAR files launch with J2SE 5.0. If a JAR file needs to be launched in Java 1.4.2, wrap the JAR file as a Mac OS X application bundle using Jar Bundler.

Note: You can double-click on a Java class file to launch your application, but this is not a recommended method for application deployment.

If you choose to deploy your application from a JAR file in Mac OS X, the manifest file must specify which class contains the main method.Without this, the JAR file is not double-clickable and users see an error message like the one shown in Figure 1.

Figure 1 Jar Launcher error

If you have a JAR file that does not already have the main class specified in the manifest, you can remedy this as follows:

Unarchive your JAR file into a working directory with some variant of jar xvf myjar.jar
In the resultant META-INF directory is a MANIFEST.MF file. Copy that file and add a line that begins with Main-Class: followed by the name of your main class. For example, a default manifest file in Mac OS X looks like this:
Manifest-Version: 1.0
Created-By: 1.4.2_07 (Apple Computer, Inc.)
With the addition of the main class designation it looks like:
Manifest-Version: 1.0
Created-By: 1.4.2_07 (Apple Computer, Inc.)
Main-Class: YourAppsMainClass
Archive your files again but this time use the -m option to jar and designate the relative path to the manifest file you just modified, for example, jar cmf YourModifiedManifestFile.txtYourJARFile.jar*.class

This is a very basic example that does not take into account more advanced uses of the jar program. More detailed information on adding a manifest to a JAR file can be found in the jar(1) man page.

Mac OS X Application Bundles

Native Mac OS X applications are more than just executable files. Although a user sees a single icon in the Finder, an application is actually an entire directory that includes images, sounds, icons, documentation, localizable strings, and other resources that the application may use in addition to the executable file itself. The application bundle simplifies application development in many ways for developers. The Finder, which displays an application bundle as a single item, retains simplicity for users, including the ability to just drag and drop one item to install an application.

This section discusses Mac OS X application bundles as they relate to deploying Java applications. More general information on Mac OS X application bundles is available in Bundle Programming Guide.

When deploying Java applications in Mac OS X, consider making your Java application into a Mac OS X application bundle. It is easy to do and offers many benefits:

Users can simply double-click the application to launch it.
If you add an appropriate icon, it shows the application icon in the Dock and in the menu bar, clearly identifying your application. (Otherwise, a default Java icon appears in the Dock.)
It lets you easily set Mac OS X–specific system properties that can make your Java application hard to distinguish from a native application.
You can bind specific document types to your application. This lets users launch your application by double-clicking a document associated with it.

The Contents of an Application Bundle

The application bundle directory structure is hidden from view in the Finder by the .app suffix and a specific attribute, the bundle bit, that is set for that directory. (See Runtime Configuration Guidelines for more information on Finder attributes.) The combination of these two things makes the directory a bundle. To get a glimpse inside an application bundle, you can explore the directory of resources from Terminal or from the Finder. Although by default the Finder displays applications as a single object, you can see inside by Control-clicking (or right-clicking if you have a multiple-button mouse) an application icon and choosing Show Package Contents as shown in Figure 2.

Figure 2 Show application bundle contents

You should see something similar to the directory structure shown in Figure 3.

Figure 3 Contents of a Java application bundle

Applications bundles for Java applications should have the following components:

An Info.plist file in the Contents folder. In the case of a Java application, this contains some important information that Mac OS X uses to set up the Java runtime environment for your application. More information about these property lists is in Java Dictionary Info.plist Keys.
A file named PkgInfo should also be in the Contents folder. This is a simple text file that contains the string APPL optionally followed directly by a four letter creator code. If an application does not have a registered creator code, the string APPL???? should be used. You may register your application with Apple’s creator code database on the ADC Creator Code Registration site at http://developer.apple.com/datatype/.
The application’s icon that is displayed in the Dock and the Finder should be in the Resources folder. There is a Mac OS X–specific file type designated by the .icns suffix, but most common image types work. To make an icon (.icns) file from your images, use the Icon Composer application installed in /Developer/Applications/Utilities/.
The Java code itself, in either jar or .class files, in Resources/Java/.
A native executable file in the MacOS folder that launches the Java VM.
Optional localized versions of strings may be included in folders designated by the .lproj suffix. The example in Figure 3 includes localizable strings for four different languages. See “Additional Considerations for Non-English Applications” for more information on localized application bundles.

There are other files in the application bundle, but these are the ones that you should have in a Java application bundle. You can learn more about the other files in an application bundle, as well as more information about some of these items, in Framework Programming Guide.

A Java Application’s Info.plist File

Mac OS X makes use of XML files for various system settings. The most common type of XML document used is the property list. Property lists have a .plist extension. The Info.plist file in the Contents folder of a Mac OS X application is a property list.

The Info.plist file lets you fine-tune how well your application is presented in Mac OS X. With slight tweaking of some of the information in this file, you can make your application virtually indistinguishable from a native application in Mac OS X, which is important for making an application that users appreciate and demand.

If you build your Java application in Xcode or Jar Bundler, the Info.plist file is automatically generated for you. If you are building application bundles through a shell or Ant script, you need to generate this file yourself. Even if it is built for you, you may want to modify it. Since it is a simple XML file, you can modify it with any text editor.

Listing 1 shows an Info.plist for a Java application that has been wrapped as an application bundle.

Listing 1 Example Info.plist

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>CFBundleDevelopmentRegion</key>

    <string>English</string>

    <key>CFBundleExecutable</key>

    <string>Java 1.4.2 Plugin Settings</string>

    <key>CFBundleGetInfoString</key>

    <string>2.1.1 (for Java 1.4.2), Copyright 2004 Apple Computer, Inc. All Rights Reserved.</string>

    <key>CFBundleIconFile</key>

    <string>Java Plugin Settings.icns</string>

    <key>CFBundleIdentifier</key>

    <string>com.apple.java.PluginSettings.142</string>

    <key>CFBundleInfoDictionaryVersion</key>

    <string>6.0</string>

    <key>CFBundleName</key>

    <string>Java 1.4.2 Plugin Settings</string>

    <key>CFBundlePackageType</key>

    <string>APPL</string>

    <key>CFBundleShortVersionString</key>

    <string>2.1.1</string>

    <key>CFBundleSignature</key>

    <string>????</string>

    <key>CFBundleVersion</key>

    <string>2.1.1</string>

    <key>Java</key>

    <dict>

        <key>JVMVersion</key>

        <string>1.4*</string>

        <key>MainClass</key>

        <string>sun.plugin.panel.ControlPanel</string>

        <key>VMOptions</key>

        <string>-Xbootclasspath/p:/System/Library/Frameworks/

JavaVM.framework/Versions/1.4.2/Home/lib/jaws.jar:/System/Library/

Frameworks/JavaVM.framework/Versions/1.4.2/Home/lib/netscape.jar</string>

    </dict>

    <key>LSHasLocalizedDisplayName</key>

    <true/>

    <key>NSHumanReadableCopyright</key>

    <string>Copyright 2003 Apple Computer, Inc., All Rights Reserved.</string>

    <key>NSJavaPath</key>

    <array/>

</dict>

</plist>

A property list file is divided into hierarchical sections called dictionaries. These are designated with the dict key. The top-level dictionary contains the information that the operating system needs to properly launch the application. The keys in this section are prefixed by CFBundle and are usually self explanatory. Where they are not, see the documentation in Runtime Configuration Guidelines.

At the end of the CFBundle keys, this example includes a Java key designating the beginning of a Java dictionary. At least two keys should be in this dictionary; the MainClass is required and the JVMVersion key is highly recommended. A listing of all the available keys and Java version values for the Java dictionary is provided in Java Dictionary Info.plist Keys.

If you examine an older Java application distributed as an application bundle, some of the keys may be missing from the Properties dictionary. Java application bundles used to include the Java-specific information distributed between an Info.plist file and another file, MRJApp.properties in Contents/Resources/ in the application bundle. If you are updating an existing application bundle, you should move the information from the MRJApp.properties file into the appropriate key in the Java dictionary in the Info.plist file.

Making a Java Application Bundle

There are three ways to make a Java application bundle:

With Xcode
With Jar Bundler
From the command line

If you build a new Java AWT or Swing application, use one of Xcode’s templates and Xcode automatically generates an application bundle complete with a default Info.plist file. You can fine-tune the behavior of this application by modifying the Info.plist file directly in the Products group of the Files pane or by modifying the settings in the Info.plist Entries section of the Targets pane. For more information on using Xcode for Java development, see Xcode Help (available from the Help menu in Xcode) and Xcode User Guide.

If you want to turn your existing Java application into a Mac OS X Java application, use the Jar Bundler application available in /Developer/Tools/. It allows you to take existing .class or jar files and wrap them as application bundles. Information about Jar Bundler, including a tutorial, is provided in Jar Bundler User Guide.

To build a valid application bundle from the command-line, for example in a shell script or an Ant file, you need to follow these steps:

Set up the correct directory hierarchy. The top level directory should be named with the name of your application with the suffix .app.
There should be a Contents directory at the root of the application bundle. It should contain a MacOS directory and a Resources directory. A Java directory should be inside of the Resources directory.
The directory layout should look like this.
YourApplicationName.app/
Contents/
MacOS/
Resources/
Java/
Copy the JavaApplicationStub file from /System/Library/Frameworks/JavaVM.framework/Versions/Current/Resources/MacOS/ into the MacOS directory of your application bundle.
Make an Info.plist file in the Contents directory of your application bundle. You can start with an example like that given in Listing 1 and modify it or generate a completely new one from scratch. Note that the application bundle does not launch unless you have set the correct attributes in this property list, especially the MainClass key.
Make a PkgInfo file in the Contents directory. It should be a plain text file. If you have not registered a creator code with ADC, the contents should be APPL????. If you have registered a creator code replace the ???? with your creator code.
Put your application’s icon file into the Contents/Resources/ directory. (For testing purposes, you can copy the generic Java application icon from /Developer/Applications/Jar Bundler.app/Contents/Resources/.)
Copy your Java .jar or .class files into /Contents/Resources/Java/.
Set the bundle bit Finder attribute with SetFile, found in /Developer/Tools/. For example, /Developer/Tools/SetFile -a B YourApplicationName.app.

After these steps, you should have a double-clickable application bundle wrapped around your Java application.

Additional Considerations for Non-English Applications

To run correctly in locales other than US English, Java application bundles must have a localized folder for each appropriate language inside the application bundle. Even if the Java application handles its localization through Java ResourceBundles, the folder itself must be there for the operating system to set the locale correctly when the application launches. Otherwise Mac OS X launches your application with the US English locale.

Put a folder named with the locale name and the .lproj suffix in the application’s Resources folder for any locale that you wish to use. For example if you include a Japanese and French version of your application, include a Japanese.lproj folder and a French.lproj folder in YourApplicationName.app/Contents/Resources/. The folder itself can be empty, but it must be present.

Bundle Programming Guide provides more detail about the application bundle format.

Distributing Application Bundles

The recommended way to distribute application bundles is as a compressed disk image. This gives users the ease of a drag-and-drop installation. Put your application bundle along with any relevant documentation on a disk image with Disk Utility, compress it, and distribute it. Disk Utility is available in /Applications/Utilities/. You can further simplify the installation process for your application by making the disk image Internet enabled. For information on how to do this see Distributing Software with Internet Enabled Disk Images.

Java Web Start

As a part of Java 1.4.2 and J2SE 5.0, Mac OS X also supports deploying your application as a Java Web Start application. Java Web Start is an implementation of the Java Network Launching Protocol & API (JNLP) specification, which means that if you make your application JNLP-aware, Mac OS X users do not need to do anything to use it. They have access to your applications through the Web browser and the Java Web Start application (installed in /Applications/Utilities/Java/).

By default, if a user launches a Java Web Start application more than twice from the same URL, they are prompted to save the application as a standard Mac OS X application, as shown in Figure 4. They are also prompted on where they want to save your application. The application is still a Java Web Start application, with all the benefits that offers, but it is now easier for users to run your application since they do not have to launch a Web browser or the Java Web Start application.

Figure 4 Java Web Start integration

The desktop integration setting can be changed in the Preferences of the Java Web Start application in /Applications/Utilities/Java/.

You need to be aware of only a few details about how the Mac OS X implementation of Java Web Start differs from the Windows and Solaris versions:

It does not support downloading of additional Java Runtime Environments (JREs). Mac OS X v.10.4 includes Java 1.4.2 and offers J2SE 5.0 as a Software Update. If your application requires J2SE 5.0, you need direct your customers to Apple to obtain it. The version keys that are valid for Java Web Start applications are the same as those for Mac OS X application bundles and are listed in Java Dictionary Info.plist Keys.
It is not necessary to set up proxy information explicitly in the Web Start application. Java Web Start in Mac OS X automatically picks up the proxy settings from the Network pane in System Preferences.
Java Web Start caches its data in the user’s /Library/Caches/Java Web Start/ directory.

The Java Plug-in

Java 1.4.2 and J2SE 5.0 for Mac OS X include the Java Plug-in for you to deploy applets in browsers and other Java embedding applications. The only browsers that currently support the Java 1.4.2 and J2SE 5.0 Java Plug-in use the Web Kit API. Other browsers on Mac OS X currently use either a Java 1.3.1 Java Plug-in or the legacy Java Embedding framework. The Java Embedding framework supports Java 1.3.1 by implementing the appletviewer class and therefore does not provide the added benefits that the Java Plug-in provides like JAR caching, handling of signed JAR files, and the Java console.

When testing your applications, you can determine which version of the Java Plug-in the application is using with the GetOpenProperties applet available from Sun at http://java.sun.com/docs/books/tutorial/deployment/applet/. These are the Java implementations used by current browsers:

Safari 2.0

Java 1.4.2 and J2SE 5.0 Plug-in

Internet Explorer 5.2

Java 1.3.1 Embedding framework

Netscape 7.2/ Mozilla 1.7

Java 1.3.1 Plug-in

The Applet Launcher application in /Applications/Utilities/Java/ also uses the J2SE 5.0 Plug-in, but it is not a full-featured browser – it is more of a development tool. For more information on Applet Launcher see “ Applet Launcher.”

“ Using Xcode with J2SE 5.0” includes information on using Applet Launcher with J2SE 5.0.

For all of the common browsers, the <APPLET> tag has proven to be less problematic than the <OBJECT> and <EMBED> tags.