Java Embedding Plugin Readme (3/2011)

  1. What is the Java Embedding Plugin?
  2. Requirements
  3. Installing and Uninstalling the Binaries
  4. How Does the Java Embedding Plugin Work?
  5. Debugging and Troubleshooting
  6. Known Problems
  7. Building the Java Embedding Plugin
The Java Embedding Plugin was written by Steven Michaud (smichaud at pobox.com)

I) What is the Java Embedding Plugin?

The Java Embedding Plugin is a utility that allows other web browsers than Apple's Safari to use the most recent versions of Java on Mac OS X. When used together with an updated version of Mozilla's MRJ Plugin Carbon (included in this distribution), the Java Embedding Plugin's functionality is available to current releases of Firefox, Seamonkey and Camino -- and is in fact bundled with them. But in principle any web browser could use the Java Embedding Plugin to add support for Java 1.4.2, J2SE 5.0 and (where available) Java SE 6.

Apple's older Java versions (1.3.1 and earlier) have a documented API for use by browser developers -- the Java Embedding API, exported by the Java Embedding Framework. But until very recently Apple didn't provide a realistic way for non-WebKit browsers to support more recent Java versions. This was an unfortunate state of affairs, and I've done something about it. (For about a year Apple has been working on a port of Oracle/Sun's Java Plugin2 to OS X, which was included in their last few Java Updates for OS X 10.5.X and 10.6.X. This does support a standard API (the NPAPI), and does (in principle) work in all browsers. But, though the latest version is a vast improvement on previous ones, it isn't yet quite "release quality".)

II) Requirements

The current version (0.9.7.5) of the Java Embedding Plugin and the MRJ Plugin JEP requires Mac OS X 10.4.11 or higher. Older versions (0.9.6.5 and earlier) required Mac OS X 10.2.8 or higher. (Dropping support for Mac OS X 10.3.X and 10.2.8 made it possible to greatly simplify building the Java Embedding Plugin from source.)

As mentioned above, the Java Embedding Plugin has for the last few years been bundled with current Mac distributions of all the Mozilla browsers -- Firefox, Seamonkey and Camino. So if you're using one of these browsers, you don't need to install the Java Embedding Plugin. But you may wish to replace the bundled version of the Java Embedding Plugin with a more recent version (for which see the next section).

The Java Embedding Plugin currently isn't compatible with (and isn't bundled with) Firefox 4 (currently available only in pre-release builds). I'm working on a version of the JEP that will be compatible with Firefox 4.

III) Installing the Binaries

You don't need to do this unless you're replacing the bundled version of the Java Embedding Plugin (in a Mozilla browser) with some other version.

Note that these instructions have changed from those included in previous JEP versions' Readme files. This is because Apple made changes in their most recent Java Updates (on OS X 10.5.X and 10.6.X) that cause the previous instructions to no longer work properly.

For each of the browser binaries you wish to update:

  1. Control-click (or right-click) on the browser binary and choose "Show Package Contents".
  2. Browse to the Contents/MacOS/plugins folder and delete JavaEmbeddingPlugin.bundle and MRJPlugin.plugin.
  3. Drag copies of the new Java Embedding Plugin binaries to the Contents/MacOS/plugins folder.

Mozilla browsers always prefer the version of the Java Embedding Plugin in their Contents/MacOS/plugins folder to whatever version (if any) is available in /Library/Internet Plug-Ins.

The versions of JavaEmbeddingPlugin.bundle and MRJPlugin.plugin (in Contents/MacOS/plugins or /Library/Internet Plug-Ins) need to match each other. To see either binary's version, control-click (or right-click) on it and choose "Get Info".

IV) How Does the Java Embedding Plugin Work?

The Java Embedding Plugin works at a low level -- the same as that of Apple's old Java Embedding Framework (which still provides Java 1.3.1 functionality on OS X Tiger) and the "OJI Plugin" that Sun makes available with its Java Plugin on other platforms (but which Apple chose not to port). Basically, it uses the (C-based) Java Native Interface to bootstrap the JVM, then uses Java code to create an environment that can host an applet.

The Java Embedding Plugin uses many undocumented APIs in the AppKit Framework and in Apple's Java Virtual Machine (whose code is in the JavaVM Framework). I make no apologies for this -- without it my work would have been impossible. But it means that the Java Embedding Plugin is more likely to break on future releases of OS X and of Apple's JVM than an app that uses only published APIs.

V) Debugging and Troubleshooting

The Java Embedding Plugin is a beta app that heavily depends on undocumented APIs. So there will be problems, and I need your help to fix them. But the Java Embedding Plugin won't suddenly become the cause of all the problems on your computer :-) So you need to work a bit to winnow out the problems that have other causes. Fortunately this is very easy.

If you have a problem with an applet in one of the browsers that the Java Embedding Plugin currently supports (Firefox, Camino or Seamonkey), first look in the following file in your home directory -- ~/Library/Logs/Java Console.log. This file is created by the MRJ Plugin JEP, and contains a record of your most recent Java "session" -- including any Java exceptions that may have occurred. Another way to view Java exceptions is to run the Java Control Panel (Java 1.4.X Plugin Settings in the /Applications/Utilities/Java folder, or Java Preferences in the /Applications/Utilities/Java/J2SE 5.0 or /Applications/Utilities/Java folder) and choose "Show console" (though this will cause less information to be written to Java Console.log).

The Java Embedding Plugin logs to the Java Console whenever it creates an applet (each entry will contain a timestamp and (at least) the text JEP creating applet [name]). If your console log doesn't contain one or more recent entries for applets created, then either they weren't loaded or the current page doesn't contain any applets.

If it's really an applet that you're having trouble with, try the same applet in the other supported browsers and in Safari, and (if possible) on different platforms (e.g. in some browser on Linux or Windows).

An applet problem that occurs in Safari, Firefox, Camino and Seamonkey, but not on other platforms using the same version of the Sun's Java Plugin, is likely to be a problem with Apple's implementation of Sun's JVM. A problem that also occurs on other platforms using Sun's Java Plugin is likely to be a problem with Sun's JVM ... or even possibly with your applet :-)

If possible, try the applet on different versions of Mac OS X. I've seen some Apple-specific problems (i.e. ones not found in similar versions of Sun's JVM on other platforms) disappear with the change from Mac OS X 10.3.X to 10.4.X, or from 10.4.X to 10.5.X.

If the problem isn't associated with a Java applet, it's likely not to have anything to do with Java or the Java Embedding Plugin :-)