You are currently viewing a snapshot of taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to, please file a bug.

Integration of the Java Platform with Mozilla


The Blackwood project has two primary goals:

  1. Integrate the Java platform with Mozilla so developers can extend the browser with components and plug-ins written in the Java programming language. Our mission is to put Java language support in Mozilla on a par with JavaScript support.
  2. Provide a vehicle for embedding the Mozilla Gecko rendering engine in applications written in the Java programming language.

Factoid:The Blackwood project got its name from the card game of bridge. Blackwood is a bidding convention used in bridge to signify to one's partner that the bidder has a strong hand and can do extremely well. Blackwood is a bridge between the Java platform and Mozilla, we hope to do a good job with Blackwood. Blackwood, bridge...get it? (hey, it could be worse: one of the other candidate names for the project was "Raymond Burr", as in the Raymond Burr that was inserted in a seemingly random fashion into the original Godzilla movie.

Blackwood Components

Blackwood consists of five sub-projects:

The first four of these projects were designed for extending the Java programming language's reach within the Mozilla web browser. The last project, Webclient, was designed instead to embed the Mozilla "Gecko" rendering engine inside a Java application. In other words, most Blackwood projects are for running Java code inside Mozilla; Webclient is for running Mozilla code inside Java applications.

These projects are described in the following paragraphs, and include links to their own web pages where appropriate.

For each Blackwood component, there are several concerns to be considered during design and implementation; these links point to text that describes the various concerns; another link points to documents the Blackwood group at Sun used for requirements gathering, design review, etc.

Open JVM Integration

(OJI has its own set of web pages on the Mozilla web site, at

The Open JVM Integration (OJI) facility, created by Mozilla engineers, was designed to let Mozilla work with different Java virtual machines (JVM's). Regardless of JVM vendor or version, if the virtual machine implements the required Open JVM Plug-in API, it can communicate with the Mozilla browser. When the browser encounters Java byte code (for example, via an APPLET, OBJECT, or EMBED tag, or directly via LiveConnect when JavaScript calls Java methods), the browser loads the byte code into the JVM for execution through the OJI API. The Open JVM Plug-in API is derived from the Netscape Plug-in API and makes heavy use of the Java Native Interface (JNI) to drive the JVM.


(BlackConnect has its own set of web pages on the Mozilla web site, at, complete with design, requirements analysis, API documentation, etc.)

BlackConnect's purpose is to give Java developers the ability to use Mozilla's XPCOM component model from Java code. There are two main use cases for BlackConnect:

  1. Developers who wish to call existing XPCOM components from their Java code, whether those XPCOM components were written in C++ or JavaScript.
  2. Developers who wish to create new, scriptable XPCOM components written in the Java programming language; these Java-implemented XPCOM components will be callable from C++ or JavaScript code just as any other scriptable XPCOM component is callable.

Before BlackConnect existed, XPCOM components could be written in C++ and JavaScript; Mozilla's XPConnect technology lets XPCOM components call each other, regardless of the language in which the component is written. BlackConnect's goal is to add Java as a suitable development language for XPCOM components.

One additional goal of BlackConnect is to support out-of-process calling of XPCOM components; in other words, if the browser is running in one process but the Java Virtual Machine (JVM) is running in a separate process (as happens with Mozilla on the Unix platforms), Java XPCOM components can communicate with Mozilla XPCOM components across the process boundary. Other possible uses of the remote BlackConnect bridge include writing an application to control the DOM of a separate Mozilla process, possibly by accessibility software.


(JavaDOM has its own set of web pages on the Mozilla web site, at

JavaDOM's goal is to give Java developers the ability to gain access to and manipulate the Document Object Model (DOM) of documents in the Mozilla browser. JavaDOM is usable from any Java code connected to Mozilla, whether it be an applet, Pluglet (see below), Webclient (see below), or Java called via LiveConnect (i.e., Java called from JavaScript on a web page with no APPLET/OBJECT/EMBED tag).

JavaDOM has undergone several iterations of development; the first iteration of the code consisted of hand-coded wrappers around the old Mozilla DOM classes. This deprecated implementation is still checked into the Mozilla source code repository but is no longer used or maintained by the Blackwood development group. The current implementation of JavaDOM takes advantage of the relatively new XPCDOM implementation in Mozilla (XPCDOM is a rewrite of the Mozilla DOM objects that use the XPIDL compiler and XPConnect technology, and are therefore scriptable just as any other XPCOM component is).

Access to Mozilla's content model through the Java DOM API opens up a whole new world of opportunities for components programed in the Java language. But it also creates a conduit that needs to be scrutinized and checked with regard to security. Concurrent access to the content model is another concern for which a policy is required, as the layout engine assumes a single thread of control.


(Pluglets has its own set of web pages on the Mozilla web site, at, complete with design, requirements analysis, API documentation, etc.)

Pluglets are Netscape plug-ins written in the Java programming language. The Pluglet API was created to address the prolbem of cross-platform development of Netscape plugins. Currently, Netscape plugins are developed in C or C++ and ported by hand to each operating system supported by the plugin vendor. For platforms that the plugin vendor does not directly support, there tends to be no port of that vendor's plugin. If, however, such a plugin were written using the Java platform, such a plugin would be available on any operating system platform that supports the appropriate JDK. In short, Pluglets are designed to bring the "write-once, run anywhere" approach to Netscape plugin development.


(Webclient has its own set of web pages on the Mozilla web site, at, complete with design, requirements analysis, API documentation, etc.)

Webclient originated as a project to extend the Java platform with a generic web browser API; ideally, this API would become a javax.browser package in the Java Developer's Kit (JDK). The idea is that Java developers who wished to use browsing capabilities in their applications (e.g., creating an HTML-based help system for their applications) could call the Webclient API's to gain browser functionality without worrying about the specific browser engine being used. Webclient code would do the work of finding a web browser and translating Webclient API calls into the API's provided by the browser being embedded.

Webclient's priority became to embed the Gecko rendering engine in a Java application, wrapped in the Webclient API's. This remains Webclient's main priority but not its only one. Webclient has also successfully wrapped the Internet Explorer HTML component, and we believe the same API's can be used to embed other browser components, including pure Java browsers such as the ICEStorm browser from Wind River Systems and the Escape browser from Espial.

Supporting Work For Blackwood's Java code: Java Utility Classes

These are a collection of handy classes for developing applications in Java. Classes include Assert (to be modified so as not to clash with assertions under development for JDK 1.4), Log, ParameterCheck, etc. More information on the utility classes is available at

Implementation Concerns


Security concerns arise in any application that allows code to be downloaded from the network and executed dynamically. This capability requires mechanisms for checking where the executable originates from, whether the source is trusted, and whether the user allows for foreign code to access certain resources on the client. The Java platform implements a security model that provides these mechanisms. The embedded application model can make direct use of this security model to protect the client from malicious applets and pluglets.

In the native application model, Java byte code can be treated much like JavaScript scripts. Thus, the same mechanisms that Mozilla uses to enforce access permissions and check the trustworthiness of scripts can be applied to applets and pluglets when they invoke native methods. The required interfaces will be implemented as part of the OJI facility.

Memory Management

The life-cycle of native objects in the Mozilla browser is managed through a reference counting protocol. Objects instantiated in a JVM, on the other hand, are reclaimed by a garbage collector when they become unreachable. Most of the facilities that make use of JNI will need to synchronize memory management across the language boundary. Once object ownership is clearly understood and specified, implementation should be straightforward, given the features like weak references and finalizers that the Java platform provides.


Concurrency is of special concern to users of the Java DOM API for Gecko. Due to the single-threaded application model employed by Gecko, access to the content model is not thread-safe. This is not a problem for components implementing listener interfaces which are always invoked by the layout engine's main thread. But it may be a problem for components like pluglets and applets which want to access the document, i.e. the container in which they are embedded, from another thread. Depending on the type of access (read-only, read-write) and the elements addressed within the document, there may or may not be a risk of interfering with another thread. Even if the latter scenario is rare, the developer needs to be aware of it. The Java DOM API implementation does not protect Gecko's content model from concurrent access. OJI, on the other hand, will provide for thread synchronization between applets, plugins and the layout engine.

Other modules within Mozilla like Necko (networking and protocol handling) employ multiple threads. For these modules, concurrency and compatibility needs to be further examined in the context of the embedded application model.


Templates for design and analysis

We offer here the templates used for Blackwood project development.

Original Document by Matthias Spycher. Updates by George Drapeau and Ed Burns.

Maintained by Ed Burns.