Application Bundles

What users see as an application in Mac OS X is actually a bundle of resources to a developer. To get a glimpse inside an application on Mac OS X, you can either explore the directory of resources from the Terminal or from the Finder. Although by default the Finder displays applications as a single object, you can view the true makeup of any application in the Finder. To see what is contained inside a standard application bundle, Control-click any application and choose Show Package Contents as in Figure 3-1.

You should see something like Figure 3-2.

Notice some important details:

• Mac OS X expects to see 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 Property List Attributes for Java Applications

• If you have an icon that should be displayed in the Mac OS X Finder, put it 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 with the Mac OS X Developer Tools.

• Your Java code, in either JAR or .class files is put into Resources/Java. This is launched by a native executable file in the MacOS folder.

There are other files in the application bundle, but the specific ones mentioned are the ones you probably care most about as a Java developer. You can learn more about the other files an application bundle in Inside Mac OS X: System Overview.

Property List Attributes for Java Applications

Mac OS X makes extensive use of XML files for various system settings. These are called property lists and have a .plist extension. The Info.plist file in the Contents folder of a Mac OS X application is one such property list. If you build your Java application in Project Builder or MRJAppBuilder, this file is automatically generated for you. Even if it is built for you, there may be times when you may want to modify it. Since it is a simple XML file, you can modify it with any text editor. Its settings will be read the next time you launch your application from the Finder. An example property list for a Java application is shown in Listing 3-1.

Listing 3-1  Info.plist file for simple Java application

<?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>SampleApp</string>

    <key>CFBundleIconFile</key>

    <string>SampleApp.icns</string>

    <key>CFBundleInfoDictionaryVersion</key>

    <string>6.0</string>

    <key>CFBundlePackageType</key>

    <string>APPL</string>

    <key>CFBundleSignature</key>

    <string>????</string>

    <key>CFBundleVersion</key>

    <string>0.1</string>

    <key>Java</key>

    <dict>

        <key>ClassPath</key>

        <string>$JAVAROOT/SampleApp.jar</string>

        <key>MainClass</key>

        <string>SampleApp</string>

        <key>Properties</key>

        <dict>

            <key>com.apple.macos.useScreenMenuBar</key>

            <string>true</string>

            <key>com.apple.mrj.application.apple.menu.about.name</key>

            <string>SampleApp</string>

        </dict>

    </dict>

</dict>

</plist>

The property list is divided into hierarchical dictionaries. 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 Mac OS X Developer Release Notes: Information Property List and Inside Mac OS X: System Overview.

At the end of the CFBundle keys, a Java key designates the beginning of a Java dictionary. The two top-level keys in the Java dictionary are required in the property list of a Java application bundle. They are defined as follows:

• MainClass, corresponds to the com.apple.mrj.application.main system property. The string value for this key should specify the fully qualified class name for the class containing you application’s main method.

• ClassPath, corresponds to the com.apple.mrj.application.classpath system property. The string value for this key should specify the fully qualified path to the directories where your class files are or to your JAR files.

Aside from those two required keys, there are some optional keys that you can add here. They are described in Mac OS X Application Properties.

The Properties sub dictionary of the Java dictionary contains keys that you pass to your Java applications from the command line with the -D option. For example, if you want to run this same application from the command line, you pass in the two keys, com.apple.macos.usescreenmenubar and com.apple.mrj.application.apple.menu.about.name as follows:

java -Dcom.apple.macos.useScreenMenuBar=true -Dcom.apple.mrj.application.apple.menu.about.name=SampleApp SampleApp

The keys in the Properties dictionary include both Mac OS X–specific options as well as general Java options. Mac OS X–specific keys and values that you may add to this dictionary of the property list are specified in Mac OS X Application Properties.

If you examine an application built with MRJAppBuilder, you might notice that some of the keys seem to be missing from the Properties dictionary. MRJAppBuilder uses a legacy style non-XML property list named MRJApp.properties in the Contents/Resources folder of an application bundle. This property list contains the same flags and system properties that you would normally find in Properties sub-dictionary (of the Java dictionary) in an Info.plist. In general, this list behaves like the Info.plist with a few exceptions:

• Arguments to main() may not contain embedded spaces. You can work around this by passing in such arguments to the Info.plist, though.

• The APP_PACKAGE property is not expanded when used in com.apple.mrj.application parameters.

• Additional command-line arguments designated in MRJApp.properties are ignored if the application is launched from the command line.

Setting the Java Runtime Properties for an Application Bundle

Having seen the structure of the Mac OS X information property list should help you to debug your application and modify existing applications, but how do you generate that list in the first place? You could build application bundles by hand in the Terminal, write the Info.plist file yourself in a text editor, and designate the file as an application with the SetFile command-line tool. There are two much simpler solutions: Project Builder and MRJAppBuilder.

If you build a Java AWT or Swing application from one of Project Builder’s templates, Project Builder automatically generates a default Info.plist file. You may either modify this by hand or directly from Project Builder as outlined in Modifying the Application Parameters. If you want to turn your preexisting Java application into a Mac OS X Java Application, MRJAppBuilder is the tool for you. It allows you to take existing .class or JAR files and wrap the information around them that Mac OS X expects to find when launching a native application, including setting up the runtime properties of your Java application. A simple tutorial for MRJAppBuilder is available in MRJAppBuilder Tutorial. Project Builder Tutorial provides a tutorial on using Project Builder to build a Mac OS X native application.

Accessing Mac OS X–Specific Properties From Applets

Mac OS X includes some specific system properties that you might want to take advantage of in your applets. Except for the com.apple.macos.useScreenMenuBar, unsigned applets cannot access these properties. If you want to use any of the properties discussed in Mac OS X Java System Properties, you can grant permission to access them by adding a line to your system-wide java.policy file located at /Library/Java/Home/lib/security/.

The line should be of the form:

java.util.PropertyPermission systemPropertyName, read;

Java Applet Plug-in

In previous versions of Mac OS X, applications that displayed applets, such as Web browsers, used the Mac OS X Java Embedding framework to embed the Java applets in the native application. This framework uses Sun’s reference appletviewer class not Sun’s Java Plug-in architecture. When this framework is used to display an applet, users miss out on the additional features of Sun’s Java Plug-in. Additionally applet behavior is dependent on how the browser maker uses the Java Embedding framework.

In Mac OS X version 10.2, browser developers may easily display applets with the Java Applet Plug-in architecture (Java Applet.plugin) without writing browser–specific code to use the Java Embedding framework. Mac OS X’s Java Applet Plug-in takes full advantage of Sun’s Java Plug-in. What this means to you is that if you want to deploy your Java applets on Mac OS X is that you should modify your HTML code so that your applets are be run through the new Java Applet Plug-in architecture and not the Java Embedding framework.

Taking Advantage of the Java Applet Plug-in with HTML

Although Sun encourages the use of the <APPLET> tag for all applets, this does not always give you the recommended behavior. For example, in some browsers, <APPLET> does not give you the full functionality of Sun’s Java Plug-in, while the <OBJECT> tag, which is mapped to the mime type application/x-java-applet, does. This is illustrated in Figure 3-4.

Figure 3-4 shows the effect of the <APPLET> tag in comparison to the <EMBED> tag. You can see that the suggested <APPLET> tag has the desired results only in Mozilla/Netscape. To work around the different interpretations of the <APPLET> tag, you have a few options. You can just use the tag listed in Listing 3-1 that invokes the Java Plug-in or you can use Sun’s HTML converter to get HTML that works in any browser. The converter is available at http://java.sun.com/products/plugin/1.3/docs/htmlconv.html. Without changing anything, you should see the same applet behavior that you saw in previous versions of Mac OS X.

Table 3-1  Interpretation of HTML tags in common Mac OS X browsers

Browser	<APPLET>	<OBJECT>	<EMBED>
Internet Explorer 5.2.x (default browser in Mac OS X 10.2)	Java Embedding framework
Netscape/Mozilla	Treated as an <EMBED> tag, which by default maps to the application/x-java-applet mime type.		Java Plug-in
OmniWeb			Java Plug-in
Opera		Java Plug-in
Chimera	Treated as an <EMBED> tag.		Java Plug-in