Switching Java versions on a Mac (setting JAVA_HOME and using Java 6 Revisited)

Switching Java versions from say, Java 5 to Java 6 or back is (probably) not intuitive for the new Mac user. This blog will point out a few things you might not expect coming from a Windows or Linux environment.  This article is also intended to correct many other (now incorrect) articles attempting to help with the same issue.  These articles were valid until some very recent updates to Java were released, specifically the Leopard 10.5.7 Java Update 4 (referred to as UPD4 from here on).

If you just want to fix it quick, because something broke since you installed UPD4, then see the Bottom Line below.

For those that want to know a little bit more why your environment broke and the Java Preferences app doesn’t seem to do what you think it should, please read on.

Some Background

Here are a few concepts that need to be understood about the Mac/Java environment before you go off and just try to set JAVA_HOME in your favorite shell environment to some other location.  Even though you might get away with this for a little while, it will bite you eventually for various reasons.  Mac OSX 10.5 comes with Java installed by default and includes multiple versions.  With UPD4 (and some earlier updates), Java 6 is installed as well, but it is not set as the default JDK.

• The Mac includes a Java Preferences App (Applications -> Utilities -> Java Preferences) that lets you set the preferred order of Java versions to run when you launch a Java application or applet within a browser.  This article shows you how to use the Java Preferences App, but the methods presented for switching Java versions is out of date.
• The Mac has a couple different ways to set environment variables that are accessible to Java programs
  • Within your shell using normal environment variables, exactly as you would expect from Linux
  • Using a ‘plist’ (preferences list) file, specifically ~/.MacOSX/environment.plist
• Just setting JAVA_HOME in your shell can cause unexpected behavior if you don’t know how Apple installs Java on the Mac
  • Apple uses several soft links to provide a “flexible” way to refer to a particular Java version and they recently changed how this works.

If you have tried to find where Apple stores all these versions, you may have discovered the /System/Library/Frameworks/JavaVM.Framework directory.  Under that is a directory called Versions and under that is a slew of versions, links, and a suspicious directory called A.  This directory holds (among other things) a bunch of shared command line tools under the Commands subdirectory (like java, javac, etc.) that are available to user programs.  These versions are supposed to pick the top version of Java from your Java Preferences app settings.  If you have JAVA_HOME set somewhere else, then all bets are off.

BTW, there is a lot of debate as to whether you should or should not manipulate these links manually.  After my research, I am a now a strong proponent of using the recommendations of Apple and tools that are provided.  The problem is finding their recommendations.  There are several articles on switching Java versions on the Mac and where you should point JAVA_HOME.  Just google any of the following phrases and you’ll see what I mean:

• switch java version on mac
• switch jdk version on mac
• setting JAVA_HOME on mac

Even Apples’ own java development support site has it wrong now, according to my latest findings.  They are not immune to having outdated documentation and I have found lots of examples that point to information that is roughly 2 years out of date.

The most informative find I came across that helped me understand the issue better was a thread on lists.apple.com and can be summarized as follows.

• There is a mess with how Java versions are installed and Apple’s approach to this is changing
• Apple needs to maintain backwards compatibility, which means the mess will be with us for awhile
• There is a new program to help us (/usr/libexec/java_home) and you should read up on it by doing a “man java_home”
  • java_home appears to be a very nice addition and can help you pick the best version of java for a program given some hints on version level (1.4, 1.5+, 1.6*, etc.)  as well as architecture (i386, x86_64, ppc) and data model (32 bit vs 64 bit)
• Use the Java Preferences App to set an appropriate “default” Java runtime for your environment
• Do NOT muck with the soft links (or anything under the /System hierarchy) manually
• Use the java_home program in shell scripts to help you set an appropriate Java runtime for standalone programs – e.g. eclipse, ant, maven, your own java programs, etc.

Bottom Line

Here is the approach I now take for switching Java versions, but still allowing other programs to pick there favorite JDK:

• do NOT set JAVA_HOME using the plist method – it’s not dynamic enough
• use the Java Preferences app to switch the “default” Java version used for those programs that don’t care
• (optional) set JAVA_HOME in your shell startup script (e.g. ~/.bashrc or equivalent) using the new /usr/libexec/java_home program – it will set the value to the one you chose in the Java Preferences app
  • NOTE: if you change the Java Preferences ordering, then you need to reset the JAVA_HOME variable in all open shell sessions to reflect that change.  You can simply run the following command (if using bash)
    • export JAVA_HOME=`/usr/libexec/java_home`
• set JAVA_HOME specifically for each standalone java program in the shell script that runs the program.
  • Recommended approach: use the java_home program to help you decide which version is “best” by supplying it hints (version level, architecture, or data model)
    • export JAVA_HOME=`/usr/libexec/java_home -v 1.5+ -d32`
  • Optional approach is to set JAVA_HOME directly to one of the frameworks you know works.  So, if you want to run a program with Java 5, then do the following:
    • export JAVA_HOME=/System/Library/Frameworks/JavaVM.Framework/Versions/1.5/Home

References (examples I read in my research)

• MOST HELPFUL thread to understand the issues caused by UPD4 (read from the bottom up)
• Macosxhints.com (dated, for your amusement only)
  • A suggestion and debate (read the comments) about manipulating the soft links “manually” to point to a particular version.
• Java on Mac OS X on about.com (not quite as dated and somewhat helpful to the newbie Java developer on Mac)
  • NOTE: the reference to the location of the Java Preferences App is wrong in this article
• Apple.com (much of this is dated, some is useful, read with caution)
  • Getting Started with Java
  • Java Development Overview
    • NOTE: this article mentions setting JAVA_HOME to /Library/Java/Home/ and this does NOT work for me after UPD4
  • Tech Note re: UPD4 (not directly related to this blog, but might be useful to some)
• Switch JDKs on Mac on blogs.sun.com (talks about Java Preferences App and the plist file.  But, I’m not recommending you use the plist file for setting JAVA_HOME)

Hope this helps!