Inline::Java(3pm)

📦

version 0.67 · 6 versions

0.67 · debian trixie, ubuntu resolute (latest)
0.67 · arch rolling
0.67 · ubuntu stonking
0.67 · ubuntu jammy
0.67 · ubuntu noble
0.67 · debian bookworm

, in debian trixie, ubuntu resolute

Inline::Java(3pm) 🦋 the Perl manual page, bestie edition 💅

okay so this is the whole Inline::Java(3pm) manpage and I am obsessed with it, so let's get into it fr fr 💖

NAME ✨

Inline::Java — Write Perl classes in Java. 🎀

SYNOPSIS 🌸

okay so here's the vibe — you literally just drop Java code straight into your Perl like it's no big deal:

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

like. it just works. no cap. 🔥

DESCRIPTION 💜

So the Inline::Java module lets you put your Java source code directly "inline" inside a Perl script or module. That's literally the whole personality. 💅

Here's the lore: a Java compiler gets launched, and your Java code gets compiled. Then Perl goes and asks the Java classes "hey bestie what public methods do you have" and those classes + methods become available to your Perl program as if they'd been written in Perl the entire time. iconic behaviour honestly. 🫶

And the little interrogation moment — where Perl asks the Java classes about their public methods — happens the first time you run your Java code. After that the namespace is cached, so all the calls after that just use the cached version. efficient queen. 👑

JDK COMPATIBILITY 🌈

As of version 0.62, the minimum JDK supported is JDK 7. and why, you ask? it's giving "diamond operator" — specifically the <> used for generic ArrayLists among others. so like. upgrade bestie. 💀

USING THE Inline::Java MODULE ✨

Inline::Java is driven by fundamentally the same idea as the other Inline language modules, like Inline::C or Inline::CPP. 🧚

The difference? 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. same energy, different pipeline. 💅

This section is gonna explain the different ways to "use" Inline::Java. For more details on Inline itself, see perldoc Inline. 📖

Basic Usage 🎀

The most basic form for using Inline::Java is:

use Inline Java => 'Java source code' ;

And of course you can use Perl's "here document" style of quoting to make the code slightly easier to read, because we love readability:

use Inline Java => <<'END';

   Java source code goes here.

END

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). All of that is detailed in perldoc Inline. 🫶

Now — for Inline::Java 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:

Set the J2SDK configuration option to the correct directory
Set the PERL_INLINE_JAVA_J2SDK environment variable to the correct directory

If none of these are specified, Inline::Java will use the Java 2 SDK that was specified at install time (see below). 👇

DEFAULT JAVA 2 SDK 💖

When Inline::Java was installed, the path to the Java 2 SDK that was used got stored in a file called default_j2sdk.pl that resides within the Inline::Java module. 🗂️

You can obtain this path by using the following command:

% perl -MInline::Java=j2sdk

If you wish to permanently change the default Java 2 SDK that is used by Inline::Java, edit this file and change the value found there. If you wish to use a different Java 2 SDK temporarily, see the J2SDK configuration option described below. 💅

Additionally, you can use the following command to get the list of directories that you should put in your shared library path when using the JNI extension:

% perl -MInline::Java=so_dirs

CONFIGURATION OPTIONS ⭐

There are a number of configuration options that dictate the behavior of Inline::Java. buckle up bestie, there's a lot but they're all important 🫶

j2sdk — Specifies the path to your Java 2 SDK.

Ex: j2sdk => '/my/java/2/sdk/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. 💀

port — Specifies the port number for the server. Default is -1 (next available port number), default for SHARED_JVM mode is 7891.

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. 💀

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.

Ex: host => 'jvm.server.com'

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. 💀

bind — Specifies the IP address on which the JVM server will be listening. By default the JVM server listens for connections on 'localhost' only.

Ex: bind => '192.168.1.1'
Ex: bind => '0.0.0.0'

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 words 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. 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.

Ex: classpath => '/my/other/java/classses'

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 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. 💀

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 Inline::Java behavior. ⚠️

Ex: extra_java_args => '-Xmx96m'

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. 💀

embedded_jni — Same as jni, except Inline::Java 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 needed in very specific circumstances. 🧚

Ex: embedded_jni => 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. Also, the embedded_jni option automatically sets the JNI option. 💀

shared_jvm — This mode enables multiple processes to share the same JVM. It was created mainly in order to be able to use 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. 💀

start_jvm — When used with shared_jvm, tells Inline::Java 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.

Ex: start_jvm => 0

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. 💀

private — In shared_jvm mode, makes every connection to the JVM use a different classloader so that each connection is isolated from the others. 🛡️

Ex: private => 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. Debugging now uses levels (1 through 5) that (loosely) follow these definitions:

1 = Major program steps
2 = Object creation/destruction
3 = Method/member accesses + packet dumps
4 = Everything else
5 = Data structure dumps

Ex: debug => 2

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 to pass extra options to the debugger. 🐛

Ex: debugger => 1

warn_method_select — Throws a warning when 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 Inline::Java learn about so that you can use them inside Perl. 📚

Ex: study => ['java.lang.HashMap', 'my.class']

autostudy — Makes Inline::Java automatically study unknown classes when it encounters them. 🤓

Ex: autostudy => 1

package — Forces Inline::Java to bind the Java code under the specified package instead of under the current (caller) package. 📦

Ex: package => 'main'

native_doubles — Normally, Inline::Java 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, Inline::Java 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. 💀

Ex: native_doubles => 1

okay that's the config section bestie, and there's still so much more to come — more parts incoming, don't go anywhere 🫶✨

✨ ENVIRONMENT VARIABLES ✨

Okay bestie so every single config option we just talked about — literally every one — except for STUDY, can also be set with an environment variable. The naming convention is giving very much "follow the pattern or perish":

PERL_INLINE_JAVA_<option name>

So like, want to set the JNI option? Just do it with the PERL_INLINE_JAVA_JNI environment variable. Easy. Slay. 💅

🚨 Heads up queen: environment variables take precedence over options you specified in the script itself. So the env var wins the argument. Periodt.

Under Win32, you can also set the PERL_INLINE_JAVA_COMMAND_COM environment variable to a true value to say "hey I'm using the command.com shell." But ngl, Inline::Java should normally be able to figure that out on its own, so it's lowkey just a backup plan. 🙈

👑 CLASSES AND OBJECTS 👑

Java is object oriented (iykyk), so any interface between Perl and Java has to support Java classes properly. No half-measures.

Example time, bestie:

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

So Inline::Java created a whole new namespace called main::Pod_1 and dropped these functions into it:

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 { ... }

And here's the tea: only the public methods get exported to Perl. Your private stuff stays private, as it should. 🔒

Inner classes are supported too! You just gotta hand over a reference to an outer class object as the first parameter of the constructor. Like this:

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

Nested class realness. 🪆

💖 METHODS 💖

So in that last example we saw how to call a method. But bestie, you can also call static methods like this:

print Pod_1->get_sdata() . "\n" ; # prints static data
# or
my $obj = new Pod_1() ;
print $obj->get_sdata() . "\n" ; # prints static data

Two roads, same destination. 🛣️

You can pass any kind of Perl scalar or any Java object to a method, and it gets auto-converted to the correct type. The way that just works? Iconic.

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

That'll work fine. And these objects can be of any type, even if Inline::Java has literally never heard of those types. Same goes for return types:

use Inline Java => <<'END' ;
   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) . "\n") ; # prints value

Objects of types that Perl doesn't know about can absolutely exist in Perl space — you just can't call any of their methods. Sad but true. 😭 Wanna fix that? Check out the STUDYING section for how to tell Inline::Java to learn about these classes.

🎀 MEMBER VARIABLES 🎀

You can also access all public member variables (static or not) from Perl. And just like with method arguments, the types of these variables do not need to be known to Perl:

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_5::hm ; # static way

⚠️ Note: watch out for typos when you're accessing members the static way! 'use strict' will not catch them because they've got a package name, so it's just gonna vibe along silently while you cry. 🙈

🌈 ARRAYS 🌈

You can send, receive and modify arrays too! And it's literally just Perl lists. Chef's kiss. 👩‍🍳💋

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

Nested arrays? We love to see it. 🦋

🫶 EXCEPTIONS 🫶

Okay so as of 0.31, you can catch exceptions as objects when Java throws them. You do it with the regular Perl exception tools: eval and $@. There's also a helper function named caught that helps you figure out what type of exception you're dealing with. Here's a typical use case:

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 $@ ;
   }
}

Here's the part that matters, so pay attention bestie: $@ actually contains a reference to the Throwable object that Java threw. So getMessage() is really a method of the java.lang.Exception class. Meaning if Java is throwing a custom exception you wrote yourself, you get access to that exception object's public methods just like any other Java object in Inline::Java. So powerful. 🔥

😭 Note: Inline::Java uses eval under the hood, so it's recommended that you store any exception in a temporary variable before processing it — especially if you're gonna be calling other Inline::Java functions. It's also probably a good idea to undef $@ once you've handled a Java exception, or else the object still holds a reference until $@ gets reset by the next eval. Clean up after yourself, queen. 🧹

🍓 FILEHANDLES 🍓

Java filehandles (java.io.Reader, java.io.Writer, java.io.InputStream or java.io.OutputStream objects) can be wrapped by the Inline::Java::Handle class to allow reading or writing from Perl. Example incoming:

use Inline Java => <<'END' ;
   import java.io.* ;

   class Pod_91 {
      public static Reader getReader(String file) throws FileNotFoundException {
        return new FileReader(file) ;
      }
   }
END

 my $o = Pod_91->getReader('t/t13.txt') ;
 my $h = Inline::Java::Handle->new($o) ;
 # read one line
 my $text = <$h>;
 chomp $text;
 print($text . "\n") ; # prints 1

So the important bit to understand: that returned Inline::Java::Handle object actually contains a reference to the Java reader or writer. And it's probably a good idea to undef it once you're done with your I/O operations, so the underlying Java object can be freed. Let it go, let it go. 🧊

⭐ CALLBACKS ⭐

Check out Inline::Java::Callbacks for more info on making callbacks. Go forth, bestie. 💜

🧠 STUDYING (aka Inline::Java goes to school 💅)

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. Fr fr, you're 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.util.HashMap'],
   autostudy => 1,
) ;

my $hm = new java::util::HashMap() ;
$hm->put("key", "value") ;
my $val = $hm->get("key") ;
print($val . "\n") ; # prints value

If you do not wish to put any Java code inside your Perl script, you must use the string 'study' as your code. That skips the build section entirely. no notes ✨

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 => <<'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

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. iconic behaviour honestly.

In some cases you may not know which classes to study until runtime. In these cases you can use the study_classes() function:

use Inline (
   Java => 'study',
   study => [],
) ;
use Inline::Java qw(study_classes) ;

study_classes(['java.util.HashMap'], undef) ;
my $hm = new java::util::HashMap() ;
$hm->put("key", "value") ;
my $val = $hm->get("key") ;
print($val . "\n") ; # prints value

The study_classes() 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.

Note: You can only specify the names of packages in which you have previously "used" Inline::Java. that's the rule bestie 😭

🦋 TYPE CASTING (glow-up for your objects)

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:

use Inline (
   Java => 'study',
   study => ['java.util.HashMap'],
   autostudy => 1,
) ;
use Inline::Java qw(cast) ;

my $hm = new java::util::HashMap() ;
$hm->put('key', 'value') ;

my $entries = $hm->entrySet()->toArray() ;
foreach my $e (@{$entries}){
  # print($e->getKey() . "\n") ; # No!
  print(cast('java.util.Map$Entry', $e)->getKey() . "\n") ; # prints key
}

In this case, Inline::Java knows that $e 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 getKey() method. 💅

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.

🎀 TYPE COERCING (same energy, but for primitives)

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 Inline::Java 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:

use Inline Java => <<'END' ;
   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('5') . "\n") ; # prints int

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(coerce) ;
$obj->f(coerce('char', '5')) ;
# or
$obj->f(Inline::Java::coerce('char', '5')) ;

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. 🫶

Another case where type coercing is needed 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 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 three-parameter version of the coerce function to do this:

$obj->{o} = Inline::Java::coerce(
  "java.lang.Object",
  [1, 2, 3],
  "[Ljava.lang.String;") ;

This tells Inline::Java to validate your Perl list as a String [], and then coerce it as an Object. slay 🌈

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 coerce:

$obj->{o} = $obj->{a} ;

🔥 JNI vs CLIENT/SERVER MODES

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. ⚡

If you have built the JNI extension, you must enable it explicitly 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. pick a lane bestie 💀

See README.JNI for more information about the JNI extension.

👑 SHARED_JVM

Starting with version 0.30, the Inline::Java 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->reconnect_JVM() function must be called in the child to get a fresh connection to the JVM. Ex:

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

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.

Note: The Java System.out stream is closed in SHARED_JVM mode. 🫠

🌸 USING Inline::Java IN A CGI

If you want to use Inline::Java in a CGI script, do the following:

use CGI ;
use Inline (
   Java => <<'END',
      class Pod_counter {
         public static int cnt = 0 ;
         public Pod_counter(){
            cnt++ ;
         }
      }
END
   shared_jvm => 1,
   directory => '/somewhere/your/web/server/can/write',
) ;

my $c = new Pod_counter() ;
my $q = new CGI() ;
print
   $q->start_html() .
   "This page has been accessed " . $c->{cnt} . " times." .
   $q->end_html() ;

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. 💀➡️✨

See the BUGS AND DEFICIENCIES section if you have problems starting the shared_jvm server in a CGI.

🌈 USING Inline::Java UNDER MOD_PERL 🌈

ok so bestie, if you wanna run Inline::Java under mod_perl, here's the whole vibe — an actual working example, no cap:

use Apache2::Const qw(:common) ;
use Inline (
   Java => <<'END',
      class Pod_counter {
         public static int cnt = 0 ;
         public Pod_counter(){
            cnt++ ;
         }
      }
END
   shared_jvm => 1,
   directory => '/somewhere/your/web/server/can/write',
) ;

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 ;
}

see the USING Inline::Java IN A CGI section for more deets — it's giving sibling energy fr.

And if you're on ModPerl::Registry? 🚨 Make sure you use the PACKAGE configuration option to specify the package where Inline::Java should bind the Java code, because ModPerl::Registry will drop your code into a package with a unpredictable name. Rude of it honestly.

💀 If the shared_jvm server is acting up under MOD_PERL, go peek at the BUGS AND DEFICIENCIES section. We got you.

🎀 Preloading and PerlChildInitHandler 🎀

ok so picture this: you're loading Inline::Java during your server startup (super common move — it bumps up shared memory and cuts down run time, iconic behavior) and you're using shared_jvm. Well… then all your Apache processes are gonna share the same socktd connection to that JVM. Which means: garbled communication, strange errors, chaos, the whole thing. Think "Can't receive packet from JVM", "Broken pipe", etc. 😭 Not the vibe.

The fix? You gotta tell Apache that after each child process has forked, they each need to create their own connections to the JVM. This happens during the ChildInit stage. Slay.

For Apache 1.3.x this could look like:

# in httpd.conf
PerlChildInitHandler MyProject::JavaReconnect

And MyProject::JavaReconnect could be as simple as this:

package MyProject::JavaReconnect;
sub handler($$) { Inline::Java::reconnect_JVM() }
1;

periodt. ✨

🦋 BUGS AND DEFICIENCIES 🦋

When you're reporting a bug, please do the following, bestie — it makes everything so much smoother:

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 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. So like… don't. 💅
If you upgrade Inline::Java from a previous version, be sure to delete your _Inline directory so that Inline::Java's own Java classes get rebuilt to match the Perl code. It's a glow-up, you gotta let it happen.
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:

% perl -MInline::Java::Server=status
% perl -MInline::Java::Server=start
% perl -MInline::Java::Server=stop
% perl -MInline::Java::Server=restart

You can specify Inline::Java options by setting the proper environment variables, and you can also set the _Inline directory by using the PERL_INLINE_JAVA_DIRECTORY environment variable. 🫶

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. (very "not me causing my own problems" energy, tbh)

Because of problems with modules Inline::Java 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. So like… no spaces, babe.
Even though it is run through a profiler regularly, Inline::Java is relatively slow compared to native Perl or Java. Lowkey just how it is. 🙈

💖 SEE ALSO 💖

Inline::Java::Callback, Inline::Java::PerlNatives, Inline::Java::PerlInterpreter.
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>. To subscribe, send an email to <inline-subscribe@perl.org>

👑 AUTHOR 👑

Patrick LeBoutillier <patl@cpan.org> is the author of Inline::Java. absolute legend.

Brian Ingerson <ingy@cpan.org> is the author of Inline.

🌸 COPYRIGHT 🌸

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.

and that's a wrap on the whole Inline::Java(3pm) page, bestie!! 🎀✨

This one's from perl v5.40.0 and it's dated 2024-12-07 — so yeah, that's the source and the date, noted for the record 💜 go forth and slay your Java-in-Perl adventures, you got this 🦋

📦 where this page comes from

debian trixie: libinline-java-perl 0.67-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libinline-java-perl 0.67-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms