.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Inline::Java 3"
.TH Inline::Java 3 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Inline::Java \- Write Perl classes in Java.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&   use Inline Java => <<\*(AqEND_OF_JAVA_CODE\*(Aq ;
\&      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) . "\en") ; # prints 25
\&   print($alu\->subtract(9, 16) . "\en") ; # prints \-7
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Inline::Java\*(C'\fR 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.
.PP
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.
.SH "JDK COMPATIBILITY"
.IX Header "JDK COMPATIBILITY"
As of version 0.62, the minimum JDK supported is JDK 7. This is due to the
"diamond operator" \f(CW\*(C`<>\*(C'\fR used for generic \f(CW\*(C`ArrayList\*(C'\fRs among others.
.SH "USING THE Inline::Java MODULE"
.IX Header "USING THE Inline::Java MODULE"
\&\f(CW\*(C`Inline::Java\*(C'\fR is driven by fundamentally the same idea as other
\&\f(CW\*(C`Inline\*(C'\fR language modules, like \f(CW\*(C`Inline::C\*(C'\fR or \f(CW\*(C`Inline::CPP\*(C'\fR.
Because Java is both compiled and interpreted, the method of getting
your code is different, but overall, using \f(CW\*(C`Inline::Java\*(C'\fR is very similar
to any other \f(CW\*(C`Inline\*(C'\fR language module.
.PP
This section will explain the different ways to \f(CW\*(C`use\*(C'\fR Inline::Java.
For more details on \f(CW\*(C`Inline\*(C'\fR, see 'perldoc Inline'.
.PP
\&\fBBasic Usage\fR
.PP
The most basic form for using \f(CW\*(C`Inline::Java\*(C'\fR is:
.PP
.Vb 1
\&   use Inline Java => \*(AqJava source code\*(Aq ;
.Ve
.PP
Of course, you can use Perl's "here document" style of quoting to make
the code slightly easier to read:
.PP
.Vb 1
\&   use Inline Java => <<\*(AqEND\*(Aq;
\&
\&      Java source code goes here.
\&
\&   END
.Ve
.PP
The source code can also be specified as a filename, a subroutine
reference (the subroutine should return source code), or an array
reference (the array contains lines of source code). This information
is detailed in 'perldoc Inline'.
.PP
In order for \f(CW\*(C`Inline::Java\*(C'\fR to function properly, it needs to know
where to find a Java 2 SDK on your machine. This is done using one
of the following techniques:
.IP 1. 4
Set the J2SDK configuration option to the correct directory
.IP 2. 4
Set the PERL_INLINE_JAVA_J2SDK environment variable to the
correct directory
.PP
If none of these are specified, \f(CW\*(C`Inline::Java\*(C'\fR will use the Java
2 SDK that was specified at install time (see below).
.SH "DEFAULT JAVA 2 SDK"
.IX Header "DEFAULT JAVA 2 SDK"
When \f(CW\*(C`Inline::Java\*(C'\fR was installed, the path to the Java 2 SDK that was
used was stored in a file called default_j2sdk.pl that resides within
the \f(CW\*(C`Inline::Java\*(C'\fR module. You can obtain this path by using the following
command:
.PP
.Vb 1
\&    % perl \-MInline::Java=j2sdk
.Ve
.PP
If you wish to permanently change the default Java 2 SDK that is used
by \f(CW\*(C`Inline::Java\*(C'\fR, edit this file and change the value found there.
If you wish use a different Java 2 SDK temporarily, see the J2SDK
configuration option described below.
.PP
Additionally, you can use the following command to get the list of directories
that you should put in you shared library path when using the JNI extension:
.PP
.Vb 1
\&    % perl \-MInline::Java=so_dirs
.Ve
.SH "CONFIGURATION OPTIONS"
.IX Header "CONFIGURATION OPTIONS"
There are a number of configuration options that dictate the
behavior of \f(CW\*(C`Inline::Java\*(C'\fR:
.IP j2sdk 4
.IX Item "j2sdk"
Specifies the path to your Java 2 SDK.
.Sp
.Vb 1
\&   Ex: j2sdk => \*(Aq/my/java/2/sdk/path\*(Aq
.Ve
.Sp
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.
.IP port 4
.IX Item "port"
Specifies the port number for the server. Default is \-1 (next
available port number), default for SHARED_JVM mode is 7891.
.Sp
.Vb 1
\&   Ex: port => 4567
.Ve
.Sp
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.
.IP host 4
.IX Item "host"
Specifies the host on which the JVM server is running. This option
really only makes sense in SHARED_JVM mode when START_JVM is disabled.
.Sp
.Vb 1
\&   Ex: host => \*(Aqjvm.server.com\*(Aq
.Ve
.Sp
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.
.IP bind 4
.IX Item "bind"
Specifies the IP address on which the JVM server will be listening. By
default the JVM server listens for connections on 'localhost' only.
.Sp
.Vb 2
\&   Ex: bind => \*(Aq192.168.1.1\*(Aq
\&   Ex: bind => \*(Aq0.0.0.0\*(Aq
.Ve
.Sp
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.
.IP startup_delay 4
.IX Item "startup_delay"
Specifies the maximum number of seconds that the Perl script
will try to connect to the Java server. In other words this is the
delay that Perl gives to the Java server to start. Default
is 15 seconds.
.Sp
.Vb 1
\&   Ex: startup_delay => 20
.Ve
.Sp
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.
.IP classpath 4
.IX Item "classpath"
Adds the specified CLASSPATH. This CLASSPATH will only be available
through the user classloader. To set the CLASSPATH globally (which is
most probably what you want to do anyways), use the CLASSPATH
environment variable.
.Sp
.Vb 1
\&   Ex: classpath => \*(Aq/my/other/java/classses\*(Aq
.Ve
.IP jni 4
.IX Item "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.
.Sp
.Vb 1
\&   Ex: jni => 1
.Ve
.Sp
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.
.IP "extra_java_args, extra_javac_args" 4
.IX Item "extra_java_args, extra_javac_args"
Specify extra command line parameters to be passed to, respectively,
the JVM and the Java compiler. Use with caution as some options may
alter normal \f(CW\*(C`Inline::Java\*(C'\fR behavior.
.Sp
.Vb 1
\&   Ex: extra_java_args => \*(Aq\-Xmx96m\*(Aq
.Ve
.Sp
Note: extra_java_args 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.
.IP embedded_jni 4
.IX Item "embedded_jni"
Same as jni, except \f(CW\*(C`Inline::Java\*(C'\fR expects the JVM to already be
loaded and to have loaded the Perl interpreter that is running the
script. This is an advanced feature that should only be need in
very specific circumstances.
.Sp
.Vb 1
\&   Ex: embedded_jni => 1
.Ve
.Sp
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. Also, the embedded_jni option automatically
sets the JNI option.
.IP shared_jvm 4
.IX Item "shared_jvm"
This mode enables multiple processes to share the same JVM. It was
created mainly in order to be able to use \f(CW\*(C`Inline::Java\*(C'\fR under
mod_perl.
.Sp
.Vb 1
\&   Ex: shared_jvm => 1
.Ve
.Sp
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.
.IP start_jvm 4
.IX Item "start_jvm"
When used with shared_jvm, tells \f(CW\*(C`Inline::Java\*(C'\fR whether to start
a new JVM (this is the default) or to expect that one is already
running. This option is useful in combination with the command line interface
described in the BUGS AND DEFICIENCIES section. Default is 1.
.Sp
.Vb 1
\&   Ex: start_jvm => 0
.Ve
.Sp
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.
.IP private 4
.IX Item "private"
In shared_jvm mode, makes every connection to the JVM use a different
classloader so that each connection is isolated from the others.
.Sp
.Vb 1
\&   Ex: private => 1
.Ve
.Sp
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.
.IP debug 4
.IX Item "debug"
Enables debugging info. Debugging now uses levels (1 through 5)
that (loosely) follow these definitions:
.Sp
.Vb 5
\&   1 = Major program steps
\&   2 = Object creation/destruction
\&   3 = Method/member accesses + packet dumps
\&   4 = Everything else
\&   5 = Data structure dumps
\&
\&   Ex: debug => 2
.Ve
.IP debugger 4
.IX Item "debugger"
Starts jdb (the Java debugger) instead of the regular Java JVM.
This option will also cause the Java code to be compiled using the
\&'\-g' switch for extra debugging information. EXTRA_JAVA_ARGS can
be used use to pass extra options to the debugger.
.Sp
.Vb 1
\&   Ex: debugger => 1
.Ve
.IP warn_method_select 4
.IX Item "warn_method_select"
Throws a warning when \f(CW\*(C`Inline::Java\*(C'\fR has to 'choose' between
different method signatures. The warning states the possible
choices and the signature chosen.
.Sp
.Vb 1
\&   Ex: warn_method_select => 1
.Ve
.IP study 4
.IX Item "study"
Takes an array of Java classes that you wish to have
\&\f(CW\*(C`Inline::Java\*(C'\fR learn about so that you can use them inside Perl.
.Sp
.Vb 1
\&   Ex: study => [\*(Aqjava.lang.HashMap\*(Aq, \*(Aqmy.class\*(Aq]
.Ve
.IP autostudy 4
.IX Item "autostudy"
Makes \f(CW\*(C`Inline::Java\*(C'\fR automatically study unknown classes when it
encounters them.
.Sp
.Vb 1
\&   Ex: autostudy => 1
.Ve
.IP package 4
.IX Item "package"
Forces \f(CW\*(C`Inline::Java\*(C'\fR to bind the Java code under the specified
package instead of under the current (caller) package.
.Sp
.Vb 1
\&   Ex: package => \*(Aqmain\*(Aq
.Ve
.IP native_doubles 4
.IX Item "native_doubles"
Normally, \f(CW\*(C`Inline::Java\*(C'\fR stringifies floating point numbers when passing
them between Perl and Java. In certain cases, this can lead to loss of
precision. When native_doubles is set, \f(CW\*(C`Inline::Java\*(C'\fR will send the actual
double bytes in order to preserve precision.
Note: This applies only to doubles, not floats.
Note: This option may not be portable and may not work properly on some
platforms.
.Sp
.Vb 1
\&   Ex: native_doubles => 1
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
Every configuration option listed above, with the exception of STUDY,
can be specified using an environment variable named using the
following convention:
.PP
.Vb 1
\&   PERL_INLINE_JAVA_<option name>
.Ve
.PP
For example, you can specify the JNI option using the
PERL_INLINE_JAVA_JNI environment variable.
.PP
Note that environment variables take precedence over options specified
in the script itself.
.PP
Under Win32, you can also use set the PERL_INLINE_JAVA_COMMAND_COM
environment variable to a true value to indicate that you are using
the command.com shell. However, \f(CW\*(C`Inline::Java\*(C'\fR should normally be
able to determine this on its own.
.SH "CLASSES AND OBJECTS"
.IX Header "CLASSES AND OBJECTS"
Because Java is object oriented, any interface between Perl and Java
needs to support Java classes adequately.
.PP
Example:
.PP
.Vb 4
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      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() . "\en") ; # prints data
\&   $obj\->set_data("new data") ;
\&   print($obj\->get_data() . "\en") ; # prints new data
.Ve
.PP
\&\f(CW\*(C`Inline::Java\*(C'\fR created a new namespace called \f(CW\*(C`main::Pod_1\*(C'\fR and
created the following functions:
.PP
.Vb 6
\&   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 { ... }
.Ve
.PP
Note that only the public methods are exported to Perl.
.PP
Inner classes are also supported, you simply need to supply a reference
to an outer class object as the first parameter of the constructor:
.PP
.Vb 4
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      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} . "\en") ; # prints Pod_2_Inner
.Ve
.SH METHODS
.IX Header "METHODS"
In the previous example we have seen how to call a method. You can also
call static methods in the following manner:
.PP
.Vb 4
\&   print Pod_1\->get_sdata() . "\en" ; # prints static data
\&   # or
\&   my $obj = new Pod_1() ;
\&   print $obj\->get_sdata() . "\en" ; # prints static data
.Ve
.PP
You can pass any kind of Perl scalar or any Java object to a method. It
will be automatically converted to the correct type:
.PP
.Vb 7
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      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} . "\en") ; # prints 5
.Ve
.PP
will work fine. These objects can be of any type, even if these types
are not known to \f(CW\*(C`Inline::Java\*(C'\fR. This is also true for return types:
.PP
.Vb 2
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      import java.util.* ;
\&
\&      class Pod_4 {
\&         public Pod_4(){
\&         }
\&
\&         public HashMap get_hash(){
\&            HashMap<String, String> h = new HashMap<>() ;
\&            h.put("key", "value") ;
\&
\&            return h ;
\&         }
\&
\&         public String do_stuff_to_hash(HashMap<String, String> h){
\&           return (String)h.get("key") ;
\&         }
\&      }
\&   END
\&
\&   my $obj = new Pod_4() ;
\&   my $h = $obj\->get_hash() ;
\&   print($obj\->do_stuff_to_hash($h) . "\en") ; # prints value
.Ve
.PP
Objects of types unknown to Perl can exist in the Perl space, you just
can't call any of their methods. See the STUDYING section for more
information on how to tell \f(CW\*(C`Inline::Java\*(C'\fR to learn about these classes.
.SH "MEMBER VARIABLES"
.IX Header "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:
.PP
.Vb 2
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      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} . "\en") ; # prints 2
\&   my $hm1 = $obj\->{hm} ; # instance way
\&   my $hm2 = $Pod_5::hm ; # static way
.Ve
.PP
Note: Watch out for typos when accessing members in the static fashion,
\&'use strict' will not catch them since they have a package name...
.SH ARRAYS
.IX Header "ARRAYS"
You can also send, receive and modify arrays. This is done simply by
using Perl lists:
.PP
.Vb 2
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      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 . "\en") ; # prints 7
\&
\&   my $a1 = $obj\->f(["a", "b", "c"]) ; # String []
\&   my $a2 = $obj\->f([
\&      ["00", "01"],
\&      ["10", "11"],
\&   ]) ; # String [][]
\&   print($a2\->[1]\->[0] . "\en") ; # prints 10
.Ve
.SH EXCEPTIONS
.IX Header "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:
.PP
.Vb 2
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      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 . "\en") ; # prints ouch!
\&      }
\&      else{
\&         # It wasn\*(Aqt a Java exception after all...
\&         die $@ ;
\&      }
\&   }
.Ve
.PP
What's important to understand is that $@ actually contains a reference
to the Throwable object that was thrown by Java. The \fBgetMessage()\fR function
is really a method of the java.lang.Exception class. So if Java is throwing
a custom exception you have in your code, you will have access to that
exception object's public methods just like any other Java object in
\&\f(CW\*(C`Inline::Java\*(C'\fR.
Note: \f(CW\*(C`Inline::Java\*(C'\fR uses eval under the hood, so it recommended that you
store any exception in a temporary variable before processing it, especially
f you will be calling other \f(CW\*(C`Inline::Java\*(C'\fR functions. 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.
.SH FILEHANDLES
.IX Header "FILEHANDLES"
Java filehandles (java.io.Reader, java.io.Writer, java.io.InputStream or
java.io.OutputStream objects) can be wrapped the \f(CW\*(C`Inline::Java::Handle\*(C'\fR
class to allow reading or writing from Perl. Here's an example:
.PP
.Vb 2
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      import java.io.* ;
\&
\&      class Pod_91 {
\&         public static Reader getReader(String file) throws FileNotFoundException {
\&           return new FileReader(file) ;
\&         }
\&      }
\&   END
\&
\&    my $o = Pod_91\->getReader(\*(Aqt/t13.txt\*(Aq) ;
\&    my $h = Inline::Java::Handle\->new($o) ;
\&    # read one line
\&    my $text = <$h>;
\&    chomp $text;
\&    print($text . "\en") ; # prints 1
.Ve
.PP
What's important to understand is that the returned \f(CW\*(C`Inline::Java::Handle\*(C'\fR
object actually contains a reference to the Java reader or writer.
It is probably a good idea to undef it once you have completed the I/O
operations so that the underlying Java object may be freed.
.SH CALLBACKS
.IX Header "CALLBACKS"
See Inline::Java::Callbacks for more information on making callbacks.
.SH STUDYING
.IX Header "STUDYING"
As of version 0.21, \f(CW\*(C`Inline::Java\*(C'\fR 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:
.PP
.Vb 5
\&   use Inline (
\&      Java => \*(Aqstudy\*(Aq,
\&      study => [\*(Aqjava.util.HashMap\*(Aq],
\&      autostudy => 1,
\&   ) ;
\&
\&   my $hm = new java::util::HashMap() ;
\&   $hm\->put("key", "value") ;
\&   my $val = $hm\->get("key") ;
\&   print($val . "\en") ; # prints value
.Ve
.PP
If you do not wish to put any Java code inside your Perl script, you must
use the string 'study' as your code. This will skip the build section.
.PP
You can also use the autostudy option to tell \f(CW\*(C`Inline::Java\*(C'\fR that you wish
to study all classes that it comes across:
.PP
.Vb 2
\&   use Inline Java => <<\*(AqEND\*(Aq, 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 . "\en") ; # prints value
.Ve
.PP
In this case \f(CW\*(C`Inline::Java\*(C'\fR intercepts the return value of the \fBget_hm()\fR
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.
.PP
In some cases you may not know which classes to study until runtime. In
these cases you can use the \fBstudy_classes()\fR function:
.PP
.Vb 5
\&   use Inline (
\&      Java => \*(Aqstudy\*(Aq,
\&      study => [],
\&   ) ;
\&   use Inline::Java qw(study_classes) ;
\&
\&   study_classes([\*(Aqjava.util.HashMap\*(Aq], undef) ;
\&   my $hm = new java::util::HashMap() ;
\&   $hm\->put("key", "value") ;
\&   my $val = $hm\->get("key") ;
\&   print($val . "\en") ; # prints value
.Ve
.PP
The \fBstudy_classes()\fR function takes 2 arguments, a reference to an array of
class names (like the STUDY configuration option) and the name of the
package in which to bind those classes. If the name of the package is
undefined, the classes will be bound to the current (caller) package.
.PP
Note: You can only specify the names of packages in which you have
previously "used" \f(CW\*(C`Inline::Java\*(C'\fR.
.SH "TYPE CASTING"
.IX Header "TYPE CASTING"
Sometimes you need to manipulate a Java object using a specific
subtype. That's when type casting is necessary. Here's an
example of this:
.PP
.Vb 6
\&   use Inline (
\&      Java => \*(Aqstudy\*(Aq,
\&      study => [\*(Aqjava.util.HashMap\*(Aq],
\&      autostudy => 1,
\&   ) ;
\&   use Inline::Java qw(cast) ;
\&
\&   my $hm = new java::util::HashMap() ;
\&   $hm\->put(\*(Aqkey\*(Aq, \*(Aqvalue\*(Aq) ;
\&
\&   my $entries = $hm\->entrySet()\->toArray() ;
\&   foreach my $e (@{$entries}){
\&     # print($e\->getKey() . "\en") ; # No!
\&     print(cast(\*(Aqjava.util.Map$Entry\*(Aq, $e)\->getKey() . "\en") ; # prints key
\&   }
.Ve
.PP
In this case, \f(CW\*(C`Inline::Java\*(C'\fR knows that \f(CW$e\fR is of type java.util.HashMap$Entry.
The problem is that this type is not public, and therefore we can't access
the object through that type. We must cast it to a java.util.Map$Entry, which
is a public interface and will allow us to access the \fBgetKey()\fR method.
.PP
You can also use type casting to force the selection of a specific method
signature for methods that have multiple signatures. See examples similar
to this in the "TYPE COERCING" section below.
.SH "TYPE COERCING"
.IX Header "TYPE COERCING"
Type coercing is the equivalent of casting for primitives types
and arrays. It is used to force the selection if a specific method
signature when \f(CW\*(C`Inline::Java\*(C'\fR has multiple choices. The coerce
function returns a special object that can only be used when calling
Java methods or assigning Java members. Here is an example:
.PP
.Vb 4
\&   use Inline Java => <<\*(AqEND\*(Aq ;
\&      class Pod_101 {
\&         public Pod_101(){
\&         }
\&
\&         public String f(int i){
\&            return "int" ;
\&         }
\&
\&         public String f(char c){
\&            return "char" ;
\&         }
\&      }
\&   END
\&
\&   my $obj = new Pod_101() ;
\&   print($obj\->f(\*(Aq5\*(Aq) . "\en") ; # prints int
.Ve
.PP
In this case, \f(CW\*(C`Inline::Java\*(C'\fR 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:
.PP
.Vb 4
\&   use Inline::Java qw(coerce) ;
\&   $obj\->f(coerce(\*(Aqchar\*(Aq, \*(Aq5\*(Aq)) ;
\&   # or
\&   $obj\->f(Inline::Java::coerce(\*(Aqchar\*(Aq, \*(Aq5\*(Aq)) ;
.Ve
.PP
The coerce function forces the selection of the matching signature. Note that
the coerce must match the argument type exactly. Coercing to a class that
extends the argument type will not work.
.PP
Another case where type coercing is needed is when one wants to pass an array
as a java.lang.Object:
.PP
.Vb 4
\&   use Inline Java => <<\*(AqEND\*(Aq;
\&      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!
.Ve
.PP
The reason why this will not work is simple. When \f(CW\*(C`Inline::Java\*(C'\fR 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
three-parameter version of the coerce function to do this:
.PP
.Vb 4
\&   $obj\->{o} = Inline::Java::coerce(
\&     "java.lang.Object",
\&     [1, 2, 3],
\&     "[Ljava.lang.String;") ;
.Ve
.PP
This tells \f(CW\*(C`Inline::Java\*(C'\fR to validate your Perl list as a String [], and
then coerce it as an Object.
.PP
Here is how to construct the array type representations:
.PP
.Vb 3
\&  [<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
.Ve
.PP
This is described in more detail in most Java books that talk about
reflection.
.PP
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 coerce:
.PP
.Vb 1
\&   $obj\->{o} = $obj\->{a} ;
.Ve
.SH "JNI vs CLIENT/SERVER MODES"
.IX Header "JNI vs CLIENT/SERVER MODES"
Starting in version 0.20, it is possible to use the JNI (Java Native
Interface) extension. This enables \f(CW\*(C`Inline::Java\*(C'\fR 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.
.PP
If you have built the JNI extension, you must enable it explicitly by doing
one of the following:
.IP 1. 4
Set the JNI configuration option to 1
.IP 2. 4
Set the PERL_INLINE_JAVA_JNI environment variable to 1
.PP
Note: \f(CW\*(C`Inline::Java\*(C'\fR 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.
.PP
See README.JNI for more information about the JNI extension.
.SH SHARED_JVM
.IX Header "SHARED_JVM"
Starting with version 0.30, the \f(CW\*(C`Inline::Java\*(C'\fR JVM can now be shared between
multiple processes. The first process to start creates the JVM but does not
shut it down on exit. All other processes can then connect as needed to the JVM.
If any of these other processes where created by forking the parent process,
the Inline::Java\->\fBreconnect_JVM()\fR function must be called in the child to get
a fresh connection to the JVM. Ex:
.PP
.Vb 11
\&   use Inline (
\&      Java => <<\*(AqEND\*(Aq,
\&         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} . "\en") ; # prints 6
.Ve
.PP
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.
.PP
Note: The Java System.out stream is closed in SHARED_JVM mode.
.SH "USING Inline::Java IN A CGI"
.IX Header "USING Inline::Java IN A CGI"
If you want to use \f(CW\*(C`Inline::Java\*(C'\fR in a CGI script, do the following:
.PP
.Vb 10
\&   use CGI ;
\&   use Inline (
\&      Java => <<\*(AqEND\*(Aq,
\&         class Pod_counter {
\&            public static int cnt = 0 ;
\&            public Pod_counter(){
\&               cnt++ ;
\&            }
\&         }
\&   END
\&      shared_jvm => 1,
\&      directory => \*(Aq/somewhere/your/web/server/can/write\*(Aq,
\&   ) ;
\&
\&   my $c = new Pod_counter() ;
\&   my $q = new CGI() ;
\&   print
\&      $q\->start_html() .
\&      "This page has been accessed " . $c\->{cnt} . " times." .
\&      $q\->end_html() ;
.Ve
.PP
In this scenario, the first CGI to execute will start the JVM, but does
not shut it down on exit. Subsequent CGI, since they have the shared_jvm
option enabled, will try to connect to the 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. The JVM will be
killed when Apache is shut down.
.PP
See the BUGS AND DEFICIENCIES section if you have problems starting
the shared_jvm server in a CGI.
.SH "USING Inline::Java UNDER MOD_PERL"
.IX Header "USING Inline::Java UNDER MOD_PERL"
Here is an example of how to use \f(CW\*(C`Inline::Java\*(C'\fR under mod_perl:
.PP
.Vb 10
\&   use Apache2::Const qw(:common) ;
\&   use Inline (
\&      Java => <<\*(AqEND\*(Aq,
\&         class Pod_counter {
\&            public static int cnt = 0 ;
\&            public Pod_counter(){
\&               cnt++ ;
\&            }
\&         }
\&   END
\&      shared_jvm => 1,
\&      directory => \*(Aq/somewhere/your/web/server/can/write\*(Aq,
\&   ) ;
\&
\&   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 OK ;
\&   }
.Ve
.PP
See USING Inline::Java IN A CGI for more details.
.PP
If you are using ModPerl::Registry, make sure to use the \f(CW\*(C`PACKAGE\*(C'\fR
configuration option to specify the package in which \f(CW\*(C`Inline::Java\*(C'\fR
should bind the Java code, since ModPerl::Registry will place your
code in a package with a unpredictable name.
.PP
See the BUGS AND DEFICIENCIES section if you have problems starting
the shared_jvm server under MOD_PERL.
.SS "Preloading and PerlChildInitHandler"
.IX Subsection "Preloading and PerlChildInitHandler"
If you are loading \f(CW\*(C`Inline::Java\*(C'\fR during your server startup (common practice to
increase shared memory and reduce run time) and you are using \f(CW\*(C`shared_jvm\*(C'\fR, then
your Apache processes will all share the same socktd connection to that JVM.
This will result in garbled communication and strange errors (like "Can't receive packet from JVM", "Broken pipe", etc).
.PP
To fix this you need to tell Apache that after each child process has forked they
each need to create their own connections to the JVM. This is done during the
\&\f(CW\*(C`ChildInit\*(C'\fR stage.
.PP
For Apache 1.3.x this could look like:
.PP
.Vb 2
\&   # in httpd.conf
\&   PerlChildInitHandler MyProject::JavaReconnect
.Ve
.PP
And \f(CW\*(C`MyProject::JavaReconnect\*(C'\fR could be as simple as this:
.PP
.Vb 3
\&   package MyProject::JavaReconnect;
\&   sub handler($$) { Inline::Java::reconnect_JVM() }
\&   1;
.Ve
.SH "BUGS AND DEFICIENCIES"
.IX Header "BUGS AND DEFICIENCIES"
When reporting a bug, please do the following:
.PP
.Vb 4
\& \- 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.
.Ve
.PP
Here are some things to watch out for:
.IP 1. 4
You shouldn't name any of 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.
.IP 2. 4
If you upgrade \f(CW\*(C`Inline::Java\*(C'\fR from a previous version, be sure to delete
your _Inline directory so that \f(CW\*(C`Inline::Java\*(C'\fR's own Java classes get
rebuilt to match the Perl code.
.IP 3. 4
Under certain environments, i.e. CGI or mod_perl, the JVM cannot start
properly because of the way these environments set up STDIN and STDOUT.
In these cases, you may wish to control the JVM (in shared mode) manually
using the following commands:
.Sp
.Vb 4
\&    % perl \-MInline::Java::Server=status
\&    % perl \-MInline::Java::Server=start
\&    % perl \-MInline::Java::Server=stop
\&    % perl \-MInline::Java::Server=restart
.Ve
.Sp
You can specify \f(CW\*(C`Inline::Java\*(C'\fR options by setting the proper
environment variables, and you can also set the _Inline directory by using
the PERL_INLINE_JAVA_DIRECTORY environment variable.
.Sp
In addition, you may also wish to set the start_jvm option to 0 in your scripts
to prevent them from trying to start their own JVM if they can't find one,
thereby causing problems.
.IP 4. 4
Because of problems with modules \f(CW\*(C`Inline::Java\*(C'\fR depends on, the usage of paths
containing spaces is not fully supported on all platforms. This applies to the
installation directory as well as the path for J2SDK and CLASSPATH elements.
.IP 5. 4
Even though it is run through a profiler regularly, \f(CW\*(C`Inline::Java\*(C'\fR is relatively
slow compared to native Perl or Java.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Inline::Java::Callback, Inline::Java::PerlNatives,
Inline::Java::PerlInterpreter.
.PP
For information about using \f(CW\*(C`Inline\*(C'\fR, see Inline.
.PP
For information about other Inline languages, see Inline-Support.
.PP
\&\f(CW\*(C`Inline::Java\*(C'\fR's mailing list is <inline@perl.org>.
To subscribe, send an email to <inline\-subscribe@perl.org>
.SH AUTHOR
.IX Header "AUTHOR"
Patrick LeBoutillier <patl@cpan.org> is the author of Inline::Java.
.PP
Brian Ingerson <ingy@cpan.org> is the author of Inline.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2001\-2005, Patrick LeBoutillier.
.PP
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 for more
details.