JNI (JAVA NATIVE INTERFACE) EXTENSION
-------------------------------------
Inline::Java now provides a JNI extension that allows you to load the Java 
virtual machine as shared object instead of running it as a separate process. 


PLATFORM AVAILABILITY
---------------------
The JNI extension is available on all supported platforms.

The extension builds properly on all platform, but problems can occur when
running it or tweaking maybe necessary on certain platforms. All help
is welcome if anyone out there is a JNI expert.

The reason why JNI is a bit complex under Linux/Solaris is because of 
threads. The Java Virtual Machine (libjvm.so) shared object uses native 
threads when embedded inside another program and that host program (in
this case Perl) must link with the same threads library for everything 
to work properly. Luckily by setting LD_PRELOAD we can get around 
rebuilding Perl. The only problems encountered where that when setting
LD_PRELOAD before running the test suite, the LD_PRELOAD affects make
as well and on Solaris some crashes were seen. Read more on this in the 
Solaris section below.

Note: Make sure the directories listed at the end of the installation
procedure are included in your LD_LIBRARY_PATH (PATH on Win32) environment
variable. This JNI extension will not load properly the the Java shared 
objects cannot be located at runtime.


OVERVIEW
--------
              +----------+----------+
              | JDK1.2.2 | JDK1.3.1 |
+-------------+----------+----------+
| Win32		  |    ok    |    ok    | 
+-------------+----------+----------+
| Linux RH7.1 |  not ok* |    ok*   |
+-------------+----------+----------+
| Soloris 2.8 |    ok*   |    ok*   |
+-------------+----------+----------+
*: Read below


WIN32
-----
Java 2 SDK 1.2.2:
	The JNI extension runs without problems.

Java 2 SDK 1.3.1:
	The JNI extension runs without problems.


LINUX
-----
Java 2 SDK 1.2.2:
    The JNI extension has not been run successfully on Linux with this 
Java 2 SDK. Hanging occurs when the process ends. This issue seems to 
be related to the main thread waiting for other threads to terminate.

Java 2 SDK 1.3.1:
    The JNI extension runs without problems with this Java 2 SDK, provided
that you add the proper version of libpthread.so to your LD_PRELOAD 
environment variable. On my test system this was /lib/i686/libpthread.so.0
You can also rebuild Perl and add that library in front of all others.
    Also, make sure you use do not use 'classic' VM. This one should only
be used with 'green threads', which don't work with JNI. Use either the 
'client' or the 'server' VMs.

	
SOLARIS
-------
Java 2 SDK 1.2.2:
    The JNI extension has been run successfully with this Java 2 SDK,
provided that you add the proper version of libthread.so to your LD_PRELOAD 
environment variable. On my test system this was /lib/libthread.so. You can 
also rebuild Perl and add that library in front of all others. On some 
occasions thread related crashes have been seen while running the test suite,
but they seemed to come from make and not from the test suite per se.
Running the test suite like this:
    % for i in `ls t/*.t` ; do perl -Mblib $i; done
was fine.

Java 2 SDK 1.3.1:
    The JNI extension has been run successfully with this Java 2 SDK,
provided that you add the proper version of libthread.so to your LD_PRELOAD 
environment variable. On my test system this was /lib/libthread.so. You can 
also rebuild Perl and add that library in front of all others. On some 
occasions thread related crashes have been seen while running the test suite,
but they seemed to come from make and not from the test suite per se.
Running the test suite like this:
    % for i in `ls t/*.t` ; do perl -Mblib $i; done
was fine.


Note: These results where achieved with Perl 5.6.1 complied with gcc 
and using the native malloc.


RUNNING Inline::Java WITH THE JNI EXTENSION
-------------------------------------------
To run Inline::Java with the JNI extension, do one of the following:

   - set the JNI configuration option to 1
   - set the PERL_INLINE_JAVA_JNI environment variable to 1

To run the test suite (make test) with the JNI extension you must use the 
PERL_INLINE_JAVA_JNI environment variable


USING THE 'SHARED_JVM' MODE
---------------------------
Inline::Java 0.30 introduced a 'SHARED_JVM' mode that allows many clients 
to connect to the same Inline::Java Java server. The 'SHARED_JVM' mode is 
meant to be used with forking processes such as Apache with mod_perl. The 
'SHARED_JVM' mode does NOT work along with the JNI mode. In fact the author 
was not able to successfully fork the Java Virtual Machine under any 
circumstances.

