Java 1.3.1 Development for Mac OS X
(Legacy)
2002-09-01

---

Java and all Java-based trademarks are
Apple Inc.
trademarks or registered trademarks of Sun
© 2002 Apple Computer, Inc.
Microsystems, Inc. in the U.S. and other
All rights reserved.
countries.
OpenGL is a registered trademark of Silicon
No part of this publication may be reproduced,
Graphics, Inc.
stored in a retrieval system, or transmitted, in
any form or by any means, mechanical,
UNIX is a registered trademark of The Open
electronic, photocopying, recording, or
Group
otherwise, without prior written permission of
Simultaneously published in the United States
Apple Inc., with the following exceptions: Any
and Canada.
person is hereby authorized to store
Even though Apple has reviewed this document,
documentation on a single computer for
APPLE MAKES NO WARRANTY OR REPRESENTATION,
personal use only and to print copies of
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO
THIS DOCUMENT, ITS QUALITY, ACCURACY,
documentation for personal use provided that
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
the documentation contains Apple’s copyright
PURPOSE. AS A RESULT, THIS DOCUMENT IS
PROVIDED “AS IS,” AND YOU, THE READER, ARE
notice.
ASSUMING THE ENTIRE RISK AS TO ITS QUALITY
AND ACCURACY.
The Apple logo is a trademark of Apple Inc.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
Use of the “keyboard” Apple logo
INDIRECT, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES RESULTING FROM ANY
(Option-Shift-K) for commercial purposes
DEFECT OR INACCURACY IN THIS DOCUMENT, even
without the prior written consent of Apple may
if advised of the possibility of such damages.
constitute trademark infringement and unfair
THE WARRANTY AND REMEDIES SET FORTH ABOVE
competition in violation of federal and state
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple
laws.
dealer, agent, or employee is authorized to make
any modification, extension, or addition to this
No licenses, express or implied, are granted
warranty.
with respect to any of the technology described
Some states do not allow the exclusion or limitation
in this document. Apple retains all intellectual
of implied warranties or liability for incidental or
property rights associated with the technology
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
described in this document. This document is
you specific legal rights, and you may also have
intended to assist application developers to
other rights which vary from state to state.
develop applications only for Apple-labeled
computers.
Every effort has been made to ensure that the
information in this document is accurate. Apple
is not responsible for typographical errors.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
.Mac is a registered service mark of Apple Inc.
Apple, the Apple logo, AppleScript, Aqua,
Carbon, Cocoa, eMac, iBook, Mac, Mac OS,
Macintosh, Objective-C, OpenDoc, Pages,
PowerBook, Quartz, QuickTime, TrueType, and
WebObjects are trademarks of Apple Inc.,
registered in the United States and other
countries.
Finder and iWeb are trademarks of Apple Inc.
OPENSTEP is a registered trademark of NeXT
Software, Inc.
GeForce4 is a trademark of NVIDIA Corporation.

---

Contents
Chapter 1
About This Book 9
How to Use This Book 9
Other Resources 10
Filing and Tracking Bugs 10
Chapter 2
How Java Is Implemented in Mac OS X 11
Java Integration in the Operating System 11
What Is Included 12
Java 2D Graphics Implementation 13
The Virtual Machine 14
Performance Profiling Tools 14
Nonstandard Virtual Machine Options 15
The Java Native Interface 15
Environmental Differences 17
Finding JAVAHOME 17
Where to Put Extensions 17
Where to Put Preferences 18
Setting the Classpath 18
Java Output 18
Chapter 3
Deployment Options 19
Distributing Your Application as a JAR File 19
Mac OS X Java Applications 19
Application Bundles 20
Property List Attributes for Java Applications 21
Setting the Java Runtime Properties for an Application Bundle 23
Java Web Start 24
Applets 25
Accessing Mac OS X–Specific Properties From Applets 25
Java Applet Plug-in 25
Chapter 4
The Development Environment 29
Java Development Tools 29
Standard JDK Tools 29
Other Command-Line Tools 31
GUI-Based Tools 31
Where to Get the Tools 34
3
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

CONTENTS
Chapter 5
Cross-Platform Practices for Great Native Behavior 37
The Aqua Look and Feel 37
Placing and Painting Components 38
Layout Managers 38
Sizing Components 38
Coloring Components 38
Windows and Dialogs 39
Use of the Multiple Document Interface 39
Windows With Scroll Bars (Using JScrollPanes) 39
File Choosing Dialogs 40
Menus 43
Menu Shortcuts 43
Menu Item Icons 44
Contextual Menus 44
Event Handling 45
Chapter 6
Using Native Features of Mac OS X in Java Applications 47
Modifying the Default Settings for Hardware Graphics Acceleration 47
Advanced Options 48
Video Cards Designation Strings 48
Specifying a Name and Icon for Command-Line Applications 49
Using the Macintosh Menu Bar 49
The Window Menu 50
The Application Menu 50
More MRJ Handlers 51
Localizing Packaged Java applications on Mac OS X 52
QuickTime for Java 52
Java Core Audio Packages 52
Java Spelling and Speech Frameworks 52
JDirect 53
Human Interface Toolbox Synchronization 53
Debugging Features for JDirect 53
MethodClosureUPP Not Supported 54
JDirect Access to Bundles 54
Embedding Applets in Native Applications 54
Cocoa Java 55
Appendix A
Project Builder Tutorial 57
Building a Java Application With Project Builder 57
The Makeup of a Project Builder Project 57
Building a Java Project 58
Adding Your Source Files 59
Modifying the Application Parameters 64
4
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

CONTENTS
Building Applets With Project Builder 68
Appendix B
MRJAppBuilder Tutorial 69
Building a Basic Application 69
Building a More Robust Application 71
Making Your Application More Mac-like 72
Java Properties Pane 72
Mac OS X Pane 74
Appendix C
Mac OS X Java System Properties 75
Java Virtual Machine Properties 75
Mac OS X Application Properties 76
Mac OS X–Specific Properties 77
Document Revision History 79
Glossary 81
5
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

CONTENTS
6
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

Figures, Tables, and Listings
Chapter 2
How Java Is Implemented in Mac OS X 11
Figure 2-1
Architecture of Mac OS X 11
Figure 2-2
Metal and Aqua look and feel on Mac OS X 12
Figure 2-3
Mac OS X as a Java development platform 13
Table 2-1
HotSpot VM options 15
Chapter 3
Deployment Options 19
Figure 3-1
Show application bundle contents 20
Figure 3-2
Contents of a Java application bundle 21
Figure 3-3
Java Web Start integration 24
Figure 3-4
Effect of HTML tags in Mac OS X 10.2 26
Table 3-1
Interpretation of HTML tags in common Mac OS X browsers
26
Listing 3-1
Info.plist file for simple Java application 21
Chapter 4
The Development Environment 29
Figure 4-1
MRJAppBuilder 32
Figure 4-2
Tools in /Developer/Applications 34
Chapter 5
Cross-Platform Practices for Great Native Behavior 37
Figure 5-1
java.awt.FileDialog 40
Figure 5-2
javax.swing.jFileChooser 41
Figure 5-3
Application displayed as an atomic object 42
Figure 5-4
Application displayed as a directory 42
Listing 5-1
Setting JScrollBar policies to be more like Aqua 40
Listing 5-2
Explicitly setting KeyStrokes based on the host platform 43
Listing 5-3
Using getMenuShortcutKeyMask to set meta keys 44
Listing 5-4
Using isPopupTrigger to detect contextual menu activation 45
Chapter 6
Using Native Features of Mac OS X in Java Applications 47
Figure 6-1
Application menu for a Java application in Mac OS X 51
Figure 6-2
Java Applet Plug-in versus Java Embedding Framework 55
Table 6-1
Video-card designation strings
49
Appendix A
Project Builder Tutorial 57
Figure A-1
Project folder contents 58
7
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

FIGURES, TABLES, AND LISTINGS
Figure A-2
Result of building a default project 59
Figure A-3
Generic Java icon 59
Figure A-4
Default files in a new Java Swing application 60
Figure A-5
Delete References alert 61
Figure A-6
Selecting files to add to a Java project 62
Figure A-7
Copy items into project folder option 63
Figure A-8
Contents of a built application 64
Figure A-9
Target settings 65
Figure A-10
Pure Java-Specific settings 66
Figure A-11
Expert View 67
Figure A-12
Default setting for live resizing
67
Figure A-13
Applet Launcher 68
Appendix B
MRJAppBuilder Tutorial 69
Figure B-1
MRJAppBuilder Application pane 70
Figure B-2
A successful build 70
Figure B-3
Merge Files pane 71
Figure B-4
FileChooserDemo application with relics 72
Figure B-5
Modifying the growbox.intrudes property 73
Figure B-6
com.apple.mrj.application.growbox.intrudes=true 73
Figure B-7
Application bundle contents 74
Appendix C
Mac OS X Java System Properties 75
Table C-1
JVM properties 75
Table C-2
required Mac OS X application properties 76
Table C-3
Application launch properties 76
Table C-4
System properties related to the graphical user interface 77
8
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

CHAPTER 1
About This Book
Important: The information in this document is obsolete and should not be used for new development.
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://develop-
er.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 Sun’s tutorials available online at http://developer.java.sun.com/de-
veloper/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:
■
“How Java Is Implemented in Mac OS X” (page 11) Presents a broad overview of how Java works in Mac
OS X. It also highlights some areas where things differ between Java in Mac OS X and other platforms.
This chapter has many important details for anyone doing Java development on Mac OS X. It is a good
place to begin if you don’t have specific questions, but want an overview of what is available.
■
“Deployment Options” (page 19) Reveals the four suggested deployment vehicles for your Java
applications on the Mac OS X operating system. If you have a Java application that you want to distribute
on Mac OS X, this chapter is important reading. It discusses not only details to be aware of in the standard
distribution methods, but also presents some unique to Mac OS X.
How to Use This Book
9
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

CHAPTER 1
About This Book
■
“The Development Environment” (page 29) If you are new to Java development on Mac OS X, this chapter
provides important background information on what tools are available to you.
■
“Cross-Platform Practices for Great Native Behavior” (page 37) Discusses some considerations you should
make while designing your applications so that they will behave just as well on Mac OS X as they do on
other platforms.
■
“Using Native Features of Mac OS X in Java Applications” (page 47) Explores some of the options available
to you in Mac OS X that are not available on other platforms. Some things discussed in this chapter will
tie your application to Mac OS X specifically, while other things will help you to add value to your Java
applications on Mac OS X without affecting your application’s cross-platform compatibility. The information
in this chapter may be important if you are designing a new application or modifying an existing one.
■
“Project Builder Tutorial” (page 57) If you want to take advantage of the free Project Builder IDE for you
Java development, this is a useful place to start.
■
“MRJAppBuilder Tutorial” (page 69) This is a tutorial for anyone distributing a Java application on Mac
OS X.
■
“Mac OS X Java System Properties” (page 75) Provides a listing of the common Java system properties
useful in Mac OS X.
Other Resources
This document and other Java documentation for Mac OS X, including the javadoc API reference, is available
online at http://developer.apple.com/documentation/java. A subset of this documentation is installed in
/Developer/Documentation/Mac OS X/Java on a Mac OS X system with the Mac OS X Developer Tools.
You can view this documentation through a Web Browser or through Project Builder (from Project Builder’s
Help menu, choose Developer Help Center).
The main Java technology page http://developer.apple.com/java contains many links to information about
Java development in Mac OS X.
The java-dev mailing list is a great source of information on a wide range of Java development topics in
Mac OS X. You can sign up for this list at http://lists.apple.com.
Sun’s Java site, http://java.sun.com is the essential reference point for Java development in general.
Filing and Tracking Bugs
If you find issues with the implementation of Java that are not represented in this document or want to
follow the resolution of an issue, you may do so online through Radar, Apple’s bug tracking system. To access
Radar, you will need an Apple Developer Connection (ADC) account. You can view the ADC membership
options, including the free online membership at, http://developer.apple.com/membership/index.html. With
an ADC membership, you can file and view bugs at http://bugreport.apple.com. When filing new bugs for
Java on Mac OS X, please use Java (new bugs) for the Component and X as the Version.
10
Other Resources
Legacy Document | 2002-09-01 | © 2002 Apple Computer, Inc. All Rights Reserved.

---

Document Outline

• Java 1.3.1 Development for Mac OS X
  • Contents
  • Figures, Tables, and Listings
  • About This Book
    • How to Use This Book
    • Other Resources
    • Filing and Tracking Bugs
  • How Java Is Implemented in Mac OS X
    • Java Integration in the Operating System
    • What Is Included
    • Java 2D Graphics Implementation
    • The Virtual Machine
      • Performance Profiling Tools
      • Nonstandard Virtual Machine Options
      • The Java Native Interface
    • Environmental Differences
      • Finding JAVAHOME
      • Where to Put Extensions
      • Where to Put Preferences
      • Setting the Classpath
      • Java Output
  • Deployment Options
    • Distributing Your Application as a JAR File
    • Mac OS X Java Applications
      • Application Bundles
      • Property List Attributes for Java Applications
      • Setting the Java Runtime Properties for an Application Bundle
        • Setting Runtime Properties in Project Builder
        • Setting Runtime Properties in MRJAppBuilder
    • Java Web Start
    • Applets
      • Accessing Mac OS X…Specific Properties From Applets
      • Java Applet Plug-in
        • Taking Advantage of the Java Applet Plug-in with HTML
        • Benefits of Using the Java Applet Plug-in
          • JAR Caching
          • Signed JAR Files
          • The Java Console
          • Java Plugin Settings Application
  • The Development Environment
    • Java Development Tools
      • Standard JDK Tools
        • Displaying a Java Stack Trace
      • Other Command-Line Tools
      • GUI-Based Tools
        • Project Builder
        • MRJAppBuilder
        • Applet Launcher
        • Other Tools
      • Where to Get the Tools
  • Cross-Platform Practices for Great Native Behavior
    • The Aqua Look and Feel
    • Placing and Painting Components
      • Layout Managers
      • Sizing Components
      • Coloring Components
    • Windows and Dialogs
      • Use of the Multiple Document Interface
      • Windows With Scroll Bars (Using JScrollPanes)
      • File Choosing Dialogs
        • Dealing With Bundles in Mac OS X
    • Menus
      • Menu Shortcuts
      • Menu Item Icons
      • Contextual Menus
    • Event Handling
  • Using Native Features of Mac OS X in Java Applications
    • Modifying the Default Settings for Hardware Graphics Acceleration
      • Advanced Options
      • Video Cards Designation Strings
    • Specifying a Name and Icon for Command-Line Applications
    • Using the Macintosh Menu Bar
      • The Window Menu
      • The Application Menu
    • More MRJ Handlers
    • Localizing Packaged Java applications on Mac OS X
    • QuickTime for Java
    • Java Core Audio Packages
    • Java Spelling and Speech Frameworks
    • JDirect
      • Human Interface Toolbox Synchronization
      • Debugging Features for JDirect
      • MethodClosureUPP Not Supported
      • JDirect Access to Bundles
    • Embedding Applets in Native Applications
    • Cocoa Java
  • Appendix A: Project Builder Tutorial
    • Building a Java Application With Project Builder
      • The Makeup of a Project Builder Project
      • Building a Java Project
      • Adding Your Source Files
      • Modifying the Application Parameters
    • Building Applets With Project Builder
  • Appendix B: MRJAppBuilder Tutorial
    • Building a Basic Application
    • Building a More Robust Application
    • Making Your Application More Mac-like
      • Java Properties Pane
      • Mac OS X Pane
  • Appendix C: Mac OS X Java System Properties
    • Java Virtual Machine Properties
    • Mac OS X Application Properties
      • Mac OS X…Specific Properties
  • Revision History
  • Glossary

---