You are currently viewing a snapshot of www.mozilla.org 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 www.mozilla.org, please file a bug.

BlackConnect Requirements Specification Version 1.1

(This document can be found at http://www.mozilla.org/projects/blackwood/connect/RequirementsSpec.html )

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 netscape.public.mozilla.java with the subject BlackConnect spec

Introduction
Detailed Problem Description
1. Information flow
2. Interface definition language
Functional Description
Behavioral Description
Appendices

Introduction

XPCOM components

^[1]

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

Goals

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 mozilla.org, 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

XPIDL

^[4]

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

wchar

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

wstring

interface package.interface

array type type []

XPIDL	Java	Notes
void	void
boolean, PRBool	boolean
octet, PRUint8	byte	sign bit converted to unsigned's high bit
char	char
wchar
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
wstring
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

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

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:

XPIDL

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

Java

    	     package org.mozilla.xpcom;
    
    	     public interface nsISupports 
    	     {
    		 public static final String IID =
    			"00000000-0000-0000-c000-000000000046";
    	     }

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();
    	     };

    	     package org.mozilla.xpcom;
    
    	     /**
    	      * Interface nsISupports
    	      *
    	      * IID: 0x00000000-0000-0000-c000-000000000046
    	      */
    
    	      public interface nsISupports 
    	      {
    		  public static final String IID =
    			 "00000000-0000-0000-c000-000000000046";
    
    
    		  /* void QueryInterface (in nsIIDRef uuid, [iid_is (uuid), retval] out nsQIResult result); */
    		  public org.mozilla.xpcom.nsISupports queryInterface(org.mozilla.xpcom.IID uuid);
    	      }

public static final String IID

System Interface Description

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

general XPCOM documentation

^[9]

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

Appendices

Other Bridges accessible for Java or for Netscape6/Mozilla browser

Threading issues
Exceptions
Igor Kushnirskiy

Mozilla