[libinline-java-perl] 147/398: Updates from local CVS repository
Jonas Smedegaard
dr at jones.dk
Thu Feb 26 11:42:58 UTC 2015
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 c06672562626c0c0b95a087ba6271a966baf8403
Author: patrick_leb <>
Date: Mon Jan 21 14:47:13 2002 +0000
Updates from local CVS repository
---
Java.pm | 54 +-
Java.pod | 1962 +++++++++++++++++++++++++++++----------------------------
README.JNI | 38 +-
t/pod_test.pl | 82 +++
4 files changed, 1119 insertions(+), 1017 deletions(-)
diff --git a/Java.pm b/Java.pm
index cf8e390..318a1bc 100644
--- a/Java.pm
+++ b/Java.pm
@@ -380,7 +380,7 @@ sub write_java {
my $build_dir = $o->get_api('build_dir') ;
my $modfname = $o->get_api('modfname') ;
- Inline::Java::Portable::mkpath($o, $build_dir) ;
+ $o->mkpath($build_dir) ;
if (! $study_only){
my $p = File::Spec->catfile($build_dir, "$modfname.java") ;
@@ -419,7 +419,7 @@ sub compile {
my $install = File::Spec->catdir($install_lib, "auto", $modpname) ;
- Inline::Java::Portable::mkpath($o, $install) ;
+ $o->mkpath($install) ;
$o->set_classpath($install) ;
my $javac = File::Spec->catfile($o->{ILSM}->{BIN},
@@ -484,7 +484,7 @@ sub compile {
}
if ($o->get_api('cleanup')){
- Inline::Java::Portable::rmpath($o, '', $build_dir) ;
+ $o->rmpath('', $build_dir) ;
}
Inline::Java::debug("compile done.") ;
@@ -636,7 +636,32 @@ sub set_classpath {
}
my $sep = portable("ENV_VAR_PATH_SEP_CP") ;
- my @cp = split(/$sep/, join($sep, @list)) ;
+ my $cpall = join($sep, @list) ;
+
+
+ $cpall =~ s/\s*\[PERL_INLINE_JAVA\s*=\s*(.*?)\s*\]\s*/{
+ my $modules = $1 ;
+ Inline::Java::debug(" found special CLASSPATH entry: $modules") ;
+
+ my @modules = split(m#\s*,\s*#, $modules) ;
+ my $dir = File::Spec->catdir($o->get_config('DIRECTORY'), "lib", "auto") ;
+
+ my %paths = () ;
+ foreach my $m (@modules){
+ $m = File::Spec->catdir(split(m#::#, $m)) ;
+
+ # Here we must make sure that the directory exists, or
+ # else it is removed from the CLASSPATH by Java
+ my $path = File::Spec->catdir($dir, $m) ;
+ $o->mkpath($path) ;
+
+ $paths{$path} = 1 ;
+ }
+
+ join($sep, keys %paths) ;
+ }/ge ;
+
+ my @cp = split(/$sep+/, $cpall) ;
# Add dot to CLASSPATH, required when building
push @cp, '.' ;
@@ -644,27 +669,6 @@ sub set_classpath {
foreach my $p (@cp){
$p =~ s/^\s+// ;
$p =~ s/\s+$// ;
- if ($p =~ /\[PERL_INLINE_JAVA\s*=\s*(.*?)\s*\]/){
- my $modules = $1 ;
- Inline::Java::debug(" found special CLASSPATH entry: $modules") ;
-
- my @modules = split(m#\s*,\s*#, $modules) ;
- my $dir = File::Spec->catdir($o->get_config('DIRECTORY'), "lib", "auto") ;
-
- my %paths = () ;
- foreach my $m (@modules){
- $m = File::Spec->catdir(split(/::/, $m)) ;
-
- # Here we must make sure that the directory exists, or
- # else it is removed from the CLASSPATH by Java
- my $path = File::Spec->catdir($dir, $m) ;
- Inline::Java::Portable::mkpath($o, $path) ;
-
- $paths{$path} = 1 ;
- }
-
- $p = join($sep, keys %paths) ;
- }
}
$ENV{CLASSPATH} = join($sep, @cp) ;
diff --git a/Java.pod b/Java.pod
index 2d7cdc1..7a6a8dd 100644
--- a/Java.pod
+++ b/Java.pod
@@ -1,980 +1,982 @@
-=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 inline at perl.org. To subscribe, send
-an email to inline-subscribe at 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 <patl at cpan.org>
-
-Brian Ingerson <INGY at 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($alu->add(9, 16) . "\n") ; # prints 25
+ print($alu->subtract(9, 16) . "\n") ; # prints -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 (String)h.get("key") ;
+ }
+ }
+ END
+
+ my $obj = new Pod_4() ;
+ my $h = $obj->get_hash() ;
+ print($obj->do_stuff_to_hash($h) ."\n") ; # 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") ;
+ my $val = $hm->get("key") ;
+ print($val . "\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") ;
+ my $val = $hm->get("key") ;
+ print($val . "\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 $nb = 5 ;
+ for (my $i = 0 ; $i < $nb ; $i++){
+ if (! fork()){
+ Inline::Java::reconnect_JVM() ;
+ my $f = new Pod_11() ;
+ exit ;
+ }
+ }
+ sleep(5) ;
+
+ my $f = new Pod_11() ;
+ 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::release_JVM() ;
+ my $c = new Pod_counter() ;
+
+ sub handler {
+ my $r = shift ;
+
+ my $q = new CGI ;
+ print
+ $q->start_html() .
+ "This page has been accessed " . $c->{cnt} . " times." .
+ $q->end_html() ;
+
+ return Apache::Constants::OK() ;
+ }
+
+It has been noticed that sometimes Apache has problems shutting down
+when Inline::Java is used. For now the solution is to shut down Apache
+twice. Then it will restart properly again.
+ 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 inline at perl.org. To subscribe, send
+an email to inline-subscribe at 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 <patl at cpan.org>
+
+Brian Ingerson <INGY at 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.JNI b/README.JNI
index e52670a..2e7c4d2 100644
--- a/README.JNI
+++ b/README.JNI
@@ -11,23 +11,35 @@ 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 on certain platforms.
+running it or tweaking maybe necessary 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.
+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
-----
-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.
+Java 2 SDK 1.2.2:
+ The JNI extension has been run successfully on Linux, but hanging
+can occur 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, provided that you add
+<Java 2 SDK installation path>/jre/lib/<arch>/native_threads/libhpi.so
+to your LD_PRELOAD environment variable.
+
SOLARIS
-------
@@ -62,7 +74,7 @@ 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.
-RUNNING INLINE::JAVA WITH THE JNI EXTENSION
+RUNNING Inline::Java WITH THE JNI EXTENSION
-------------------------------------------
To run Inline::Java with the JNI extension, do one of the following:
@@ -77,8 +89,10 @@ 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.
\ No newline at end of file
+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.
+
diff --git a/t/pod_test.pl b/t/pod_test.pl
new file mode 100644
index 0000000..a66d4c5
--- /dev/null
+++ b/t/pod_test.pl
@@ -0,0 +1,82 @@
+use strict ;
+
+use blib ;
+use Getopt::Long ;
+
+BEGIN {
+ mkdir('./_Inline_test', 0777) unless -e './_Inline_test';
+}
+
+use Inline Config =>
+ DIRECTORY => './_Inline_test';
+
+require Inline::Java ;
+
+
+my %opts = () ;
+GetOptions (\%opts,
+ "d", # debug
+ "s=i", # skip to
+ "o=i", # only
+) ;
+
+
+open(POD, "<Java.pod") or
+ die("Can't open Java.pod file") ;
+my $pod = join("", <POD>) ;
+
+my $del = "\n=for comment\n" ;
+
+my @code_blocks = ($pod =~ m/$del(.*?)$del/gs) ;
+
+my $ps = Inline::Java::portable("ENV_VAR_PATH_SEP_CP") ;
+$ENV{CLASSPATH} .= "$ps" . "[PERL_INLINE_JAVA=Pod_Foo,Pod_Bar]" ;
+
+my $skip_to = $opts{s} || 0 ;
+
+my $cnt = -1 ;
+foreach my $code (@code_blocks){
+ $cnt++ ;
+
+ if ((defined($opts{o}))&&($opts{o} != $cnt)){
+ print "skipped\n" ;
+ next ;
+ }
+
+ if ($cnt < $skip_to){
+ print "skipped\n" ;
+ next ;
+ }
+
+ print "-> Code Block $cnt\n" ;
+
+ $code =~ s/(\n)( )/$1/gs ;
+ $code =~ s/(((END(_OF_JAVA_CODE)?)|STUDY)\')/$1, NAME => "main::main" / ;
+
+ if (($code =~ /SHARED_JVM/)&&($opts{o} != $cnt)){
+ print "skipped\n" ;
+ next ;
+ }
+
+ $code =~ s/print\((.*) \. \"\\n\"\) ; # prints (.*)/{
+ "print (((($1) eq ('$2')) ? \"ok\" : \"not ok ('$1' ne '$2')\") . \"\\n\") ;" ;
+ }/ge ;
+
+ debug($code) ;
+
+ eval $code ;
+ if ($@){
+ die $@ ;
+ }
+}
+
+close(POD) ;
+
+
+sub debug {
+ my $msg = shift ;
+ if ($opts{d}){
+ print $msg ;
+ }
+}
+
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libinline-java-perl.git
More information about the Pkg-perl-cvs-commits
mailing list