Mac OS X 10.6 Snow Leopard
Installation and Setup Guide
Read this document before you install Mac OS X. It includes important information about installing Mac OS X. For more information about Mac OS X, visit this website: www.apple.com/macosx For the latest information about using Mac OS X, connect to the Internet and open Mac Help. To open Mac Help, in the Finder choose Help > Mac Help. For additional support and technical information on all Apple products, visit this website: www.apple.com/support To find out what version of Mac OS X you have installed on your computer, choose Apple () menu > About This Mac.

System requirements

An Intel processor
To upgrade to Snow Leopard or install Snow Leopard for the first time, you must have a Mac with:
An internal or external DVD drive, or DVD or CD Sharing At least 1 GB of RAM (additional RAM is recommended) A built-in display or a display connected to an Apple-supplied video card supported

by your computer

At least 5 GB of disk space available, or 7 GB of disk space if you install the developer

Upgrading Mac OS X

Follow these easy steps to upgrade to Mac OS X Snow Leopard. 1 Insert the Mac OS X installation disc. 2 Double-click the Install Mac OS X icon. The Welcome pane appears, followed by the License Agreement. Read and agree to the software license agreement. 3 In the pane where you select a disk, select your current Mac OS X disk (in most cases, it will be the only one available). 4 Click Customize to select or deselect optional software. You can customize some of the software that will be installed, such as printer drivers, fonts, and language translations. In the Custom Install pane, select the software you want to install, and then click OK. Note:If you see a message that you dont have enough disk space to install MacOSX, you can deselect items to save space. 5 Click Install. To quit any open applications and start the installation, click Install in the message that appears. When prompted, enter your administrator password.
Upgrading using another computers optical drive
You can use DVD or CD Sharing to upgrade Mac OS X (or to reinstall your iLife applications) on a Mac without an optical drive using another computers optical drive. The other computer must have Mac OS X 10.4.10 or later, or Microsoft Windows XP or Windows Vista. Note:You dont need to use Remote Install Mac OS X to upgrade Mac OS X on a Mac without an optical drive. However, if you need to restore your Mac to factory settings, then you need to use Remote Install Mac OS X. 1 Make sure both computers are on the same network (wired or wireless). 2 Make sure you have installed DVD or CD Sharing on the computer whose optical drive youre using. If the computer is a Mac with Mac OS X 10.5.3 or later, DVD or CD Sharing is installed.
To install DVD or CD Sharing on a Mac with Mac OS X 10.4.10-10.5.2, see:
http://support.apple.com/downloads/DVD_or_CD_Sharing_Setup_Update_for_Mac
On a Windows computer, see: http://support.apple.com/downloads/DVD_or_CD_
Sharing_Update_1_0_for_Windows
3 Make sure you have turned on DVD or CD Sharing on the computer whose optical drive youre using.
To turn on DVD or CD Sharing on a Mac, select the DVD or CD Sharing checkbox in

Sharing preferences.

On a Windows computer, select Enable Remote DVD or CD in the DVD or CD
Sharing control panel. 4 Insert the installation disc into the computers optical drive. 5 On the computer where youre installing Mac OS X (or iLife applications), select the Remote Disc under Devices in a Finder window sidebar. If you see the Ask to use button, click it. On the computer with the installation disc, click Accept. 6 Select the disc, open the Installer, and then follow the onscreen instructions.
Using Time Machine to back up and restore your system

After youve installed Snow Leopard, connect Time Capsule or an external USB or FireWire drive to your computer and use Time Machine to make an up-to-date copy of everything on your computer. If you need to install Snow Leopard again and youve created a Time Machine backup, use the Restore utility to restore everything on your computer to its previous condition. 1 Insert the Mac OS X installation disc, and then double-click the Install Mac OS X icon. 2 In the Installer, click Utilities, and then click Restart. 3 When the Language Chooser appears, select your language, and then click the Continue button (looks like an arrow). 4 Choose Utilities > Restore System From Backup, and then click Continue in the screen that appears. 5 Select a backup source. Select the disk that contains the Time Machine backup you want to restore, and then follow the onscreen instructions. Note:Restoring your system erases all the contents of the volume you select.
Restoring your computer to factory settings
If you need to restore your computer to the original factory settings, you can use Disk Utility in the Mac OS X Installer. Important:If you restore your computer to factory settings, everything on your computer (your user accounts, network settings, and all of your files and folders) will be deleted. Before you restore, back up any files you want to keep by copying them to another disk. Write down your network settings from Network preferences to make it easier to get connected again after reinstalling Mac OS X. 1 Insert the Mac OS X installation disc, and then double-click the Install Mac OS X icon. Note:You can use Remote Install Mac OS X to restore your computer to factory settings on a Mac without an optical drive, using another computers optical drive. To use Remote Install Mac OS X, first follow the instructions in Using Remote Install Mac OS X later in this document, and then go to step 3 in this section. 2 In the Installer, click Utilities, and then click Restart. 3 When the Language Chooser appears, select your language, and then click the Continue button (looks like an arrow). 4 Choose Utilities > Disk Utility. 5 Select your disk from the list on the left, and then click the Erase tab. 6 Select Mac OS Extended (Journaled) from the Format pop-up menu, type a name for your disk, and then click Erase. After the disk has been erased, choose Disk Utility > Quit Disk Utility, and then follow the instructions in the Mac OS X Installer to reinstall Mac OS X. Note:Once the installation is complete, you may be prompted to use the Applications installation disc that came with your computer to reinstall your iLife applications (GarageBand, iPhoto, iMovie, iDVD, and iWeb). To reinstall your iLife applications, insert the Applications installation disc, double-click the Install Bundled Software icon, and then follow the onscreen instructions.
Using Remote Install Mac OS X

You can use Remote Install Mac OS X to restore your computer to factory settings on a Mac without an optical drive, using another computers optical drive. The other computer must have Mac OS X 10.4.10 or later, or Microsoft Windows XP or Windows Vista. 1 Make sure both computers are on the same network (wired or wireless). Note:You cant use Remote Install Mac OS X with a WEP-protected wireless network. 2 Make sure that you have installed DVD or CD Sharing on the computer whose optical drive youre using. If the computer is a Mac with Mac OS X 10.5.3 or later, DVD or CD Sharing is installed.
Sharing_Update_1_0_for_Windows 3 Insert the Mac OS X installation disc into the computers optical drive. 4 On the computer whose optical drive youre using, open Remote Install Mac OS X.
On a Mac, it is located in the Utilities folder in the Applications folder. On a Windows computer, choose Remote Install Mac OS X from the Install Assistant.
5 Follow the onscreen instructions. Read the introduction, select the installation disc you want to use, and depending on your type of network, select AirPort or Ethernet. Click Continue after each pane.
6 On the computer where youre installing the software, hold down the Option key while restarting the computer, until you see the list of available startup disks. 7 On the computer with the installation disc, click Continue in Remote Install Mac OS X. Note:If you selected AirPort as your network in step 5, choose your AirPort network from the pop-up menu. When you see the AirPort status icon indicating signal strength, click Continue in Remote Install Mac OS X.
8 On the computer where youre installing the software, select the installation disc, and then click the arrow below the disc icon. To erase and reinstall Mac OS X, go to step 3 in Restoring your computer to factory settings earlier in this document.
Reinstalling applications using another computers optical drive
If you used Remote Install Mac OS X to restore your computer to factory settings, you may need to use the Applications installation disc that came with your computer to reinstall your iLife applications (GarageBand, iPhoto, iMovie, iDVD, and iWeb). If youre prompted to use the Applications installation disc, follow the instructions in Upgrading using another computers optical drive earlier in this document.

Advice about installing

In the following sections, youll find answers to questions you may have about installing and using Mac OS X.
Using the keyboard during installation
You have full keyboard access while using the Mac OS X Installer and Mac OS X Setup Assistant. Press the Tab key to highlight buttons, pop-up menus, and other options. Press the Down Arrow key to open pop-up menus. Press the Space bar to select items.
The Installer cant repair your disk
If a message says the Installer cant repair the disk, you may need to erase it. Before you erase your disk, try copying your files to an external disk. When youre ready to erase and reinstall Mac OS X, follow the instructions in the Restoring your computer to factory settings section of this document.
The Installer doesnt open
If the Installer doesnt open, restart your computer while holding down the C key to start up your computer using the Mac OS X installation disc. If the Installer still doesnt open, restart your computer while holding down the mouse or trackpad button to eject the disc. After your computer starts up, insert the Mac OS X installation disc. Use Startup Disk preferences to select the disc as your startup disk, and then restart. If the Installer doesnt open when youre using DVD or CD Sharing, try using Remote Install Mac OS X. If your computer is connected to a network, your network administrator may prevent you from installing software or upgrading Mac OS X. Contact your network administrator for assistance.
The installation wasnt successful
If you were unable to install Mac OS X, try the following: 1 Disconnect any external devices you dont need during installation. 2 Remove any cards from manufacturers other than Apple. 3 Try installing Mac OS X again. 4 If you were unable to install Mac OS X again, choose Utilities > Disk Utility. Select the disk on which you want to install, click First Aid, and then click Repair Disk. After repairing any problems, quit Disk Utility and then click Continue to try installing again. If youre still unable to install Mac OS X, try erasing the disk before installing Mac OS X. Before you erase your disk, try copying your files to an external disk. When youre ready to erase and reinstall Mac OS X, follow the instructions in the Restoring your computer to factory settings section of this document.
Advice about accounts and passwords
In the following sections, youll find answers to questions you may have about user names, passwords, and logging in.
You cant log in to your computer
Make sure youre typing the name and password exactly the way they were created, including capitalization. If you still cant log in but you know the name and password of an administrator user (such as the first user you created), log in as the administrator and use Accounts preferences to change your password.

You dont remember your password and need to reset it
If you dont remember your password and you have the Mac OS X installation disc, insert the disc and restart your computer while holding down the C key. If your computer doesnt have an optical drive, use Remote Install Mac OS X. When the Mac OS X Installer appears, select your language, choose Utilities > Reset Password, and then follow the onscreen instructions.
You cant log in to your remote user account
If you're logging in to a server to access your user account and you cant log in, contact your system administrator.
Copyright 2009 Apple Inc. All rights reserved. Apple, the Apple logo, AirPort, FireWire, GarageBand, iDVD, iLife, iMovie, iPhoto, Mac, Mac OS, Time Capsule, and Time Machine are trademarks of Apple Inc., registered in the U.S. and other countries. Finder, iWeb, and Snow Leopard are trademarks of Apple Inc. Intel is a trademark of Intel Corp. in the U.S. and other countries. Other product and company names mentioned herein may be trademarks of their respective companies.

Figure B-1 Figure B-2 Figure B-3 Figure B-4 Figure B-5 Figure B-6 Figure B-7 MRJAppBuilder Application pane 70 A successful build 70 Merge Files pane 71 FileChooserDemo application with relics 72 Modifying the growbox.intrudes property 73
com.apple.mrj.application.growbox.intrudes=true 73
Application bundle contents 74
Table C-1 Table C-2 Table C-3 Table C-4 JVM properties 75 required Mac OS X application properties 76 Application launch properties 76 System properties related to the graphical user interface 77

CHAPTER 1

About This Book
Important: The information in this document is obsolete and should not be used for new development. Links to downloads and other resources may no longer be valid. With Mac OS X, Apple delivers a Java implementation that adds value for both developers and end users. Java is fully integrated into Mac OS X, which offers developers easy access to the Aqua user interface, UNIX-based tools and technologies, QuickTime, OpenGL, and Cocoa. This built-in flexibility allows developers to create robust, well-designed applications that offer users a wide range of rich features and functionality. This book provides an overview of Java development on Mac OS X and discusses the available features. It also provides simple examples on using the development tools available with Mac OS X. This book is for the Java developer interested in writing Java applications on Mac OS X version 10.2 with Java 2 Standard Edition (J2SE) version 1.3.1. It does not discuss Java 2 Standard Edition version 1.4 on Mac OS X. Information on previous versions of Java on Mac OS X can be found in the Release Notes at http://developer.apple.com/documentation/java. It is primarily geared toward developers of pure Java applications, but it will also be useful for Cocoa Java development and WebObjects Java development. This is not a tutorial for the Java language. If you are not already proficient in Java, this document will still be helpful to you but it will not teach you about the Java language and J2SE packages. Many resources exist in print and on the Web for learning the Java programming language. If you are new to programming in Java, you may want to start with one of Suns tutorials available online at http://developer.java.sun.com/developer/onlineTraining/new2java/.

How to Use This Book

Overall, the purpose is document to highlight how Java development in Mac OS X may be different if you are accustomed to Java development on other platforms. It does not attempt to present a conclusive overview of Java itself. It is meant as a supplemental guide to help you save time and development effort. It introduces you to the tools available to you, discusses some details of how Java is implemented, points out potential trouble spots, and provides some reference documentation. This book has information for many different types of Java developers. To help you determine what information is important for you the following listing provides an overview of the contents of the following chapters:

Setting the Classpath

In Mac OS X, you treat the classpath the way you would in any BSD shell. You can use setenv classpathnewClasspathAddition to add to the classpath for the duration of the current session for that particular Terminal window. You still have to explicitly add a reference to this variable when compiling by typing javac -classpath %CLASSPATHfilename. You can determine the current value of CLASSPATH with the command echo $CLASSPATH. By default no CLASSPATH variable is explicitly set for the shell, although Java knows to look in the various Library/Java/Extensions folder for developer-supplied JAR files. You can avoid retyping the setenv classpath command for each Terminal session by automatically adding paths to your classpath shell startup script (.cshrc or.tcshrc for the default tcsh shell). For example, find or create ~/.cshrc. That file should have a line that looks similar to setenv CLASSPATH ".:/Users/username/Projects/HelloWorld/:/Users/username/Projects/HelloWorld/HelloWorld.jar". In this example, the current directory, the specific directory of a particular project, and a JAR file in that directory are included in the classpath.

Java Output

When you launch a Java application from the command line, standard output goes to the Terminal window. When you launch a Java application by double clicking it, your Java output is displayed in the Console application in /Applications/Utilities. Applets that use the Java Plug-in may display output in the Java Console.

CHAPTER 3

Deployment Options
There are basically four different distribution methods for Java applications in Mac OS X. You can distribute your applications as a JAR file, a Mac OS X Java application, a Java Web Start application, or an applet. They each have different benefits as outlined in the following sections.
Distributing Your Application as a JAR File
The most basic distribution method for your Java applications is as a JAR file. It is the simplest way for you as a developer since it requires very little, if any, changes from the JAR files you distribute on other platforms. It does though, have drawbacks for the end user. The major drawback being that Swing applications look out of place with their odd application names in the menu bar and generic Java icons in the dock. Considering this alone, deploying your application from a JAR file is not recommended on Mac OS X if your application has a graphical interface and will be run by general users. If you do choose to deploy your application from a JAR file on Mac OS X, it is important to remember to include in your JAR file a valid manifest file that declares the class that contains the main method. Without one, users will have to resort to launching your application from the command line. This will seem very outdated for users whose platform has let them launch an application simply by double-clicking it for almost twenty years! If you do not have the class with main declared in your JAR file a simple way to fix this is as follows: 1. 2. Unarchive your JAR file into a working directory with some variant of jar xvf myjar.jar In the 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, Main-Class: HelloWorld. Archive you 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

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 Builders 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 (page 64). 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 (page 69). Project Builder Tutorial (page 57) provides a tutorial on using Project Builder to build a Mac OS X native application.
Setting Runtime Properties in Project Builder
When you begin a new Java Swing or Java AWT application project in Project Builder, the ClassPath and MainClass properties are generated automatically. The ClassPath property is updated as you add and remove.class and.jar files. If you change the name of your main class or want to append values for any of the other properties available in Mac OS X Java System Properties (page 75), you may do so by editing the target settings. Choose Edit Active Target from the Project menu. In the resulting window (or pane depending your settings) you can modify the settings in a more user-friendly manner than by editing the property list by hand. Some of the most common properties are set with a checkbox. Other properties are set in the Additional Properties and Additional VM Options fields.
Setting Runtime Properties in MRJAppBuilder
The Java Properties pane of MRJAppBuilder allows you to set Java runtime properties. The main and classpath fields are not editable. These values are derived from your settings in the Application pane. A default set of properties is already provided but it is simple to add more: 1. 2. 3. 4. Click the Add button. In the property field, put the name of the system property as specified in Mac OS X Java System Properties (page 75). Fill in the appropriate value for that property. The Description field can be left blank; its information will not be saved.

When you build your application, you will see the specified settings in the Info.plist and MRJApp.properties files.

Java Web Start

Java Web Start provides yet another way you can distribute your Java applications on Mac OS X. Although not a standard part of Java 1.3.1, Mac OS X does provide Java Web Start with the default installation of the operating system. This is an implementation of the Java Network Launching Protocol & API (JNLP) Specification, v1.0.1. This means that if you choose to build JNLP-aware applications, Mac OS X users do not need to do anything to take advantage of them. 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 3-3 (page 24). 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 offer, but it 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 3-3 Java Web Start integration
The desktop integration setting can be changed in the Preferences of the Java Web Start application. There are only a few details to be aware of in 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 includes J2SE 1.3.1, so if your application specifically requires JRE 1.2 or 1.4, it will not work. Specifications for versions numbers that can expand to include 1.3.1 will work though, for example 1.2+ or 1.3+. It is s not necessary to set up proxy information explicitly in the Web Start application. Java Web Start in Mac OS X automatically picks up your proxy settings from the Network preference pane. Java Web Start caches its data in the users /Library/Caches/Java Web Start directory.

Applets

Applets have always been one of the most common deployment methods for Java. Mac OS X provides a robust environment for applet development through the use of Suns Java Plug-in. Applets use the same 1.3.1 VM that Java applications use. Their behavior should be similar to the behavior of Suns Java Plug-in. Of course as with all applet deployment, the host platforms support for Java is only part of the story. How Web browsers interpret your HTML code to launch the applet is also key. This section gives you some relevant information for deploying your applets in Mac OS X.

Treated as an <EMBED> tag, which by default maps to the application/x-java-applet mime type.

Java Plug-in

OmniWeb Opera Chimera Treated as an <EMBED> tag. Java Plug-in
Benefits of Using the Java Applet Plug-in
Using the Java Applet Plug-in provides a better experience for people that use your applets. Changes have been made in the areas discussed below. JAR Caching You can now designate that you want to store certain JAR files for repeated use. If you developed for Mac OS 9, notice that this is similar to JAR caching on MRJ 2.2.x. The cache is stored in the users home folder in Library/Caches/Java. To take advantage of JAR file caching, you may need to modify your HTML with the following tags:
<PARAM NAME = "cache_option" VALUE="plugin">

Turns on caching.

<PARAM NAME = "cache_archive" VALUE="a.jar, b.jar, c.jar">
This is an optional tag used to specify the list of JAR files you want to cache. JAR files in cache_archive are searched first, then the JAR files designated with the ARCHIVE tag are used
<PARAM NAME = "cache_version" VALUE="1.2.0.1, 2.1.1.2, 1.1.2.7">
This is an optional tag used to specify the version number of the JAR files designated with cache_archive. Each value corresponds to the respective JAR files designated with cache_archive. If the version value is newer than what is cached, the JAR file in the cache is updated. If this tag is omitted, the plug-in checks the server to see if there is a newer version available and caches that version. JAR file caching in Mac OS X conforms to the Java 1.3.1_03 standard. It does not conform to the Java 1.4 standard. This means that there are certain things you should keep in mind:
JAR files specified with the ARCHIVE tag are not cached. The cache_version_ex parameter is not supported. There is no JAR file indexing support. For better forward compatibility, it is suggested that you use the cache_archive and cache_version parameters.
Signed JAR Files If a user decides to always trust your JAR file, a certificate is stored in the users home folder in

Library/Preferences/Java Plugin certificates 1.3.1.
Users can view their JAR file certificates in the Java Plugin Settings application. The Java Console The Java Console provides a way to log and trace the behavior of your applet while it is running. It can give you interactive thread information and allow you to force garbage collection. The Java Console is the display medium for System.outSystem.err for applets. The Java Console is visible if you select the option Show Java Console in the Java Plugin Settings utility.
Java Plugin Settings Application The Java Plugin Settings application allows users to fine-tune how applets behave in Mac OS X. It behaves on Mac OS X as it does on other platforms. It is important to recognize that settings you make while testing may not be the settings that users have on their computers. These settings are stored per user in ~/Library/Preferences/com.apple.java.plugin.properties131.

CHAPTER 4

The Development Environment
Mac OS X provides a very robust environment for Java development. This chapter outlines some of the tools available to you in Mac OS X. It also discusses some things that may be different in the development environment from other platforms that you may have used for Java development.

Java Development Tools

There are three basic types of Java development tools available to you in Mac OS X:
There are the standard command-line Java tools that you normally associate with the Java Development Kit (JDK). Apple provides additional command-line and GUI-based tools free with the Mac OS X Developer Tools. There are many third-party tools, both open source and commercial, that you can use for Java development on Mac OS X.

Standard JDK Tools

Most of the same tools that you would expect to find on Linux, Solaris, or Windows with the Java Development Kit (JDK) installed are included with Mac OS X by default. There are no extra installation steps required. Most of the standard JDK tools are command-line tools. The Java command-line tools are accessible from /usr/bin and /Library/Java/Home/bin. These tools are included with the default installation of Mac OS X:

basic Java tools

java runtime and virtual machine javaccompiler javahC header and stub file generator javapclass file disassembler jdbdebugger jararchive tool javadocAPI documentation generator appletviewerapplet viewer extcheckJAR conflict detection utility
Remote Method Invocation (RMI) tools
rmicRMI stub compiler rmidRMI activation system daemon rmiregistryremote object registry serialvertool to obtain class serial version
internationalization tool
native2acsiitext converter to Unicode

security tools

jarsignerJAR signing and verification tool keytoolkey and certificate management tool policytooltool to manage Java policy files
Java Interface Definition Language (IDL) and RMI over Internet Inter-ORB Protocol (IIOP) tools
idljIDL-to-Java compiler tnameservJava IDL name server starter script
Documentation on using these tools is available in the online manual (man) pages. These are available in Project Builder under the Help menu as well as in the shell itself.
Displaying a Java Stack Trace
When debugging your Java applications, you may want to display a stack trace. If you launched your application from the command line, CTRL-\ generates a SIGQUIT signal and prints the current stack trace in your Terminal window. If you launch your Java application from the Finder, you just need to find its process ID (PID) and deliver a SIGQUIT signal to that process. You see the stack trace in the Console application. For example, first launch Applet Launcher, Terminal, and Console (all are in Applications/Utilities). If you want to generate a stack trace for Applet Launcher, in Terminal type:
ps -auxwww | grep "Applet Launcher"
You would see the results as something like:
bgerfen 1490 0.0 2.17912 ?? S 2:39PM 0:05.76 /Applications/Utilities/Java/Applet Launcher.app/Contents/MacOS/Applet Launcher -psn_0_5898241 bgerfen 1507 0.0 0.4 std R+ 2:41PM 0:00.00 grep -i Applet Launcher
Once you have the appropriate PID, kill it. For this example this looks like:

Proceed with the installation by following the onscreen prompts. Once you have restarted your computer, you should find the command-line Java tools installed in /usr/bin.
The Mac OS X Developer Tools CD comes with Mac OS X and is provided with new Macintosh computers. If you do not have a current copy of the Mac OS X Developer Tools, you may download them from the Apple Developer Connection Web site at http://connect.apple.com. Even if you do not want to use the Apple provided GUI-based tools, you should install the Mac OS X Developer Tools since they contains some important tools not installed by default. Note: The Developer Tools available through the Apple Developer Connection online may be a more recent version than the Developer Tools CD that came with your copy of Mac OS X. It is advisable to check the website first. Compatibility information between releases is discussed in the release notes which are available online at http://developer.apple.com/releasenotes.

CHAPTER 5

Cross-Platform Practices for Great Native Behavior
If you are developing Java applications that you plan to deploy on multiple platforms, there are some things that you should keep in mind to support Mac OS X as well as the other platforms. This chapter discusses some basic points to consider and small changes you can make to your Java code to help it run well on any platform, but are especially important to consider to make your application look like a Mac OS X application. In general, these changes do not require you to use any APIs or properties specific to Mac OS X. This chapter mainly discusses user interface issues.

The Aqua Look and Feel

Before discussing cross-platform coding practices, it is important to lay the foundation of what is available in Mac OS X. The default interface to the operating system is called Aqua. Although other interfaces can be displayed in Mac OS X, there is great benefit in usability by adhering closely to the native interface. To that end, Apple has worked hard to make your Java applications appear and behave as much like native applications as possible. Taking advantage of the basic look of the Aqua user interface is very simple. It requires you to do nothing other than write clean Java code. In Mac OS X, the default pluggable look and feel (PLAF) for Swing applications, com.apple.mrj.swing.MacLookAndFeel, gives an Aqua appearance to your Swing applications. So if you dont explicitly change your code to invoke another look and feel, Swing applications look like native applications by default. In general it is good practice to avoid explicitly setting the PLAF in your Java code.This makes your application fit in much better on any platform. In the case of Mac OS X, this is especially true. If do you need to change the look and feel of your application to test it for different platforms, it is better to set the swing.defaultlaf Java property for your application at runtime by passing in -Dswing.defaultlaf=yourLookAndFeel when launching the application. For development purposes, you may want to temporarily change Mac OS Xs default look and feel. You can do this by modifying the swing.properties file in /Library/Java/Home/lib. You dont need to use AWT components for the native look of Aqua because Swing provides it. You can enjoy further benefits in performance and predictable graphics behavior by not mixing the heavyweight and lightweight components of AWT and Aqua. Behavior is part of a user interface as well as appearance. Automatic adoption of the Aqua appearance is a first step, but there are many details that still are in your hands when trying to provide the best Aqua experience. Inside Mac OS X: Aqua Human Interface Guidelines is the definitive guide for how applications should appear and behave in Mac OS X and why they should behave that way. If you have a decision to make that is not specified anywhere else, that document is a great source of answers to user interface questions. If you find areas where your pure Java applications do not take advantage of these guidelines, please let Apple know. There are numerous details that go into designing a first-class application on any platform. Although it may be impossible to build a perfect application, there are a few topics that are hot issues to users of a particular platform. As a Java developer, a few areas to keep in mind as you design are discussed in the following sections.

Menu Item Icons

Like mnemonics, menu item icons are also available and functional via Swing in Mac OS X. They are not a standard part of the Aqua interface, although some applications do display themmost notably the Finder in the Go menu. You may want to consider applying these icons conditionally based on platform. Whether or not you choose to display menu item icons in Mac OS X, you should be aware that Aqua does specify a specific set of special characters to be used in menus. See the information on using special characters in menus in Inside Mac OS X: Aqua Human Interface Guidelines

Contextual Menus

There is no problem supporting contextual menus in your Java applications on Mac OS Xthey are fully supported. There are slight differences in terminology though. Java calls them popup menus while Aqua calls them contextual menus. More important is how they are triggered on different platforms. On Mac OS X, they are triggered by a Control-click. (By default, the second button of a two-button mouse maps to Control-click in Mac OS X.) In Windows, the right mouse button is the standard trigger for contextual menus. These are two very different cases, which could result in fragmented and conditional code. One important aspect of both triggers is shared, the mouse click. To ensure that your program is interpreting the proper contextual menu trigger, it is again a good idea to ask the AWT to do the interpreting for you with java.awt.event.MouseEvent.isPopupTrigger.
The method is defined in java.awt.event.MouseEvent because you need to activate the contextual menu through a java.awt.event.MouseListener on a given component when a mouse event on that component is detected. The important thing to determine is how and when to detect the proper event. In Mac OS X, the pop up trigger is set on MOUSE_PRESSED. In Windows it is set on MOUSE_RELEASED. For portability, both cases should be considered as shown in Listing 5-4 (page 45). Listing 5-4 Using isPopupTrigger to detect contextual menu activation
JLabel label = new JLabel("I have a pop up menu!"); label.addMouseListener(new MouseAdapter(){ public void mousePressed(MouseEvent e) { evaluatePopup(e); } public void mouseReleased(MouseEvent e) { evaluatePopup(e); } private void evaluatePopup(MouseEvent e) { if (e.isPopupTrigger()) { // show the pop up menu. } } });

Event Handling

Two notes on event handling may be useful to your in your development and deployment of applications in Mac OS X:
Many of the Swing and AWT components are implemented with native code from the Carbon API of Mac OS X. Although this should not affect your Java code, it might be important information in debugging applications that do not appear to behave correctly, especially in regard to the runtime handling of events. If you do find an issue where the event handling is not as specified by the Java 2 specification, please file a bug as explained in Filing and Tracking Bugs (page 10). Although mouse-down events from additional buttons on multi button USB mice are delivered correctly, mouse-up and mouse-drag events involving the additional buttons may not be delivered with the correct modifiers. There may be ambiguity between various button masks and meta key masks. Use the utility functions as a workaround (for example, java.awt.event.InputEvent.isMetaDown) instead of accessing the modifiers directly.

The Window Menu

One of the suggestions in Inside Mac OS X: Aqua Human Interface Guidelines is that all Mac OS X applications should provide a Window menu to keep track of all currently open windows. A Window menu should contain a list of currently active (visible) windows, with the corresponding menu item checked if a given window is currently in the foreground. Likewise, selection of a given Window menu item should result in the corresponding window being brought to the front. New windows should be added to the menu, and closed windows should be removed. The ordering of the menu items is typically the order in which the windows appeared. Inside Mac OS X: Aqua Human Interface Guidelines has more specific guidance on the Window menu.

The Application Menu

Any Java application that uses AWT/Swing, or is packaged in a double-clickable application bundle, is automatically launched with an application menu similar to native applications on Mac OS X. This application menu, by default, contains the full name of the main class as the title. This name can be changed using the com.apple.mrj.application.apple.menu.about.name application property or the -Xdock:name command-line property. According to the Aqua guidelines, the name you specify for the application menu should be no longer than 16 characters. Figure 6-1 (page 51) shows an application menu.

Figure 6-1

Application menu for a Java application in Mac OS X
The next step to customizing your application menu is to have your own handling code called when an item in the application menu is chosen. Apple has provided a means for this through interfaces in the com.apple.mrj package. Each interface has a special callback method that is called when the appropriate application menu item is chosen. The following callback interfaces for the application menu are available:
com.apple.MRJAboutHandler, to handle the About menu item. com.apple.MRJPrefsHandler, to handle the Preferences menu item. com.apple.MRJQuitHandler, to trigger final clean-up logic when the Quit menu item is chosen. By default, that Quit menu item just calls System.exit. You might actually want to do more than just exit.
To handle a given application menu item: 1. 2. Implement the appropriate handler interface. Define the appropriate handler method in your implementation: handleAbout, handlePrefs, or handleQuit. Register your handler using the appropriate static methods in the com.apple.mrj.MRJApplicationUtils class: either registerAboutHandler, registerPrefsHandler, or registerQuitHandler.
You can see examples of these implementations in a default Swing application project in Project Builder. If your application is to be deployed on other platforms, where Preferences, Quit, and About are accessed elsewhere on the menu bar (in a File or Edit menu, for example), you may want to make this placement conditional based on the operating system of the host platform. This is preferable to just adding a second instance of each of these menu items for Mac OS X. This minor modification can go a long way to making your Java application feel more like a native application on Mac OS X.

More MRJ Handlers

In addition to the interfaces provided for handling application menu items, Java on Mac OS X provides two other handlers:
com.apple.MRJOpenApplicationHandler, which lets you respond to an Open Application Apple event.
com.apple.MRJOpenDocumentHandler, that responds to double-clicking a supported document or the dragging of a document onto your applications icon.
These handler interfaces are intended to enhance a Java applications behavior in the Mac OS X Finder and are used in the same manner as the application menu interfaces described above.
Localizing Packaged Java applications on Mac OS X
To run correctly in non-English locales, Java applications bundles need to have the appropriate localized folders inside the application package. This is true even if the Java application handles its localization through Java ResourceBundles. Specifically, you need to have a folder named with the locale name and the.lproj suffix present in the applications Resources folder for any locale that you wish to use. For example, you need a Japanese.lproj folder inside YourApplication.pkg/Contents/Resources/ in order for Japanese localization to work correctly. The folder itself can be empty, but it must be present for Mac OS X to set the locale correctly when the application launches. Otherwise Mac OS X launches your application with the English US locale. The Bundle Services documentation and Inside Mac OS X: System Overview, both available from http://developer.apple.com/documentation, provide more details about the application bundle format.

QuickTime for Java

QuickTime for Java provides a cross-platform API that allows Java developers to build multimedia components, including streaming audio and video, into applications and applets for both Macintosh and Windows. More information on QuickTime for Java is available online at http://developer.apple.com/quicktime/qtjava/.

Java Core Audio Packages

The JAR file is copied into the /Contents/Resources/Java directory of the resulting application bundle. Now go back to the Application pane. Notice that the path to this JAR file was automatically added to the /tmp path you had there before. (You can get rid of that reference to /tmp now if you havent already.) You now have a Mac OS X application that a user can install by simply dropping in the Finder without having to deal with installing anything else or being concerned with where the application is installed.
Making Your Application More Mac-like
So far you have built a basic application that has some features that Mac users expect. For example they can install it with a simple drag and drop. If you launch that application, you will notice something missing. The icon in the Dock is a generic Java icon. You can fix that easily enough in MRJAppBuilder. For the sake of this example, just copy an icon from another application, in this case the icon from the prebuilt version of the FileChooserDemo application. To do this, select the generic icon in the Application pane. It is near the bottom of the pane, in the Output file section. If you click it, it opens a file chooser. Navigate to the file named JavaApp.icns in
/Developer/Examples/Java/JFC/FileChooserDemo/FileChooserDemo.app/Contents/Resources
and click Select. (You will probably need to change the Format pop-up menu to All Files from the default Icon Files to navigate there.) Now if you build the application, you should see that it displays the new icon in the Dock.

Java Properties Pane

An icon is only the first step. There are a few other things you can do to make a well-written Java application hard to distinguish from a native Mac OS X application. MRJAppBuilder provides an interface for making a lot of these changes in the Java Properties pane. Before going there, launch the FileChooserDemo application that you just built. Notice that the window has a white bar at the bottom of the window as shown in Figure B-4 (page 72). Figure B-4 FileChooserDemo application with relics
This is because by default, MRJAppBuilder sets certain system properties. In this case, com.apple.mrj.application.growbox.intrudes is set to false. The result is that an extra 15 pixels are added to the window. You can correct this in the Java Properties pane. Click the Java Properties tab. This pane contains properties that are passed to the application when it is run. Of special note here is the Parameters property. This is where you can specify any command-line parameters that need to be passed to your application when it is run. To see the effect of modifying the Java properties, change the value of the growbox.intrudes property from false to true as in Figure B-5 (page 73).

Figure B-5

Modifying the growbox.intrudes property
Quit the previously built FileChooserDemo if it is still running, and build and run the new version. Notice that the relics no longer surround the window when you switch between the different interface styles. Figure B-6

java -Dcom.apple.macosx.useScreenMenuBar=trueYourSwingApp

Table C-4 Property

System properties related to the graphical user interface Default Notes Value

com.apple.hwaccel

Turns on hardware graphics acceleration for the not commented out of
/Library/Java/Home/lib/hwexclude.prop set to false, hardware acceleration is turned of used in conjunction with the com.apple.hwacce

property.

Property

Default Notes Value

com.apple.hwexclude
When specific video card designation strings are with this property, hardware graphics acceleratio turned on for the respective video cards. It is be other video cards. When this property is set, ignored.
/Library/Java/Home/lib/hwexclude.prop
com.apple.macos.use-file-dialog-packages
When set to true, causes java.awt.FileDial application packages as if they were files and doe navigation into them.
Puts Swing menus in the Mac OS X menu bar if u Aqua look and feel. Java applications created wi Builder have this set to true. Note that JMenuB JDialogs are not moved to the Mac OS X menu b
com.apple.macos.useSmallTabs
If defined, and set to true, tab controls in Swing a more closely resemble the Metal look and feel. I false, the tabs assume a larger size more simila default Aqua controls. Use anti-aliasing when rendering text. Use anti-aliasing when rendering graphics.
com.apple.macosx.AntiAliasedTextOn com.apple.macosx.AntiAliasedGraphicsOn

true true

com.apple.mrj.application.apple.menu.about.name None
If defined, an About command is added to the to application menu and can be detected by regist com.apple.mrj.AboutHandler. Java applicati with Project Builder have this set to initial name project.
com.apple.mrj.application.growbox.intrudes
Resizable windows growbox (resize control) intr AWT content. If turned off, the bottom of the wi pushed down 15 pixels. Enables live resizing of windows.
com.apple.mrj.application.live-resize

REVISION HISTORY

Document Revision History
This table describes the changes to Java 1.3.1 Development for Mac OS X. Date 2003-04-01 Notes Changed the title from Java Development on Mac OS X: Java 2 Platform, Standard Edition Version 1.3.1 to Java 1.3.1 Development for Mac OS X. Format completely revised. Changed target emphasis from Mac OS 9 Java developers to Java developers coming from other platforms. Updated to include new features introduced in Java 1.3.1, including the Java.applet.plugin and information about hardware acceleration. Updated for Mac OS X version 10.2. Modified tutorials to work with new operating system and corrected some typographical errors. Document originally released with a focus on describing what is different in Java development from Mac OS 9 to Mac OS X.