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.

BlackConnect Requirements Specification Version 1.1

(This document can be found at )

Review Status: reviewed

NOTE: This document specifies the ideal BlackConnect, not the current BlackConnect or even a future BlackConnect. That is, not everything in here will be implemented, but nothing will be implemented that isn't in here. In other words, the actual implementation will be a proper subset of what is specified here.

post feedback to with the subject BlackConnect spec

Table of Contents

  1. Introduction
    1. How the software fits into the larger system
    2. Overall description
    3. Software Project Constraints
  2. Detailed Problem Description
    1. Information flow
    2. Interface definition language
  3. Functional Description
  4. Behavioral Description
  5. Appendices
    1. Other Projects Similar to This One
    2. Differences from the Current Implementation
    3. References
    4. People who have worked on this document


    BlackConnect project aims to provide interoperability between Java and XPCOM components [1] . BlackConnect will allow users to implement components for Netscape6/Mozilla browser in Java and to use native Netscape6/Mozilla components in Java applications. In this document, the term "Browser" refers to the Netscape6/Mozilla browser.

    This document is the canonical source of requirements for the software. If new feature requests or changes are granted, the feature or change should be included in the spec prior to implementation. This document will be held under version after approval of initial revisions.

    How the software fits into the larger system

      Any Java developer may use BlackConnect for extending functionality of Browser. BlackConnect will be accessible in the following forms, and only the following forms:

      • As a set of shared libraries and a jar files.

      BlackConnect will be available in the following environments:

      Operating Systems

      • Windows NT 4.0 SP3 and greater

      • Solaris 2.7 and greater

      • linux

      • MacOS 8

      Java environments

      • JDK1.3

      [Basicly it would be available on all platforms Mozilla's XPCOM and JDK1.3 are available.]

    Overall description

      Why do we need BlackConnect?

      As mentioned in the introduction, BlackConnect project aims to provide ability to implement components for Browser in Java and to provide ability to use native Browser components in Java.

      Asking "why do we need BlackConnect?" actually we want to know "why do we want to use java in Browser ?. Why do we want to use native Browser's components in Java?. Why do not we want to use JNI for Java C++ interaction?"

      • Why to use Java implemented components

        • Some developers prefer to write in Java
        • Some components are simpler to implement in Java
          You can take a look at pluglets [2]

      • Why to use native Browser components in Java

        We might want to use Browser's rendering engine in java applications. For more information take a look at webclient [3]

      • Why do not use JNI for Java C++ interaction

        • It is tedious and error prone to write native/java wrappers for each and every component we want to use
        • It is simpler to distribute just a byte code. (in case of JNI usage native code should be provided as well


      • Easy to use
        It should be easy to implemented java components for Browser and to use native the Browser's components in java. The smaller BlackConnect API and requirements are the better.

      • Low overhead
        BlackConnect is a thin layer of software between the VM and the Browser. It will not cause major memory consumption outside of that already caused by the browser and the VM used for executing java implemented XPCOM components, or executing native components from java.

    Software Project Constraints

      Sun aims to complete principal development for BlackConnect project by the April 2001. After that point, Sun may continue to be the steward of BlackConnect development at, but may also pass the mantle on to some other entity.

Detailed Problem Description

    Information Flow

      Using BlackConnect should be transparent for the user. It should not matter for the user does he or she use java or native implemented component. In java we should invoke java method for java object (even though it implemented in C++ for example) The same should be true for C++

    Interface definition language

      Browser's XPIDL [4] is to be used for BlackConnect.

      Each XPCOM interface corresponds to a public Java interface of the same name. Only [xpcom] and [scriptable] [5] methods are to be used with BlackConnect

      Here is how to map XPIDL types to Java types:

      XPIDL Java Notes
      void void  
      boolean, PRBool boolean  
      octet, PRUint8 byte sign bit converted to unsigned's high bit
      char char  
      short, PRInt16 short  
      unsigned short, PRUint16, PRUnichar sign bit converted to unsigned's high bit
      long, PRInt32 int  
      unsigned long, PRUint32, nsrefcnt sign bit converted to unsigned's high bit
      long long, PRInt64 long  
      unsigned long long, PRUint64, PRTime sign bit converted to unsigned's high bit
      float float  
      double double  
      string java.lang.String  
      interface package.interface  
      array type type []  

      Here is how to map modifiers

      XPIDL Java Notes
      attribute Type Name Type getName() & void setName(Type)  
      readonly attribute Type Name Type getName()  
      out type, inout type type[]  
      in type type  
      const type public static final type  

      Here is how to map methods:

      XPIDL Java Notes
      void Method(in type var) void method(converted_type var) see types mapping
      void Method(out type var) void method(converted_type[] var)
      void Method([retval] out type var) converted_type method()
      type Method() converted_type method()
      [notxpcom] or [noscript] Method() not supported  

      Here is interface definition mapping:


          	     [scriptable, uuid(00000000-0000-0000-c000-000000000046)]
          	     interface nsISupports {


          	     package org.mozilla.xpcom;
          	     public interface nsISupports 
          		 public static final String IID =

      By default all interfaces are to be placed in org.mozilla.xpcom package.

      All classes we are using must implement nsISupports interface:

          	     [scriptable, uuid(00000000-0000-0000-c000-000000000046)]
          	     interface nsISupports {
          		 void QueryInterface(in nsIIDRef uuid, 
          				     [iid_is(uuid),retval] out nsQIResult result);
          		 [noscript, notxpcom] nsrefcnt AddRef();
          		 [noscript, notxpcom] nsrefcnt Release();
      Here is java interface for nsISupports:
          	     package org.mozilla.xpcom;
          	      * Interface nsISupports
          	      * IID: 0x00000000-0000-0000-c000-000000000046
          	      public interface nsISupports 
          		  public static final String IID =
          		  /* void QueryInterface (in nsIIDRef uuid, [iid_is (uuid), retval] out nsQIResult result); */
          		  public org.mozilla.xpcom.nsISupports queryInterface(org.mozilla.xpcom.IID uuid);
    Each interface should have public static final String IID equal to string representation of interface's iid.

    System Interface Description

      BlackConnect provides access to Browser components and services. But only few classes and interfaces are part of BlackConnect API.

      • org.mozilla.xpcom.ComponentManager provides access to Browser's nsIComponentManager [6]
        All interfaces nsIComponentManager depends on should be available in java. (But they are not part of the API)
        nsIComponentManager is responsible for dialing with components. It might be used for searching and initiating components for example.
      • org.mozilla.xpcom.nsISupports[7]
        each and every XPCOM component should implement nsISupports interface.
      • org.mozilla.xpcom.IID[8] For each and every XPCOM interface there is corresponding unique IID value.

      (Why are these classes and interfaces?

      Why is it necessary?

      It is necessary to have nsISupports because it is the root interface for all XPCOM components.
      It is necessary to have IID because nsISupports depends on it.
      It is necessary to have ComponentManager because it is the only hook to Netscape components we have.

      Why is it enough?

      We can implement new components using nsISupports and IID
      We can find and use existing XPCOM components using ComponentManager (components might be c++, java script or java implemented) )

Functional Description

    From the custom java components developer's perspective, BlackConnect usage should be transparent.

Behavioral Description

    Because BlackConnect reflects native implemented XPCOM objects to java general XPCOM documentation[9] is the best source to get information about XPCOM behavior.

    Here we are going to discuss: threading issues, exceptions and security model

    • Threading issues

      • In the XPCOM world, the majority of objects must be called on the thread they were created. BlackConnect should ensure this happens.

      • BlackConnect should provide thread consistency for Java.
        Let's say that there is a call from java to native and back to java again. The last call should happen in the same thread as the first one.

    • Exceptions
      XPCOM does not have exception model. It has error codes. BlackConnect should throw exceptions according to error codes and return error codes according to exceptions.
      Postponed for next version of BlackConnect

    • Security
      BlackConnect should provide jdk1.2 security model.
      Postponed for next version of BlackConnect