Java Embedding Plugin Readme (3/2011)
I) What is the Java Embedding Plugin?
II) Requirements
III) Installing and Uninstalling the Binaries
IV) How Does the Java Embedding Plugin Work?
V) Debugging and Troubleshooting
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 :-)
