Inline::Java 0.30
Perl
module
-
Part of CPAN
distribution
Inline-Java 0.30.
Inline::Java - Write Perl classes in Java.
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
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.
The 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.
Inline::Java is driven by fundamentally the same idea as other
Inline language modules, like Inline::C or Inline::CPP.
Because Java is both compiled and interpreted, the method of getting
your code is different, but overall, using Inline::Java is very similar
to any other Inline language module.
This section will explain the different ways to use Inline::Java.
For more details on Inline, see 'perldoc Inline'.
The most basic form for using 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 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
There are a number of configuration options that dictate the
behavior of 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 sugnature 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 thme 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'] ;
Because Java is object oriented, any interface between Perl and Java
needs to support Java classes adequately.
Example:
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 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" ;
The output from this program is:
new Foo object being created
data
new data
Inline::Java created a new namespace called 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
Inline::Java you cannot create public classes because Java
requires that they be defined in a .java file of the same
name (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:
use Inline Java => <<'END';
class Foo {
public Foo() {
}
public class Bar {
public Bar() {
}
}
}
END
my $obj = new Foo() ;
my $obj2 = new Bar($obj) ;
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:
use Inline Java => <<'END';
class Foo2 {
public Foo2(int i, String j, Foo k) {
...
}
}
END
my $obj = new Foo() ;
my $obj2 = new Foo2(5, "toto", $obj) ;
will work fine. These objects can be of any type, even if these types
are not known to Inline::Java. This is also true for return types:
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->gethash() ;
$obj->do_stuff_to_hash($h) ;
Objects of types unknown to Perl can exist in the Perl space, you just
can't call any of their methods.
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:
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
Note: Watch out for typos when accessing members in the static fashion,
'use strict' will not catch them since they have a package name...
You can also send and receive arrays. This is done by using Perl lists:
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] ; # "10"
Sometimes when a class as many signatures for the same method,
Inline::Java will have to select one of the signatures based on
the arguments that are passed:
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') ;
In this case, 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';
Object o ;
int a[] = {1, 2, 3} ;
class Foo7 {
public Foo7() {
}
}
END
my $obj = new Foo7() ;
$obj->{o} = [1, 2, 3] ; # No!
The reason why this will not work is simple. When 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 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} ;
As of version 0.21, 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:
use Inline (
Java => 'STUDY',
STUDY => ['java.lang.HashMap'],
) ;
my $hm = new java::lang::HashMap() ;
$hm->put("key", "value") ;
my $v = $hm->get("key") ;
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 Inline::Java that you wish
to study all classes that it comes across:
use Inline (
Java => 'DATA',
AUTOSTUDY => 1,
) ;
my $obj = new Foo8() ;
my $hm = $obj->get_hm() ;
$hm->put("key", "value") ;
my $v = $hm->get("key") ;
__END__
__Java__
import java.util.* ;
class Foo8 {
public Foo8() {
}
public HashMap get_hm(){
HashMap hm = new HashMap() ;
return hm ;
}
}
In this case 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.
If you wish to use more than one 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:
package Foo ;
use Inline (
Java => '<<END',
class Foo {
public Foo() {
}
}
END
NAME => "Foo",
CLASSPATH => "[PERL_INLINE_JAVA=Foo, Bar]",
) ;
package Bar ;
use Inline (
Java => '<<END',
class Bar {
public Bar() {
}
}
END
NAME => "Bar",
) ;
package main ;
my $f = new Foo() ;
my $b = new Bar() ;
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.
Starting in version 0.20, it is possible to use the JNI (Java Native
Interface) extension. This enables 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: 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.
Starting with version 0.30, the 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:
use Inline (
Java => '<<END',
import java.util.* ;
class t {
public t(){
}
}
END
SHARED_JVM => 1,
) ;
my $t = new t() ;
my $nb = 5 ;
for (my $i = 0 ; $i < $nb ; $i++){
if (! fork()){
Inline::Java::reconnect_JVM() ;
$t = new $t() ;
}
}
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.
Please note that the SHARED_JVM feature does not work in JNI mode.
This is an ALPHA release of 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 (use 'fix' option)
It likely will work with many other configurations.
This is how Inline::Java works. Once the user's code is compiled by the
javac binary, 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 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.
For information about using Inline, see Inline.
For information about other Inline languages, see Inline-Support.
Inline::Java's mailing list is inline@perl.org
The subscribe, send email to inline-subscribe@perl.org
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:
- You can't use the "package" Java directive when using
Inline::Java.
- 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 (
Inline::Java can't work this way).
Patrick LeBoutillier <patl@cpan.org>
Brian Ingerson <INGY@cpan.org> is the author of Inline.
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)
|
