README
1INTRODUCTION:
2
3Inline::Java - Write Perl classes in Java.
4
5Inline::Java lets you write Perl classes in Java.
6
7Example:
8
9 use Inline Java => <<'END';
10 class JAxH {
11 public JAxH(String x){
12 System.out.println("Just Another " + x + " Hacker") ;
13 }
14 }
15 END
16
17 new JAxH('Inline') ;
18
19When run, this complete program prints:
20
21 Just Another Inline Hacker
22
23
24-------------------------------------------------------------------------------
25JNI (JAVA NATIVE INTERFACE) EXTENSION:
26
27Inline::Java now provides a JNI extension that allows you to load the Java
28virtual machine as shared object instead of running it as a separate process.
29
30See README.JNI for more information on building the JNI extension.
31
32
33-------------------------------------------------------------------------------
34INSTALLATION:
35
36- This module requires Inline version 0.44 or higher to be installed.
37- It also requires a version of the Java SDK 1.2 or higher to be
38 installed. You can get the latest Java SDK from Sun Microsystems
39 at http://java.sun.com. Follow the provided instructions in order
40 to install the Java SDK properly.
41
42To install Inline::Java do this:
43
44 % perl Makefile.PL J2SDK=/your/java/dir (see Note 1)
45 % make (see Note 2)
46 % make test (see Note 3, 4)
47 % make install
48
49You have to 'make install' before you can run it successfully.
50
51Note 1: Under Win95/98/Me, you may need to do 'cd ..' to get back to the
52your original directory after the command has completed. Also, you may set
53either the JAVA_HOME or the PERL_INLINE_JAVA_J2SDK environment variable to
54/your/java/dir instead of using the J2SDK Makefile.PL parameter.
55
56Note 2: Use nmake on Win32.
57
58Note 3: If you have built the JNI extension and want the test suite to use
59it, you will need to set the PERL_INLINE_JAVA_JNI environment variable to 1
60BEFORE running 'make test'.
61
62Note 4: When testing Inline::Java, it's always a good idea to run 'make test'
63twice. The first time you test the building and loading of a module, the
64second time you test loading of an already built module.
65
66
67-------------------------------------------------------------------------------
68FEATURES FOR THIS VERSION:
69
70Inline::Java version 0.52 is a minor upgrade that includes:
71 - Fixed JNI on cygwin (many thanks to Eric Rybski for the patch)
72 - Improved installation. 'make java' is now performed automatically.
73 - Fixed problems with disappearing exceptions by localizing $@.
74 - Other minor bug fixes.
75
76See CHANGES for a full change list.
77
78-------------------------------------------------------------------------------
79INFORMATION:
80
81= For more information on Inline::Java, see 'perldoc Inline::Java'.
82= For information about Inline, see 'perldoc Inline'.
83= For information on using Java, visit http://java.sun.org.
84
85Inline::Java's mailing list is inline@perl.org.
86To subscribe, send an email to inline-subscribe@perl.org.
87
88Please send questions and comments to Patrick LeBoutillier <patl@cpan.org>.
89
90Copyright (c) 2001-2005, Patrick LeBoutillier. All Rights Reserved.
91
README.JNI
1JNI (JAVA NATIVE INTERFACE) EXTENSION
2-------------------------------------
3Inline::Java now provides a JNI extension that allows you to load the Java
4virtual machine as shared object instead of running it as a separate process.
5
6
7PLATFORM AVAILABILITY
8---------------------
9The JNI extension is available on all supported platforms.
10
11The extension builds properly on all platform, but problems can occur when
12running it or tweaking maybe necessary on certain platforms. All help
13is welcome if anyone out there is a JNI expert.
14
15The reason why JNI is a bit complex under Linux/Solaris is because of
16threads. The Java Virtual Machine (libjvm.so) shared object uses native
17threads when embedded inside another program and that host program (in
18this case Perl) must link with the same threads library for everything
19to work properly. Starting with Perl 5.8, this works fine. With previous
20versions, you may get around rebuilding Perl by setting LD_PRELOAD.
21The only problems encountered where that when setting LD_PRELOAD before
22running the test suite, the LD_PRELOAD affects make as well and on Solaris
23some crashes were seen. Read more on this in the Solaris section below.
24
25Note: Make sure the directories listed at the end of the installation
26procedure are included in your LD_LIBRARY_PATH (PATH on Win32) environment
27variable. This JNI extension will not load properly the the Java shared
28objects cannot be located at runtime.
29
30
31OVERVIEW
32--------
33 +----------+------------+------------+
34 | JDK1.3.1 | J2SDK1.4.2 | J2SDK1.5.0 |
35+-------------+----------+------------+------------+
36| Win32 | ok | ok | ok |
37+-------------+----------+------------+------------+
38| cygwin | ok* | ok* | ok* |
39+-------------+----------+------------+------------+
40| Linux RH7.3 | ok* | ok* | ? |
41+-------------+----------+------------+------------+
42| Linux RH9.0 | ok* | ok* | ok |
43+-------------+----------+------------+------------+
44| Soloris 2.8 | ok* | ? | ? |
45+-------------+----------+------------+------------+
46* : Read below
47
48
49WIN32
50-----
51Java 2 SDK 1.3.1:
52 The JNI extension runs without problems.
53
54Java 2 SDK 1.4.2:
55 The JNI extension runs without problems.
56
57
58LINUX
59-----
60Java 2 SDK 1.3.1:
61 The JNI extension runs without problems with this Java 2 SDK, provided
62that you use Perl >= 5.8.0 or do one of the following:
63
641- Rebuild perl and add the libpthread library in front of all other
65 libraries (see the 'BUILDING PERL' section below). You should also
66 use your system's malloc (not perl's).
67 This is the recommended solution.
68
692- Add the proper version of libpthread.so to your LD_PRELOAD environment
70 variable. On my test system this was /lib/i686/libpthread.so.0.
71 This solution seems viable but thread related crashes/hang-ups have
72 been reported on some systems. If make crashes while running the test
73 suite, try running it like this:
74 % for i in `ls t/*.t` ; do perl -Mblib $i; done
75
76Also, make sure you use do not use 'classic' VM. This one should only
77be used with 'green threads', which don't seem to work with JNI. Use either
78the 'client' or the 'server' VMs.
79
80Java 2 SDK 1.4.2:
81 The same as Java 2 SDK 1.3.1 applies.
82
83
84SOLARIS
85-------
86Java 2 SDK 1.3.1:
87 The JNI extension runs without problems with this Java 2 SDK, provided
88that you use Perl >= 5.8.0 or do one of the following:
89
901- Rebuild perl and add the libthread library in front of all other
91 libraries (see the 'BUILDING PERL' section below). You should also
92 use gcc and your system's malloc (not perl's).
93 This is the recommended solution.
94
952- Add the proper version of libthread.so to your LD_PRELOAD environment
96 variable. On my test system this was /lib/libthread.so.
97 This solution seems viable but thread related crashes/hang-ups have
98 been reported on some systems. If make crashes while running the test
99 suite, try running it like this:
100 % for i in `ls t/*.t` ; do perl -Mblib $i; done
101
102
103CYGWIN
104------
105Java 2 SDK 1.3.1:
106 The JNI extension runs without problems.
107
108 PerlInterpreter:
109 Compiles but stand-alone (non-JNI initiated) Java interpreter locks
110 up when attempting to load the DLL. This is a known issue with
111 initialization of the cygwin1.dll from a non-cygwin DLL or EXE, which
112 has been "broken" since at least Cygwin 1.5.13.
113 A possible work around might be to build the PerlInterpreter against
114 a native Win32 Perl distribution with '-mno-cygwin' GCC compile flag,
115 although this means you would be using native Perl instead of Cygwin
116 Perl when using PerlInterpreter.
117
118Java 2 SDK 1.4.2:
119 The JNI extension runs without problems.
120
121 PerlInterpreter:
122 The same as Java 2 SDK 1.3.1 applies.
123
124 PerlNatives:
125 Compiles and runs fine in a JNI-initiated interpreter, but stand-alone
126 (non-JNI initiated) Java interpreter locks up when attempting to load
127 the DLL. This is a known issue with initialization of the
128 cygwin1.dll from a non-cygwin DLL or EXE, which has been "broken"
129 since at least Cygwin 1.5.13.
130
131Java 2 SDK 1.5.0:
132 The same as Java 2 SDK 1.4.2 applies.
133
134
135BUILDING PERL
136-------------
137Here's how to rebuild Perl (version < 5.8.0) to get the JNI extension to
138work properly:
139
140- Use all the defaults or whatever makes sense, but no threaded Perl
141 and no interpreter threads, i.e.:
142
143 Build a threading Perl? [n] n
144 Build Perl for multiplicity? [n] n
145
146- When asked what libraries to use, type -lthread (Solaris) or -lpthread
147 (Linux) and tack on whatever the default is at the end, i.e.:
148
149 What libraries to use? -> [-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lcrypt
150 -lutil] -lpthread -lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lcrypt -lutil
151 (under Linux it's -lpthread, but for Solaris it's -lthread)
152
153- Make sure that you do not use perl's own malloc, i.e.:
154
155 Do you wish to attempt to use the malloc that comes with perl5? -> [n] n
156
157
158RUNNING Inline::Java WITH THE JNI EXTENSION
159-------------------------------------------
160To run Inline::Java with the JNI extension, do one of the following:
161
162 - set the JNI configuration option to 1
163 - set the PERL_INLINE_JAVA_JNI environment variable to 1
164
165To run the test suite (make test) with the JNI extension you must use the
166PERL_INLINE_JAVA_JNI environment variable
167
168
169USING THE 'SHARED_JVM' MODE
170---------------------------
171Inline::Java 0.30 introduced a 'SHARED_JVM' mode that allows many clients
172to connect to the same Inline::Java Java server. The 'SHARED_JVM' mode is
173meant to be used with forking processes such as Apache with mod_perl. The
174'SHARED_JVM' mode does NOT work along with the JNI mode. In fact the author
175was not able to successfully fork the Java Virtual Machine under any
176circumstances.
177
178