This is an automated email from the git hooks/post-receive script. js pushed a commit to tag 0.55 in repository libinline-java-perl.
commit 435c132be9675229a76b0d8788c58d6a6eedb497 Author: Patrick LeBoutillier <p...@cpan.org> Date: Wed Jan 16 13:31:14 2002 +0000 Updated documentation. --- Java.pod | 1882 +++++++++++++++++++++++++++++++----------------------------- README | 34 +- README.JNI | 63 +- 3 files changed, 1011 insertions(+), 968 deletions(-) diff --git a/Java.pod b/Java.pod index cd1231d..2d7cdc1 100644 --- a/Java.pod +++ b/Java.pod @@ -1,902 +1,980 @@ -=head1 NAME - -Inline::Java - Write Perl classes in Java. - -=head1 SYNOPSIS - -=for comment - - my $alu = new alu() ; - print "9 + 16 = ", $alu->add(9, 16), "\n"; - print "9 - 16 = ", $alu->subtract(9, 16), "\n"; - - use Inline Java => <<'END_OF_JAVA_CODE'; - class alu { - public alu(){ - } - - public int add(int i, int j){ - return i + j ; - } - - public int subtract(int i, int j){ - return i - j ; - } - } - END_OF_JAVA_CODE - -=for comment - -=head1 WARNING - -THIS IS ALPHA SOFTWARE. It is incomplete and possibly unreliable. -It is also possible that some elements of the interface (API) will -change in future releases. - Z<> - - -=head1 DESCRIPTION - -The C<Inline::Java> module allows you to put Java source code -directly "inline" in a Perl script or module. A Java compiler -is launched and the Java code is compiled. Then Perl asks the -Java classes what public methods have been defined. These classes -and methods are available to the Perl program as if they had been -written in Perl. - -The process of interrogating the Java classes for public methods -occurs the first time you run your Java code. The namespace is -cached, and subsequent calls use the cached version. - Z<> - - -=head1 USING THE Inline::Java MODULE - -C<Inline::Java> is driven by fundamentally the same idea as other -C<Inline> language modules, like C<Inline::C> or C<Inline::CPP>. -Because Java is both compiled and interpreted, the method of getting -your code is different, but overall, using C<Inline::Java> is very similar -to any other C<Inline> language module. - -This section will explain the different ways to C<use> Inline::Java. -For more details on C<Inline>, see 'perldoc Inline'. - -B<Basic Usage> - -The most basic form for using C<Inline::Java> is: - - use Inline Java => 'Java source code' ; - -Of course, you can use Perl's "here document" style of quoting to make -the code slightly easier to read: - - use Inline Java => <<'END'; - - Java source code goes here. - - END - -The source code can also be specified as a filename, a subroutine -reference (sub routine should return source code), or an array -reference (array contains lines of source code). This information -is detailed in 'perldoc Inline'. - -In order for C<Inline::Java> to function properly, it needs to know -where to find the Java compiler (javac) and the Java Runtime (java) -on your machine. This is done using one of the following techniques: - - - set the BIN configuration option to the correct directory - - set the PERL_INLINE_JAVA_BIN environment variable to the correct - directory - - put the correct directory in your PATH environment variable - - -=head1 CONFIGURATION OPTIONS - -There are a number of configuration options that dictate the -behavior of C<Inline::Java>: - - BIN: - Specifies the path to your Java binaries. - Ex: BIN => 'my/java/bin/path' - Note: This configuration option only has an effect on the first - 'use Inline Java' call inside a Perl script, since all other calls - make use of the same JVM. However, you can use it if you want to - change which 'javac' executable is used for subsequent calls. - - PORT: - Specifies the starting port number for the server. If many - C<Inline::Java> blocks are declared, the port number is - incremented each time. - Default is 7890. - Ex: PORT => 4567 - Note: This configuration option only has an effect on the first - 'use Inline Java' call inside a Perl script, since all other calls - make use of the same JVM. - - STARTUP_DELAY: - Specifies the maximum number of seconds that the Perl script - will try to connect to the Java server. In other this is the - delay that Perl gives to the Java server to start. - Default is 15 seconds. - Ex: STARTUP_DELAY => 20 - Note: This configuration option only has an effect on the first - 'use Inline Java' call inside a Perl script, since all other calls - make use of the same JVM. - - CLASSPATH: - Adds the specified CLASSPATH to the environment CLASSPATH. - Ex: CLASSPATH => '/my/other/java/classses' - Note: This configuration option only has an effect on the first - 'use Inline Java' call inside a Perl script, since all other calls - make use of the same JVM. - - JNI: - Toggles the execution mode. The default is to use the client/server - mode. To use the JNI extension (you must have built it at install - time though. See README and README.JNI for more information), set - JNI to 1. - Ex: JNI => 1 - Note: This can also be set globally by setting the - PERL_INLINE_JAVA_JNI environment variable to 1. - Note: This configuration option only has an effect on the first - 'use Inline Java' call inside a Perl script, since all other calls - make use of the same JVM. - - SHARED_JVM: - This mode enables mutiple processes to share the same JVM. It was - created mainly in order to be able to use C<Inline::Java> under - mod_perl. - Ex: SHARED_JVM => 1 - Note: This configuration option only has an effect on the first - 'use Inline Java' call inside a Perl script, since all other calls - make use of the same JVM. - - DEBUG: - Enables debugging info - Ex: DEBUG => 1 - - WARN_METHOD_SELECT: - Throws a warning when C<Inline::Java> has to 'choose' between - different method signatures. The warning states the possible - choices and the signature chosen. - Ex: WARN_METHOD_SELECT => 1 - - STUDY: - Takes an array of Java classes that you wish to have - C<Inline::Java> learn about so that you can use them inside Perl. - Ex: STUDY => ['java.lang.HashMap', 'my.class'] ; - - AUTOSTUDY: - Makes C<Inline::Java> automatically study unknown classes it - encounters. - Ex: STUDY => ['java.lang.HashMap', 'my.class'] ; - - -=head1 CLASSES AND OBJECTS - -Because Java is object oriented, any interface between Perl and Java -needs to support Java classes adequately. - -Example: - -=for comment - - use Inline Java => <<'END'; - class Foo { - String data = "data" ; - static String sdata = "static data" ; - - public Foo() { - System.out.println("new Foo object being created") ; - } - - public String get_data(){ - return data ; - } - - public static String get_static_data(){ - return sdata ; - } - - public void set_data(String d){ - data = d ; - } - } - END - - my $obj = new Foo ; - print $obj->get_data() . "\n" ; - $obj->set_data("new data") ; - print $obj->get_data() . "\n" ; - -=for comment - -The output from this program is: - - new Foo object being created - data - new data - -C<Inline::Java> created a new namespace called C<main::Foo> and -created the following functions: - - sub main::Foo::new { ... } - sub main::Foo::Foo { ... } - sub main::Foo::get_data { ... } - sub main::Foo::get_sdata { ... } - sub main::Foo::set_data { ... } - sub main::Foo::DESTROY { ... } - -Note that only the public methods are exported to Perl. -Note also that the class itself is not public. With -C<Inline::Java> you cannot create public classes because Java -requires that they be defined in a .java file of the same -name (C<Inline::Java> can't work this way). - -Inner classes are also supported, you simply need to supply a reference -to an outer class object as the first parameter of the constructor: - -=for comment - - use Inline Java => <<'END'; - class Foo1 { - public Foo1() { - } - - public class Bar { - public Bar() { - } - } - } - END - - my $obj = new Foo1() ; - my $obj2 = new Foo1::Bar($obj) ; - -=for comment - -=head1 METHODS - -In the previous example we have seen how to call a method. You can also -call static methods in the following manner: - - print Foo->get_sdata() . "\n" ; - # or - my $obj = new Foo() ; - print $obj->get_sdata() . "\n" ; - -both of these will print: - - static data - -You can pass any kind of Perl scalar or any Java object to a method. It -will be automatically converted to the correct type: - -=for comment - - use Inline Java => <<'END'; - class Foo2_arg { - public Foo2_arg(){ - } - } - class Foo2 { - public Foo2(int i, String j, Foo2_arg k) { - // ... - } - } - END - - my $obj = new Foo2_arg() ; - my $obj2 = new Foo2(5, "toto", $obj) ; - -=for comment - -will work fine. These objects can be of any type, even if these types -are not known to C<Inline::Java>. This is also true for return types: - -=for comment - - use Inline Java => <<'END'; - import java.util.* ; - - class Foo3 { - public Foo3() { - } - - public HashMap get_hash(){ - return new HashMap() ; - } - - public void do_stuff_to_hash(HashMap h){ - // ... - } - } - END - - my $obj = new Foo3() ; - my $h = $obj->get_hash() ; - $obj->do_stuff_to_hash($h) ; - -=for comment - -Objects of types unknown to Perl can exist in the Perl space, you just -can't call any of their methods. - Z<> - - -=head1 MEMBER VARIABLES - -You can also access all public member variables (static or not) from Perl. -As with method arguments, the types of these variables does not need to -be known to Perl: - -=for comment - - use Inline Java => <<'END'; - import java.util.* ; - - class Foo4 { - public int i ; - public static HashMap hm ; - - public Foo4() { - } - } - END - - my $obj = new Foo4() ; - $obj->{i} = 2 ; - my $hm1 = $obj->{hm} ; # instance way - my $hm2 = $Foo4::hm ; # static way - -=for comment - -Note: Watch out for typos when accessing members in the static fashion, -'use strict' will not catch them since they have a package name... - Z<> - - -=head1 ARRAYS - -You can also send and receive arrays. This is done by using Perl lists: - -=for comment - - use Inline Java => <<'END'; - import java.util.* ; - - class Foo5 { - public int i[] = {5, 6, 7} ; - - public Foo5() { - } - - public String [] f(String a[]){ - return a ; - } - - public String [][] f(String a[][]){ - return a ; - } - } - END - - my $obj = new Foo5() ; - my $i_2 = $obj->{i}->[2] ; # 7 - my $a1 = $obj->f(["a", "b", "c"]) ; # String [] - - my $a2 = $obj->f([ - ["00", "01"], - ["10", "11"], - ]) ; # String [][] - print "$a2->[1]->[0]\n" ; # "10" - -=for comment - -=head1 TYPE CASTING - -Sometimes when a class as many signatures for the same method, -C<Inline::Java> will have to select one of the signatures based on -the arguments that are passed: - -=for comment - - use Inline Java => <<'END'; - class Foo6 { - public Foo6() { - } - - public void f(int i){ - } - - public void f(char c){ - } - } - END - - my $obj = new Foo6() ; - $obj->f('5') ; - -=for comment - -In this case, C<Inline::Java> will call f(int i), because '5' is an integer. -But '5' is a valid char as well. So to force the call of f(char c), do the -following: - - use Inline::Java qw(cast) ; - $obj->f(cast('char', '5')) ; - # or - $obj->f(Inline::Java::cast('char', '5')) ; - -The cast function forces the selection of the matching signature. Note that -the cast must match the argument type exactly. Casting to a class that -extends the argument type will not work. - -Another case where type casting is need is when one wants to pass an array -as a java.lang.Object: - - use Inline Java => <<'END'; - class Foo7 { - public Object o ; - int a[] = {1, 2, 3} ; - - public Foo7() { - } - } - END - - my $obj = new Foo7() ; - $obj->{o} = [1, 2, 3] ; # No! - -The reason why this will not work is simple. When C<Inline::Java> sees an -array, it checks the Java type you are trying to match it against to validate -the construction of your Perl list. But in this case, it can't validate -the array because you're assigning it to an Object. You must use the 3 -parameter version of the cast function to do this: - - $obj->{o} = Inline::Java::cast( - "java.lang.Object", - [1, 2, 3], - "[Ljava.lang.String;") ; - -This tells C<Inline::Java> to validate your Perl list as a String [], and -then cast it as an Object. - -Here is how to construct the array type representations: - - [<type> -> 1 dimensional <type> array - [[<type> -> 2 dimensional <type> array - ... - - where <type>is one of: - B byte S short I int J long - F float D double C char Z boolean - - L<class>; array of <class> objects - -This is described in more detail in most Java books that talk about -reflection. - -But you only need to do this if you have a Perl list. If you already have a -Java array reference obtained from elsewhere, you don't even need to cast: - - $obj->{o} = $obj->{a} ; - - -=head1 EXCEPTIONS - -You can now (as of 0.31) catch exceptions as objects when they are thrown -from Java. To do this you use the regular Perl exception tools: eval and -$@. A helper function named 'caught' is provided to help determine the -type of the exception. Here is a example of a typical use: - -=for comment - - use Inline Java => <<'END'; - import java.util.* ; - - class Foo8 { - public Foo8(boolean t) throws Exception { - if (t){ - throw new Exception("ouch!") ; - } - } - } - END - - use Inline::Java qw(caught) ; - - eval { - my $obj = new Foo8(1) ; - } ; - if ($@){ - if (caught("java.lang.Exception")){ - my $msg = $@->getMessage() ; # "ouch!" - print "$msg\n" ; - } - else{ - # It wasn't a Java exception after all... - die $@ ; - } - } - -=for comment - -What's important to understand is that $@ actually contains a reference -to the Throwable object that was thrown by Java. The getMessage() function -is really a method of the java.lang.Exception class. So if Java is throwing -an custom exception you have in your code, you will have access to that -exception object's public method just like any other Java object in -C<Inlin::Java>. It is also probably a good idea to undef $@ once you have -treated a Java exception, or else the object still has a reference until -$@ is reset by the next eval. - Z<> - - -=head1 CALLBACKS - -You can now (as of 0.31), call Perl functions from Java. To do this you -need to create an InlinePerlJavaCaller object. You can then use the -CallPerl method to call your Perl function. You pass the paramters using -an array of java.lang.Object. The method will return the result in a -java.lang.Object, which you must then cast to as a java.lang.String -(if your Perl method returns a Perl scalar), or anything else if your Perl -function returns an "Inline::Java" object. Here is a example of a typical -use: - -=for comment - - use Inline Java => <<'END'; - import java.util.* ; - - class regexp extends InlineJavaPerlCaller { - public regexp(){ - } - - public boolean match(String target, String pattern) - throws InlineJavaException { - try { - String m = (String)CallPerl("main", "regexp", - new Object [] {target, pattern}) ; - - if (m.equals("1")){ - return true ; - } - } - catch (PerlException pe){ - // $@ is in pe.GetObject() - } - - return false ; - } - } - END - - my $re = new regexp() ; - my $match = $re->match("Inline::Java", "^Inline") ; - print "match? -> $match\n" ; - - - sub regexp { - my $target = shift ; - my $pattern = shift ; - - return ($target =~ /$pattern/) ; - } - -=for comment - -The CallPerl method can throw 2 types of exceptions, both of which are inner -classes of InlineJavaPerlCaller: InlineJavaException and PerlException. The -former, which designates an internal C<Inline::Java> error, should never be -dealt with and should be thrown back all the way up to the function that was -initially called by Perl. The latter indicates that the Perl callback threw -an exception (die() or croak()). The value of $@ (this can be a scalar or -any valid "Inline::Java" object) can retreived using the GetObject method -of the PerlException object. - Z<> - - -=head1 STUDYING - -As of version 0.21, C<Inline::Java> can learn about other Java classes -and use them just like the Java code you write inside your Perl script. -In fact you are not even required to write Java code inside your Perl -script anymore. Here's how to use the 'studying' function: - -=for comment - - use Inline ( - Java => 'STUDY', - STUDY => ['java.util.HashMap'], - ) ; - - my $hm = new java::util::HashMap() ; - $hm->put("key", "value") ; - my $v = $hm->get("key") ; - -=for comment - -If you do not wish to put any Java code inside you Perl script, you must -use the string 'STUDY' as your code. This will skip the build section. - -You can also use the AUTOSTUDY option to tell C<Inline::Java> that you wish -to study all classes that it comes across: - -=for comment - - use Inline Java => <<'END', AUTOSTUDY => 1; - import java.util.* ; - - class Foo9 { - public Foo9() { - } - - public HashMap get_hm(){ - HashMap hm = new HashMap() ; - return hm ; - } - } - END - - my $obj = new Foo9() ; - my $hm = $obj->get_hm() ; - $hm->put("key", "value") ; - my $v = $hm->get("key") ; - -=for comment - -In this case C<Inline::Java> intercepts the return value of the get_hm() -method, sees that it's of a type that it doesn't know about -(java.lang.HashMap), and immediately studies the class. After that call -the java::lang::HashMap class is available to use through Perl. - Z<> - - -=head1 USING MULTIPLE SECTIONS - -If you wish to use more than one C<Inline::Java> section in your Perl script, -you will need to use the Inline NAME option to name your modules. You can then -use a special syntax in your CLASSPATH (either the environment variable or the -configuration option) to tell what Inline::Java modules it will need to load -at runtime: - -=for comment - - package Foo ; - use Inline ( - Java => <<'END_FOO', - class F1 { - public F1() { - } - } - END_FOO - NAME => "Foo", - CLASSPATH => "[PERL_INLINE_JAVA=Foo, Bar]", - ) ; - - package Bar ; - use Inline ( - Java => <<'END_BAR', - class B1 { - public B1() { - } - } - END_BAR - NAME => "Bar", - ) ; - - package main ; - my $f = new Foo::F1() ; - my $b = new Bar::B1() ; - -=for comment - -If you set the CLASSPATH via the configuration option, remember to do so in the -first Inline::Java section. Also remember that you can't use Java packages with -Inline::Java. Your classes must be in the unnamed package. - Z<> - - -=head1 JNI vs CLIENT/SERVER MODES - -Starting in version 0.20, it is possible to use the JNI (Java Native -Interface) extension. This enables C<Inline::Java> to load the Java virtual -machine as a shared object instead of running it as a stand-alone server. -This brings an improvement in performance. - -However, the JNI extension is not available on all platforms (see README and -README.JNI for more information). For that reason, if you have built the -JNI extension, you must enable it explicitely by doing one of the following: - - - set the JNI configuration option to 1 - - set the PERL_INLINE_JAVA_JNI environment variable to 1 - -Note: C<Inline::Java> only creates one virtual machine instance. Therefore -you can't use JNI for some sections and client/server for others. The first -section determines the execution mode. - Z<> - - -=head1 SHARED_JVM - -Starting with version 0.30, the C<Inline::Java> JVM can now be shared between -multiple processes. The first process to start the JVM is considered the JVM -owner and will shutdown the JVM on exit. All other processes can connect as -needed to the JVM. If any of these other processes where created by forking -the parent process, the Inline::Java->reconnect_JVM() function must be called -in the child to get a fresh connection to the JVM. Ex: - -=for comment - - use Inline ( - Java => <<'END', - class Foo10 { - public Foo10(){ - } - } - END - SHARED_JVM => 1, - ) ; - - my $f = new Foo10() ; - - my $nb = 5 ; - for (my $i = 0 ; $i < $nb ; $i++){ - if (! fork()){ - Inline::Java::reconnect_JVM() ; - $f = new Foo10() ; - exit ; - } - } - sleep(5) ; - -=for comment - -Once this code was run, each of the 6 processes will have created a different -instance of the 't' class. Data can be shared between the processes by using -static members in the Java code. - -If processes not forked off the parent are connecting to the shared JVM, the -parent's CLASSPATH must be set properly or else the parent will not see these -classes. See USING MULTIPLE SECTIONS for more details. - -If you want to use C<Inline::Java> in a CGI script, do the following: - -=for comment - - use Inline ( - Java => <<'END', - class Foo11 { - public Foo11(){ - } - } - END - SHARED_JVM => 1, - ) ; - - Inline::Java::release_JVM() ; - my $f = new Foo11() ; - -=for comment - -The release_JVM() function simply tells the CGI script that it is no -longer responsible for shutting down the JVM. What this does is that -the first CGI to execute will start the JVM, but by releasing it the JVM -will never be shutdown. Subsequent CGI, sine they have the SHARED_JVM -option enabled, will try to connect to an already existing JVM before -trying to start a new one. Therefore if the JVM haapens to crash or is -killed, the next CGI that runs will start a new one. - -Please note that the SHARED_JVM feature does not work in JNI mode. - Z<> - - -=head1 SUPPORTED PLATFORMS - -This is an ALPHA release of C<Inline::Java>. Further testing and -expanded support for other operating systems and platforms will be a -focus for future releases. It has been tested on: - - - Solaris 2.5.1 + Perl 5.6 + Java SDK 1.2.2 - - Solaris 2.8 + Perl 5.6 + Java SDK 1.3.0 - - Linux Redhat 6.2 Alpha + Perl 5.6 + Java SDK 1.3.1 - - Windows 2000 + Perl 5.6 + Java SDK 1.3.0 - - Windows 95 + Perl 5.6 + Java SDK 1.2.2 - (under Win95/98/Me, use 'perl Makefile.PL fix' to fix the Makefile) - -It likely will work with many other configurations. - Z<> - - -=head1 HOW IT WORKS - -This is how C<Inline::Java> works. Once the user's code is compiled by the -javac binary, C<Inline::Java>'s own Java code is compiled. This code -implements a server (or not if you use the JNI mode) that receives requests -from Perl to create objects, call methods, destroy objects, etc. It is also -capable of analyzing Java code to extract the public symbols. Once this -code is compiled, it is executed to extract the symbols from the Java code. - -Once this is done, the user's code information is fetched and is bound to -Perl namespaces. Then C<Inline::Java>'s code is run to launch the server. The -Perl script then connects to the server using a TCP socket (or not if you use -the JNI mode). Then each object creation or method invocation on "Java -objects" send requests to the server, which processes them and returns -object ids to Perl which keeps them the reference te objects in the future. - Z<> - - -=head1 SEE ALSO - -For information about using C<Inline>, see L<Inline>. - -For information about other Inline languages, see L<Inline-Support>. - -Inline::Java's mailing list is inl...@perl.org - -The subscribe, send email to inline-subscr...@perl.org - Z<> - - -=head1 BUGS AND DEFICIENCIES - -When reporting a bug, please do the following: - - - Put "use Inline REPORTBUG;" at the top of your code, or - use the command line option "perl -MInline=REPORTBUG ...". - - Run your code. - - Follow the printed instructions. - -Here are some things to watch out for: - -=over 4 - -=item 1 - -You can't use the "package" Java directive when using C<Inline::Java>. - -=item 2 - -You can't create public classes when using Inline::Java. This is due -to the fact that Java requires that public classes be defined in a -.java file of the same name (C<Inline::Java> can't work this way). - -=item 3 - -You shouldn't name any of your classes starting "InlineJavaServer" or -"InlineJavaPerl". Those are reserved for C<Inline::Java>'s own Java -classes. Also do not name your classes 'B', 'S', 'I', 'J', 'F', 'D', -'C', 'Z' or 'L'. These classes seem to be used internally to represent -the primitive types. - - -=item 4 - -If you upgrade C<Inline::Java> from a previous version, be sure to delete -your Inline directory so that C<Inline::Java>'s own Java classes get -rebuilt to match the Perl code. - -=back - Z<> - -=head1 AUTHOR - -Patrick LeBoutillier <p...@cpan.org> - -Brian Ingerson <i...@cpan.org> is the author of Inline. - Z<> - - -=head1 COPYRIGHT - -Copyright (c) 2001, Patrick LeBoutillier. - -All Rights Reserved. This module is free software. It may be used, -redistributed and/or modified under the terms of the Perl Artistic -License. - -(see http://www.perl.com/perl/misc/Artistic.html) - -=cut +=head1 NAME + +Inline::Java - Write Perl classes in Java. + +=head1 SYNOPSIS + +=for comment + + use Inline Java => <<'END_OF_JAVA_CODE' ; + class Pod_alu { + public Pod_alu(){ + } + + public int add(int i, int j){ + return i + j ; + } + + public int subtract(int i, int j){ + return i - j ; + } + } + END_OF_JAVA_CODE + + my $alu = new Pod_alu() ; + print "9 + 16 = ", $alu->add(9, 16), "\n" ; # prints 9 + 16 = 25 + print "9 - 16 = ", $alu->subtract(9, 16), "\n" ; # prints 9 - 16 = -7 + +=for comment + +=head1 WARNING + +THIS IS ALPHA SOFTWARE. It is incomplete and possibly unreliable. +It is also possible that some elements of the interface (API) will +change in future releases. + Z<> + + +=head1 DESCRIPTION + +The C<Inline::Java> module allows you to put Java source code +directly "inline" in a Perl script or module. A Java compiler +is launched and the Java code is compiled. Then Perl asks the +Java classes what public methods have been defined. These classes +and methods are available to the Perl program as if they had been +written in Perl. + +The process of interrogating the Java classes for public methods +occurs the first time you run your Java code. The namespace is +cached, and subsequent calls use the cached version. + Z<> + + +=head1 USING THE Inline::Java MODULE + +C<Inline::Java> is driven by fundamentally the same idea as other +C<Inline> language modules, like C<Inline::C> or C<Inline::CPP>. +Because Java is both compiled and interpreted, the method of getting +your code is different, but overall, using C<Inline::Java> is very similar +to any other C<Inline> language module. + +This section will explain the different ways to C<use> Inline::Java. +For more details on C<Inline>, see 'perldoc Inline'. + +B<Basic Usage> + +The most basic form for using C<Inline::Java> is: + + use Inline Java => 'Java source code' ; + +Of course, you can use Perl's "here document" style of quoting to make +the code slightly easier to read: + + use Inline Java => <<'END'; + + Java source code goes here. + + END + +The source code can also be specified as a filename, a subroutine +reference (sub routine should return source code), or an array +reference (array contains lines of source code). This information +is detailed in 'perldoc Inline'. + +In order for C<Inline::Java> to function properly, it needs to know +where to find the Java compiler (javac) and the Java Runtime (java) +on your machine. This is done using one of the following techniques: + + - set the BIN configuration option to the correct directory + - set the PERL_INLINE_JAVA_BIN environment variable to the correct + directory + - put the correct directory in your PATH environment variable + + +=head1 CONFIGURATION OPTIONS + +There are a number of configuration options that dictate the +behavior of C<Inline::Java>: + + BIN: + Specifies the path to your Java binaries. + Ex: BIN => 'my/java/bin/path' + Note: This configuration option only has an effect on the first + 'use Inline Java' call inside a Perl script, since all other calls + make use of the same JVM. However, you can use it if you want to + change which 'javac' executable is used for subsequent calls. + + PORT: + Specifies the starting port number for the server. If many + C<Inline::Java> blocks are declared, the port number is + incremented each time. + Default is 7890. + Ex: PORT => 4567 + Note: This configuration option only has an effect on the first + 'use Inline Java' call inside a Perl script, since all other calls + make use of the same JVM. + + STARTUP_DELAY: + Specifies the maximum number of seconds that the Perl script + will try to connect to the Java server. In other this is the + delay that Perl gives to the Java server to start. + Default is 15 seconds. + Ex: STARTUP_DELAY => 20 + Note: This configuration option only has an effect on the first + 'use Inline Java' call inside a Perl script, since all other calls + make use of the same JVM. + + CLASSPATH: + Adds the specified CLASSPATH to the environment CLASSPATH. + Ex: CLASSPATH => '/my/other/java/classses' + Note: This configuration option only has an effect on the first + 'use Inline Java' call inside a Perl script, since all other calls + make use of the same JVM. + + JNI: + Toggles the execution mode. The default is to use the client/server + mode. To use the JNI extension (you must have built it at install + time though. See README and README.JNI for more information), set + JNI to 1. + Ex: JNI => 1 + Note: This can also be set globally by setting the + PERL_INLINE_JAVA_JNI environment variable to 1. + Note: This configuration option only has an effect on the first + 'use Inline Java' call inside a Perl script, since all other calls + make use of the same JVM. + + SHARED_JVM: + This mode enables mutiple processes to share the same JVM. It was + created mainly in order to be able to use C<Inline::Java> under + mod_perl. + Ex: SHARED_JVM => 1 + Note: This configuration option only has an effect on the first + 'use Inline Java' call inside a Perl script, since all other calls + make use of the same JVM. + + DEBUG: + Enables debugging info + Ex: DEBUG => 1 + + WARN_METHOD_SELECT: + Throws a warning when C<Inline::Java> has to 'choose' between + different method signatures. The warning states the possible + choices and the signature chosen. + Ex: WARN_METHOD_SELECT => 1 + + STUDY: + Takes an array of Java classes that you wish to have + C<Inline::Java> learn about so that you can use them inside Perl. + Ex: STUDY => ['java.lang.HashMap', 'my.class'] ; + + AUTOSTUDY: + Makes C<Inline::Java> automatically study unknown classes it + encounters. + Ex: STUDY => ['java.lang.HashMap', 'my.class'] ; + + +=head1 ENVIRONMENT VARIABLES + + PERL_INLINE_JAVA_BIN: + Same as the BIN option. + + PERL_INLINE_JAVA_JNI: + Same as the JNI option. + + PERL_INLINE_SHARED_JVM: + Same as the SHARED_JVM option. + + PERL_INLINE_JAVA_DEBUG: + Same as the DEBUG option. + + PERL_INLINE_JAVA_COMMAND_COM: + If set to a true value, tells Inline::Java that you are using + the command.com shell. Inline::Java should normally be able + to determine this on its own. + + +=head1 CLASSES AND OBJECTS + +Because Java is object oriented, any interface between Perl and Java +needs to support Java classes adequately. + +Example: + +=for comment + + use Inline Java => <<'END' ; + class Pod_1 { + String data = "data" ; + static String sdata = "static data" ; + + public Pod_1(){ + } + + public String get_data(){ + return data ; + } + + public static String get_static_data(){ + return sdata ; + } + + public void set_data(String d){ + data = d ; + } + + private void priv(){ + } + } + END + + my $obj = new Pod_1 ; + print $obj->get_data() . "\n" ; # prints data + $obj->set_data("new data") ; + print $obj->get_data() . "\n" ; # prints new data + +=for comment + +C<Inline::Java> created a new namespace called C<main::Pod_1> and +created the following functions: + + sub main::Pod_::new { ... } + sub main::Pod_::Pod_1 { ... } + sub main::Pod_::get_data { ... } + sub main::Pod_::get_sdata { ... } + sub main::Pod_::set_data { ... } + sub main::Pod_::DESTROY { ... } + +Note that only the public methods are exported to Perl. +Note also that the class itself is not public. With +C<Inline::Java> you cannot create public classes because Java +requires that they be defined in a .java file of the same +name (C<Inline::Java> can't work this way). + +Inner classes are also supported, you simply need to supply a reference +to an outer class object as the first parameter of the constructor: + +=for comment + + use Inline Java => <<'END' ; + class Pod_2 { + public Pod_2(){ + } + + public class Pod_2_Inner { + public String name = "Pod_2_Inner" ; + + public Pod_2_Inner(){ + } + } + } + END + + my $obj = new Pod_2() ; + my $obj2 = new Pod_2::Pod_2_Inner($obj) ; + print $obj2->{name} . "\n" ; # prints Pod_2_Inner + +=for comment + +=head1 METHODS + +In the previous example we have seen how to call a method. You can also +call static methods in the following manner: + + print Pod_1->get_sdata() . "\n" ; # prints static data + # or + my $obj = new Pod_1() ; + print $obj->get_sdata() . "\n" ; # prints static data + +You can pass any kind of Perl scalar or any Java object to a method. It +will be automatically converted to the correct type: + +=for comment + + use Inline Java => <<'END' ; + class Pod_3_arg { + public Pod_3_arg(){ + } + } + class Pod_3 { + public int n ; + + public Pod_3(int i, String j, Pod_3_arg k) { + n = i ; + } + } + END + + my $obj = new Pod_3_arg() ; + my $obj2 = new Pod_3(5, "toto", $obj) ; + print $obj2->{n} . "\n" ; # prints 5 + +=for comment + +will work fine. These objects can be of any type, even if these types +are not known to C<Inline::Java>. This is also true for return types: + +=for comment + + use Inline Java => <<'END' ; + import java.util.* ; + + class Pod_4 { + public Pod_4(){ + } + + public HashMap get_hash(){ + HashMap h = new HashMap() ; + h.put("key", "value") ; + + return h ; + } + + public String do_stuff_to_hash(HashMap h){ + return h.get("key") ; + } + } + END + + my $obj = new Pod_4() ; + my $h = $obj->get_hash() ; + print $obj->do_stuff_to_hash($h) ; # prints value + +=for comment + +Objects of types unknown to Perl can exist in the Perl space, you just +can't call any of their methods. + Z<> + + +=head1 MEMBER VARIABLES + +You can also access all public member variables (static or not) from Perl. +As with method arguments, the types of these variables does not need to +be known to Perl: + +=for comment + + use Inline Java => <<'END' ; + import java.util.* ; + + class Pod_5 { + public int i ; + public static HashMap hm ; + + public Pod_5(){ + } + } + END + + my $obj = new Pod_5() ; + $obj->{i} = 2 ; + print $obj->{i} . "\n" ; # prints 2 + my $hm1 = $obj->{hm} ; # instance way + my $hm2 = $Pod_4::hm ; # static way + +=for comment + +Note: Watch out for typos when accessing members in the static fashion, +'use strict' will not catch them since they have a package name... + Z<> + + +=head1 ARRAYS + +You can also send and receive arrays. This is done simply by using Perl +lists: + +=for comment + + use Inline Java => <<'END' ; + import java.util.* ; + + class Pod_6 { + public int i[] = {5, 6, 7} ; + + public Pod_6(){ + } + + public String [] f(String a[]){ + return a ; + } + + public String [][] f(String a[][]){ + return a ; + } + } + END + + my $obj = new Pod_6() ; + my $i_2 = $obj->{i}->[2] ; # 7 + print $i_2 . "\n" ; # prints 7 + + my $a1 = $obj->f(["a", "b", "c"]) ; # String [] + my $a2 = $obj->f([ + ["00", "01"], + ["10", "11"], + ]) ; # String [][] + print $a2->[1]->[0] . "\n" ; # prints 10 + +=for comment + +=head1 TYPE CASTING + +Sometimes when a class as many signatures for the same method, +C<Inline::Java> will have to select one of the signatures based on +the arguments that are passed: + +=for comment + + use Inline Java => <<'END' ; + class Pod_7 { + public Pod_7(){ + } + + public String f(int i){ + return "int" ; + } + + public String f(char c){ + return "char" ; + } + } + END + + my $obj = new Pod_7() ; + print $obj->f('5') . "\n" # prints int ; + +=for comment + +In this case, C<Inline::Java> will call f(int i), because '5' is an integer. +But '5' is a valid char as well. So to force the call of f(char c), do the +following: + + use Inline::Java qw(cast) ; + $obj->f(cast('char', '5')) ; + # or + $obj->f(Inline::Java::cast('char', '5')) ; + +The cast function forces the selection of the matching signature. Note that +the cast must match the argument type exactly. Casting to a class that +extends the argument type will not work. + +Another case where type casting is need is when one wants to pass an array +as a java.lang.Object: + + use Inline Java => <<'END'; + class Pod_8 { + public Object o ; + int a[] = {1, 2, 3} ; + + public Pod_8() { + } + } + END + + my $obj = new Pod_8() ; + $obj->{o} = [1, 2, 3] ; # No! + +The reason why this will not work is simple. When C<Inline::Java> sees an +array, it checks the Java type you are trying to match it against to validate +the construction of your Perl list. But in this case, it can't validate +the array because you're assigning it to an Object. You must use the 3 +parameter version of the cast function to do this: + + $obj->{o} = Inline::Java::cast( + "java.lang.Object", + [1, 2, 3], + "[Ljava.lang.String;") ; + +This tells C<Inline::Java> to validate your Perl list as a String [], and +then cast it as an Object. + +Here is how to construct the array type representations: + + [<type> -> 1 dimensional <type> array + [[<type> -> 2 dimensional <type> array + ... + + where <type> is one of: + B byte S short I int J long + F float D double C char Z boolean + + L<class>; array of <class> objects + +This is described in more detail in most Java books that talk about +reflection. + +But you only need to do this if you have a Perl list. If you already have a +Java array reference obtained from elsewhere, you don't even need to cast: + + $obj->{o} = $obj->{a} ; + + +=head1 EXCEPTIONS + +You can now (as of 0.31) catch exceptions as objects when they are thrown +from Java. To do this you use the regular Perl exception tools: eval and +$@. A helper function named 'caught' is provided to help determine the +type of the exception. Here is a example of a typical use: + +=for comment + + use Inline Java => <<'END' ; + import java.util.* ; + + class Pod_9 { + public Pod_9(boolean t) throws Exception { + if (t){ + throw new Exception("ouch!") ; + } + } + } + END + + use Inline::Java qw(caught) ; + + eval { + my $obj = new Pod_9(1) ; + } ; + if ($@){ + if (caught("java.lang.Exception")){ + my $msg = $@->getMessage() ; + print "$msg" . "\n" ; # prints ouch! + } + else{ + # It wasn't a Java exception after all... + die $@ ; + } + } + +=for comment + +What's important to understand is that $@ actually contains a reference +to the Throwable object that was thrown by Java. The getMessage() function +is really a method of the java.lang.Exception class. So if Java is throwing +an custom exception you have in your code, you will have access to that +exception object's public method just like any other Java object in +C<Inlin::Java>. It is also probably a good idea to undef $@ once you have +treated a Java exception, or else the object still has a reference until +$@ is reset by the next eval. + Z<> + + +=head1 CALLBACKS + +You can now (as of 0.31), call Perl functions from Java. To do this you +need to create an InlinePerlJavaCaller object. You can then use the +CallPerl method to call your Perl function. You pass the parameters using +an array of java.lang.Object. The method will return the result in a +java.lang.Object, which you must then cast to as a java.lang.String +(if your Perl method returns a Perl scalar), or anything else if your Perl +function returns an "Inline::Java" object. Here is a example of a typical +use: + +=for comment + + use Inline Java => <<'END' ; + import java.util.* ; + + class Pod_regexp extends InlineJavaPerlCaller { + public Pod_regexp(){ + } + + public boolean match(String target, String pattern) + throws InlineJavaException { + try { + String m = (String)CallPerl("main", "regexp", + new Object [] {target, pattern}) ; + + if (m.equals("1")){ + return true ; + } + } + catch (PerlException pe){ + // $@ is in pe.GetObject() + } + + return false ; + } + } + END + + my $re = new Pod_regexp() ; + my $match = $re->match("Inline::Java", "^Inline") ; + print $match . "\n" ; # prints 1 + + + sub regexp { + my $target = shift ; + my $pattern = shift ; + + return ($target =~ /$pattern/) ; + } + +=for comment + +The CallPerl method can throw 2 types of exceptions, both of which are inner +classes of InlineJavaPerlCaller: InlineJavaException and PerlException. The +former, which designates an internal C<Inline::Java> error, should never be +dealt with and should be thrown back all the way up to the function that was +initially called by Perl. The latter indicates that the Perl callback threw +an exception (die() or croak()). The value of $@ (this can be a scalar or +any valid "Inline::Java" object) can retreived using the GetObject method +of the PerlException object. + Z<> + + +=head1 STUDYING + +As of version 0.21, C<Inline::Java> can learn about other Java classes +and use them just like the Java code you write inside your Perl script. +In fact you are not even required to write Java code inside your Perl +script anymore. Here's how to use the 'studying' function: + +=for comment + + use Inline ( + Java => 'STUDY', + STUDY => ['java.util.HashMap'], + ) ; + + my $hm = new java::util::HashMap() ; + $hm->put("key", "value") ; + print $hm->get("key") . "\n" ; # prints value + +=for comment + +If you do not wish to put any Java code inside you Perl script, you must +use the string 'STUDY' as your code. This will skip the build section. + +You can also use the AUTOSTUDY option to tell C<Inline::Java> that you wish +to study all classes that it comes across: + +=for comment + + use Inline Java => <<'END', AUTOSTUDY => 1 ; + import java.util.* ; + + class Pod_10 { + public Pod_10(){ + } + + public HashMap get_hm(){ + HashMap hm = new HashMap() ; + return hm ; + } + } + END + + my $obj = new Pod_10() ; + my $hm = $obj->get_hm() ; + $hm->put("key", "value") ; + print $hm->get("key") . "\n" ; # prints value + +=for comment + +In this case C<Inline::Java> intercepts the return value of the get_hm() +method, sees that it's of a type that it doesn't know about +(java.lang.HashMap), and immediately studies the class. After that call +the java::lang::HashMap class is available to use through Perl. + Z<> + + +=head1 USING MULTIPLE SECTIONS + +If you wish to use more than one C<Inline::Java> section in your Perl script, +you will need to use the Inline NAME option to name your modules. You can then +use a special syntax in your CLASSPATH (either the environment variable or the +configuration option) to tell what Inline::Java modules it will need to load +at runtime: + +=for comment + + package Pod_Foo ; + use Inline ( + Java => <<'END_Pod_Foo', + class Pod_Foo { + public Pod_Foo(){ + } + } + END_Pod_Foo + NAME => "Pod_Foo", + CLASSPATH => "[PERL_INLINE_JAVA=Pod_Foo, Pod_Bar]", + ) ; + + package Pod_Bar ; + use Inline ( + Java => <<'END_Pod_Bar', + class Pod_Bar { + public Pod_Bar() { + } + } + END_Pod_Bar + NAME => "Pod_Bar", + ) ; + + package main ; + my $f = new Pod_Foo::Pod_Foo() ; + my $b = new Pod_Bar::Pod_Bar() ; + +=for comment + +If you set the CLASSPATH via the configuration option, remember to do so in the +first Inline::Java section. Also remember that you can't use Java packages with +Inline::Java. Your classes must be in the unnamed package. + Z<> + + +=head1 JNI vs CLIENT/SERVER MODES + +Starting in version 0.20, it is possible to use the JNI (Java Native +Interface) extension. This enables C<Inline::Java> to load the Java virtual +machine as a shared object instead of running it as a stand-alone server. +This brings an improvement in performance. + +If you have built the JNI extension, you must enable it explicitely by doing +one of the following: + + - set the JNI configuration option to 1 + - set the PERL_INLINE_JAVA_JNI environment variable to 1 + +Note: C<Inline::Java> only creates one virtual machine instance. Therefore +you can't use JNI for some sections and client/server for others. The first +section determines the execution mode. + +See README.JNI for more information about the JNI extension. + Z<> + + +=head1 SHARED_JVM + +Starting with version 0.30, the C<Inline::Java> JVM can now be shared between +multiple processes. The first process to start the JVM is considered the JVM +owner and will shutdown the JVM on exit. All other processes can connect as +needed to the JVM. If any of these other processes where created by forking +the parent process, the Inline::Java->reconnect_JVM() function must be called +in the child to get a fresh connection to the JVM. Ex: + +=for comment + + use Inline ( + Java => <<'END', + class Pod_11 { + public static int i = 0 ; + public Pod_11(){ + i++ ; + } + } + END + SHARED_JVM => 1, + ) ; + + my $f = new Pod_11() ; + + my $nb = 5 ; + for (my $i = 0 ; $i < $nb ; $i++){ + if (! fork()){ + Inline::Java::reconnect_JVM() ; + $f = new Pod_11() ; + exit ; + } + } + sleep(5) ; + print $f->{i} . "\n" ; # prints 6 + +=for comment + +Once this code was run, each of the 6 processes will have created a different +instance of the 't' class. Data can be shared between the processes by using +static members in the Java code. + +If processes not forked off the parent are connecting to the shared JVM, the +parent's CLASSPATH must be set properly or else the parent will not see these +classes. See USING MULTIPLE SECTIONS for more details. + Z<> + + +=head1 USING Inline::Java IN A CGI + +If you want to use C<Inline::Java> in a CGI script, do the following: + +=for comment + + use CGI ; + use Inline ( + Java => <<'END', + class Pod_counter { + public static int cnt = 0 ; + public Pod_counter(){ + cnt++ ; + } + } + END + SHARED_JVM => 1, + ) ; + + Inline::Java::release_JVM() ; + my $c = new Pod_counter() ; + + my $q = new CGI ; + print + $q->start_html() . + "This page has been accessed " . $c->{cnt} . " times." . + $q->end_html() ; + +=for comment + +The release_JVM() function simply tells the CGI script that it is no +longer responsible for shutting down the JVM. What this does is that +the first CGI to execute will start the JVM, but by releasing it the JVM +will never be shutdown. Subsequent CGI, since they have the SHARED_JVM +option enabled, will try to connect to an already existing JVM before +trying to start a new one. Therefore if the JVM happens to crash or is +killed, the next CGI that runs will start a new one. + Z<> + + +=head1 USING Inline::Java UNDER MOD_PERL + +Here is an example of how to use C<Inline::Java> under mod_perl: + + use Apache::Constants ; + use Inline ( + Java => <<'END', + class Pod_counter { + public static int cnt = 0 ; + public Pod_counter(){ + cnt++ ; + } + } + END + SHARED_JVM => 1, + ) ; + + Inline::Java::reconnect_JVM() ; + + sub handler { + my $r = shift ; + + my $c = new Pod_counter() ; + my $q = new CGI ; + print + $q->start_html() . + "This page has been accessed " . $c->{cnt} . " times." . + $q->end_html() ; + + return Apache::Constants::OK() ; + } + +The reconnect_JVM() function makes sure that our connection to the JVM +is new and that we are not using a connection that we received after +a fork. + Z<> + + +=head1 SUPPORTED PLATFORMS + +This is an ALPHA release of C<Inline::Java>. Further testing and +expanded support for other operating systems and platforms will be a +focus for future releases. It has been tested on: + + - Solaris 2.8 + Perl 5.6 + Java SDK 1.3.1 + - Linux Redhat 7.1 Intel + Perl 5.6 + Java SDK 1.3.1 + - Windows 2000 + Perl 5.6 + Java SDK 1.3.0 + - Windows 95 + Perl 5.6 + Java SDK 1.2.2 + +It likely will work with many other configurations. + Z<> + + +=head1 HOW IT WORKS + +This is how C<Inline::Java> works. Once the user's code is compiled by the +javac binary, C<Inline::Java>'s own Java code is compiled. This code +implements a server (or not if you use the JNI mode) that receives requests +from Perl to create objects, call methods, destroy objects, etc. It is also +capable of analyzing Java code to extract the public symbols. Once this +code is compiled, it is executed to extract the symbols from the Java code. + +Once this is done, the user's code information is fetched and is bound to +Perl namespaces. Then C<Inline::Java>'s code is run to launch the server. The +Perl script then connects to the server using a TCP socket (or not if you use +the JNI mode). Then each object creation or method invocation on "Java +objects" send requests to the server, which processes them and returns +object ids to Perl which keeps them the reference te objects in the future. + Z<> + + +=head1 SEE ALSO + +For information about using C<Inline>, see L<Inline>. + +For information about other Inline languages, see L<Inline-Support>. + +Inline::Java's mailing list is inl...@perl.org. To subscribe, send +an email to inline-subscr...@perl.org + +Inline::Java's home page is http://inline-java.sourceforge.net + Z<> + + +=head1 BUGS AND DEFICIENCIES + +When reporting a bug, please do the following: + + - Put "use Inline REPORTBUG;" at the top of your code, or + use the command line option "perl -MInline=REPORTBUG ...". + - Run your code. + - Follow the printed instructions. + +Here are some things to watch out for: + +=over 4 + +=item 1 + +You can't use the "package" Java directive when using C<Inline::Java>. + +=item 2 + +You can't create public classes when using Inline::Java. This is due +to the fact that Java requires that public classes be defined in a +.java file of the same name (C<Inline::Java> can't work this way). + +=item 3 + +You shouldn't name any of your classes starting "InlineJavaServer" or +"InlineJavaPerl". Those are reserved for C<Inline::Java>'s own Java +classes. Also do not name your classes 'B', 'S', 'I', 'J', 'F', 'D', +'C', 'Z' or 'L'. These classes seem to be used internally by Java to +represent the primitive types. + + +=item 4 + +If you upgrade C<Inline::Java> from a previous version, be sure to delete +your Inline directory so that C<Inline::Java>'s own Java classes get +rebuilt to match the Perl code. + +=back + Z<> + +=head1 AUTHOR + +Patrick LeBoutillier <p...@cpan.org> + +Brian Ingerson <i...@cpan.org> is the author of Inline. + Z<> + + +=head1 COPYRIGHT + +Copyright (c) 2001, Patrick LeBoutillier. + +All Rights Reserved. This module is free software. It may be used, +redistributed and/or modified under the terms of the Perl Artistic +License. + +(see http://www.perl.com/perl/misc/Artistic.html) + +=cut diff --git a/README b/README index 3486b67..811a2f1 100644 --- a/README +++ b/README @@ -26,9 +26,6 @@ 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. -This extension works without problems on MSWin32 systems, pretty well on -Linux (there are some threding issues), but requires rebuilding Perl on -Solaris (and possibly in Linux as well) because of threading issues. See README.JNI for more information on building the JNI extension. @@ -45,41 +42,28 @@ INSTALLATION: To install Inline::Java do this: perl Makefile.PL -make (see Note 2) -make test (see Note 3, 4, 5) -perl shared_jvm_test.pl (see Note 6) +make (see Note 1) +make test (see Note 2, 3, 4) make install You have to 'make install' before you can run it successfully. -Note 1: Use nmake on Windows systems. If you are using the COMMAND.COM shell -under Windows, Inline::Java will try to detect it. If it doesn't, -you should set the PERL_INLINE_JAVA_COMMAND_COM environment variable -to a true value. You also will need set this whenever you use the module -later on. +Note 1: Use nmake on Windows systems. -Note 2: On Win95/98/Me, you might get and error when doing 'nmake'. If so, -rerun 'perl Makefile.PL' adding the 'fix' option, i.e. 'perl Makefile.PL fix'. - -Note 3: In order for 'make test' to run properly, you should put the +Note 2: In order for 'make test' to run properly, you should put the directory to your Java binaries in either your PATH environment variable or in the PERL_INLINE_JAVA_BIN environment variable. 'make test' will remind you if you don't do this. -Note 4: If you have built the JNI extension and want the test suite to use +Note 3: If you have built the JNI extension and want the test suite to use it, you will need to set the PERL_INLINE_JAVA_JNI environment variable to 1 BEFORE running 'make test'. -Note 5: When testing Inline::Java, it's always a good idea to run 'make test' +Note 4: When testing Inline::Java, it's always a good idea to run 'make test' twice. The first time you test the building and loading of a module, the second time you test loading of an already built module. -Note 6: If you plan to use Inline::Java under mod_perl or any other program -that forks, you may wish to run 'perl shared_jvm_test.pl'. This will simulate -a forking process that uses Inline::Java. Please keep in mind that this test -does not work under Windows. - ------------------------------------------------------------------------------- FEATURES: @@ -88,9 +72,13 @@ WARNING: THIS IS ALPHA SOFTWARE. It is incomplete and possibly unreliable. It is also possible that some elements of the interface (API) will change in future releases. -Inline::Java version 0.31 is a minor upgrade that includes: +Inline::Java version 0.31 is a major upgrade that includes: + Exception handling (Perl can 'catch' Java exceptions) + Callbacks to Perl from Java ++ More complete test suite ++ Improved documentation and related examples ++ Improved installation script and directions ++ Other minor bug fixes Inline::Java version 0.30 is a major upgrade that includes: + Multi-threaded JVM diff --git a/README.JNI b/README.JNI index e1a1b8b..e52670a 100644 --- a/README.JNI +++ b/README.JNI @@ -1,19 +1,34 @@ 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 platforms. +The JNI extension is available on all supported platforms. The extension builds properly on all platform, but problems can occur when running it on certain platforms. +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. + WIN32 ----- The JNI extension runs without problems on Win32. +LINUX +----- +The JNI extension has been run successfully on Linux, but only with +Java 2 SDK 1.2.2. Please take note that under certain circumstances +the process would freeze just before terminating. This issue seemed +to the main thread waiting for other threads to terminate. + SOLARIS ------- The JNI extension requires Perl to be built following specific instructions @@ -46,47 +61,6 @@ in order to run properly on Solaris. Here's what you have to do: Then use this Perl version to build and run Inline::Java. -LINUX ------ -The JNI extension has been run successfully on Linux, but some runtime -problems can occur depending on Java 2 SDK version and other factors. -For best results you need to use Java 1.2.2 with native threads. To do -this you need to inspect your Java 2 SDK distribution tree, and put in -your LD_LIBRARY_PATH the directories that contain 'native_threads' instead -of those that contain 'green_threads'. - -You should also use any directory that says 'classic' instead of the others. -The Classic VM seems to run better under Linux. - -On my Linux box, here's what I used as LD_LIBRARY_PATH: - - LD_LIBRARY_PATH=/home/patrickl/apps/jdk1.2.2/jre/lib/i386: - /home/patrickl/apps/jdk1.2.2/jre/lib/i386/classic: - /home/patrickl/apps/jdk1.2.2/jre/lib/i386/native_threads - - -BUILDING THE JNI EXTENSION --------------------------- - -- perl Makefile.PL JNI -- make - -At this point you should have built the JNI extension. If for some reason -Makefile.PL tells you in can't find certain files, you can set the paths -manually by editing 'Java/Makefile.PL' and setting the following variables -that you'll find near the top of the file: - - my $java_include = # location of jni.h - my $java_include_os = # location of jni_md.h - my $java_lib = # location of libjvm.so or jvm.lib on MSWin32 - my $java_so = # location of libjvm.so or jvm.dll on MSWin32 - -Now comes the time to run the test suite using the JNI extension. To achieve -this, you will need to set the PERL_INLINE_JAVA_JNI environment variable to 1 -before running 'make test'. - -- make test - RUNNING INLINE::JAVA WITH THE JNI EXTENSION ------------------------------------------- @@ -96,6 +70,9 @@ 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 --------------------------- @@ -104,4 +81,4 @@ Inline::Java 0.30 introduced a 'SHARED_JVM' mode that allows many clients to con 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. +Virtual Machine under any circumstances. \ No newline at end of file -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libinline-java-perl.git _______________________________________________ Pkg-perl-cvs-commits mailing list Pkg-perl-cvs-commits@lists.alioth.debian.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits