gecko-dev/java/xpcom/old

Java Bridge to XPCOM
====================

This directory contains the beginnings of the Java Bridge to XPCOM.
For now it is disconnected from the main Mozilla build, because as yet 
it is good for no more than a few demo and test programs, and because
Java compilation on Unix and Linux doesn't work quite right (as of 
Aug 13, 1999).

The source is divided into four directories

	classes
		Java source files
	src
		Native code (C++/C) for Java classes and stub support
	test
		Test code, including a dummy XPCOM component
	tools
		Support tools:

		genproxy -- Generates Java source for a proxy class 
			to an XPCOM object.  (Eventually will
			generate bytecodes and interfaces.)


Build
-----

Currently only UNIX/Linux builds are supported (mainly because it's my 
platform of choice).  Windows builds should not be too much more
difficult, and 

1. Make sure MOZILLA_FIVE_HOME is set to <mozilla-source-dir>/dist/bin, 
   and that JDKHOME indicates a valid JDK 1.2 installation.

   *IMPORTANT*: remove the jni.h, jni_md.h, and jri.h in mozilla/dist/bin,
                before compiling native code.  Otherwise, the header 
                mismatch will cause crashes in JNI code.

2. Insure that the following are in your LD_LIBRARY_PATH:

	$MOZILLA_FIVE_HOME
	$MOZILLA_FIVE_HOME/../lib
	mozilla/java/xpcom/test (or "." if you run in that directory)
	mozilla/java/xpcom/src (or "../src" if you run in "test")

3. In mozilla/java/xpcom, execute 

	../../build/autoconf/update-makefile.sh

   if necessary, to generate a Makefile, and then

	gmake JAVAC="javac -g -d $MOZILLA_FIVE_HOME/../classes"

   This is to get around bugs in Java compilation.   

4. Change directories to mozilla/java/xpcom/test

5. Execute

	gmake -f Makefile.test

   This has the side effect of creating JSISample.xpt in the main 
   Mozilla components directory; all other libraries, executables, and
   Java class files reside in the test directory.


Tests
-----

Both tests use the JSSample component, whose methods do nothing more
than print out the in and out arguments, and perhaps perform a simple
operation.

xptest

	This program takes the name of a JSSample method and a number
	of "in" parameters (coerced from strings to the expected
	data types), executes the method, and returns.  It is mainly 
	useful to test whether the "xpjava" native functions still 
	work correctly, independently of the JVM.

	Sample invocation:

		./xptest AddTwoInts 1 1

	Output:
		Starting ...
		Initializing XPCOM
		<some debugging messages>
		Registering Allocator
		Getting InterfaceInfoManager
		Registering Sample Factory
		AddTwoInts:
			0:  type = 2, in
			1:  type = 2, in
			2:  type = 2, out, retval
		Consuming 1
		Consuming 1
		Arguments are: 
		0) 1 : type 2, ptr=(nil)
		1) 1 : type 2, ptr=(nil)
		2) 7566446 : type 2, ptr=0x804fae8, data
		Calling XPTC_InvokeByIndex( 0x80932d0, 23, 3, 0x804fac8)
		Results are: 
		0) 1 : type 2, ptr=(nil)
		1) 1 : type 2, ptr=(nil)
		2) 2 : type 2, ptr=0x804fae8, data


XPCTest.main()

	This is a Java version of xptest.  Unlike xptest, each
	non-String argument to the method must be preceded by a flag
	indicating its type, out parameters require a "placeholder
	flag":

		-c:	char
		-b:	byte
		-s:	short
		-i:	int
		-j, -l:	long
		-f:	float
		-d:	double
		-z:	boolean
		-r:	placeholder for retval
		-0:	placeholder for out param (equiv. to -r)

	If the "command" argument is a number, XPCTest invokes the
	XPCOM method with that offset.

	Sample invocation:

		java -native XPCTest AddTwoInts -i 1 -i 1 -r

	Output:

		Initializing XPCOM
		Registering Allocator
		Getting InterfaceInfoManager
		Command: AddTwoInts, arguments: [1, 1, null]
		Results: [1, 1, 2]

	Notes:

	1. You must run native threads; Mozilla loads the native 
	   thread library, and the JVM will panic if it has to 
	   load both native and green threads.

	2. Because of the way the JDK links shared libraries, 
	   you must have a valid mozilla/dist/bin/component.reg;
	   otherwise, XPCOM will not bootstrap correctly.
	   Note that "apprunner" and "xptest" will create one.
	   Future versions will fix this limitation.