NAME

Tutorial - Perl and Java

SYNOPSIS

Java and Perl have different strengths and complement each other well.

You can connect them at runtime with tools such as JPL, PJC, or ActiveX. In theory, you can convert Perl to Java bytecode, and vice-versa.

Note:

Not actually a conversion.

At this stage, we are generating Java opcodes by walking Perl's syntax tree. This is very different from converting Perl to Java. It's a lot easier!

1.1 Perl and Java, Compared

Perl offers rich text processing features, high-level network APIs, excellent database integration, and a centralized repository of reusable code:

Regular expression engine is a powerful sub language that can perform complex text manipulations and extract data.
Packages such as libwww-perl (LWP) and libnet are powerful, high-level interfaces to network functionality.
The Perl DBI is an interface to SQL data sources.
CPAN provides a centralized, organized archive of reusable code.

Java has a powerful graphical API, has numerous embedded implementations, excellent database integration, but no single recognized repository of reusable code.

The Swing (JFC) toolkit is a powerful toolkit for developing user interfaces. Java also boasts 2D and 3D graphics APIs.
Java comes in embedded flavors, such as:
- Kaffe http://www.transvirtual.com/ - embedded implementations for different platforms
- Waba http://www.wabasoft.com/ - a subset of Java for Windows CE and PalmOS
- It's embedded into web browsers (Netscape and MS Internet Explorer)
- and more...
Java's JDBC is similar to Perl's DBI
Java has many different repositories of code. Efforts such as the Giant Java Tree http://www.gjt.org/ attempt to create a unified repository.

1.2 Opportunities to Combine Java and Perl

You have a Java program with a lot of data that needs to be parsed, filed, briefed, debriefed, and numbered.

You want to build your GUI in Java, but let Perl do the heavy lifting.

You've adopted the "Java is a systems language, Perl is a scripting language" paradigm, and it works for you.

You're not sure which regex implementation to use:

org.teeth.green.loony.raving.monster.regex.*;

com.zeppelin.regex.*;

You want the best of both worlds.

1.3 Important Differences between Java and Perl

perl compiles and executes programs each time you run them (unless you use the Perl compiler).
javac compiles programs in advance, java runs them in the Java interpreter.
The Java interpreter supports method overloading (methods can have the same name, but are differentiated on the basis of their argument types). Overloaded methods generally perform the same function, but methods with a shorter argument list often use defaults:

// Draw a circle in the center of the screen
int drawCircle(int radius);

// Draw a circle at specified coordinates
int drawCircle(int radius, int h, int k);

The Perl interpreter doesn't support method overloading. In JPL, when we call Java from Perl, we need to use some tricks to specify the Java method we want to invoke. We'll learn about this when we see JPL's getmeth function.

Note:

At the time this presentation was prepared, JPL did not work with Perl for Win32. However, JPL is in the core Perl distribution, and there are plans to make it work with Perl for Win32.

With that in mind, I'm presenting the JPL material first, because it is of interest to both Win32 and Unix Perl people. The Win32-specific stuff (alternatives to JPL) will come last. I won't be offended if the Unix people leave when I move to this section of the tutorial, since there is no Unix material in that section. I'm perfectly happy to take questions between JPL and ActiveX sections.

A subset of JPL now works on Win32. You can embed Java in Perl, but you cannot embed Perl in Java (yet).

2.1 JPL Overview

Let's look at an overview of JPL.

2.1.1 Calling Perl from Java

Well-supported by JPL, but it is a complicated process:

The JPL preprocessor parses the .jpl file and generates C code wrappers for Perl methods. It also generates Java and Perl source files.
The C compiler compiles the wrapper and links it to the libPerlInterpreter.so shared library, producing a shared library for the wrapper.
The Java compiler compiles the Java source file, which uses native methods to load the wrapper.
The wrapper connects the Java code to the Perl code in the Perl source file.

Fortunately, a generic Makefile.PL simplifies the process. This is a Perl script that generates a Makefile for you.

2.1.2 Calling Java from Perl

This works best when Perl is embedded within a Java program.

The JNI Perl module creates and loads a JVM. There is no precompiler, nothing extra -- it's just a Perl module and extension.

B<A Problem, Though>. In theory, you can call Java from standalone
Perl programs, but this doesn't work because some implementations
of Java use a user-level threads package (green threads) that
override some functions in the C library. Perl is comfortable
using these functions, but Java is not happy using the standard C
library functions.

So, with green threads, you can't reliably embed Java in a standalone Perl program.

Many Java implementations now use native threads. JPL has been tested on Solaris with JDK 1.1.x and native threads, but not on Linux.

Note:

Oddly enough, this is the only way it works on Win32.

On Unix, I've still had trouble, even with native threads. I might need to recompile perl with -DREENTRANT, but I'm not sure.

2.2 Working with JPL

How to set up a JPL application, compile, and install it.

2.2.1 Setting up a Project

The install-jpl script creates the setvars script. Source the output of setvars into your shell when you want to develop or run JPL applications.
Create a directory with the name of your project, such as Frotz. (if you want to use the generic Makefile.PL, you need a separate directory for each JPL class you create).
Copy the generic Makefile.PL into the project directory. The jpl/Sample directory in the Perl distribution includes the generic Makefile.PL.
Write a .jpl program with the same name as the project (such as Frotz.jpl)

2.2.2 Compiling and Installing a Project

Type make to compile the application, and make install to install it. This installs the application in the jpl directory you created when you installed JPL.

B<Beware>. The default I<jpl> directory is the same as the
directory you install it I<from>. If you go with the default and
delete your Perl source, you'll delete your JPL installation!

Type java Frotz (or the name you chose in step 2 of section 2.2.1) to run it

2.2.3 What's in the jpl Directory?

libPerlInterpreter.so: a shared library that loads the Perl interpreter.
Compiled .class files for JPL applications you have written.
Native code shared library wrappers for JPL applications you have written.
Perl scripts that contain the Perl code to load at runtime.

Beware. If you issue the C<make> command and then run the examples
in your development directory, you might be in for a surprise! If
the JPL directories come first in your CLASSPATH and
LD_LIBRARY_PATH, you'll keep running the installed, older version,
rather than the one you are developing

Note:

"Source" means to load it into your current shell, with something like:

eval-backtick-setvars-backtick

as opposed to just executing it, because then only the subshell gets the environment vars.

2.3 Calling Perl from Java

Now, we'll look at how you can invoke Perl from Java.

2.3.1 Perl Methods

You can put Perl methods in your .jpl file. Perl methods are declared perl and use double curly braces to make life easier on the JPL preprocessor:

perl int perlMultiply(int a, int b) {{
my $result = $a * $b;
return $result;
}}

In your Java code, you can invoke Perl methods like a Java method. The native code wrappers take care of running the Perl code:

public void invokePerlFunction() {
    int x = 3;
    int y = 6;
    int retval = perlMultiply(x, y);
    System.out.println(x + " * " + y + " = " + retval);
}

class MethodDemo

class MethodDemo {
// A Perl method to multiply two numbers and
// return the result.
//
perl int perlMultiply(int a, int b) {{
    my $result = $a * $b;
    return $result;
}}

// A Java method to call the Perl function.
//
public void invokePerlFunction() {
    int x = 3;
    int y = 6;
    int retval = perlMultiply(x, y);
    System.out.println(x +" * "+ y +" = "+ retval);
}

public static void main(String[] args) {
    MethodDemo demo = new MethodDemo();
    demo.invokePerlFunction();
    }
}

Where did $self go?

Don't worry, $self is still there. JPL takes care of fetching it, as well as all the other arguments:

perl int perlMultiply(int a, int b) {{
    my $result = $a * $b;
    return $result;
}}

perl void calculateProduct() {{
    my $x = 3;
    my $y = 6;
    my $retval = $self->perlMultiply($x, $y);
    print "$x * $y = $retval\n";
}}

B<Note>. JPL takes care of putting all the arguments, including
C<$self>, into variables. If you see a variable in the function
header, you will get a variable of the same name without having to
use C<shift> or C<@_>, guaranteed.

NOTE: I've added a line that prints the output of "ref dollar sign self" You'll see this when I run the demo.

class SelfDemo {

// A Perl method to multiply two values.
//
perl int perlMultiply(int a, int b) {{
    my $result = $a * $b;
    return $result;
}}

// A Perl method to invoke another Perl method.
//
perl void calculateProduct() {{
    my $x = 3;
    my $y = 6;
    # Ahhh. There's our old friend, $self!
    #
    my $retval = $self->perlMultiply($x, $y);
    # Display the results.
    #
    print "$x * $y = $retval\n";
}}

public static void main(String[] args) {
    SelfDemo demo = new SelfDemo();
    demo.calculateProduct();
    }
}

Passing Arrays

If you pass an array from Java into a Perl method, it arrives in the form of a scalar reference.

Use the GetIntArrayElements() JNI function to convert that scalar into an array of integers.

perl void min_max( int[] data ) {{

    # Get the array elements
    #
    my @new_array = GetIntArrayElements( $data );

    # Sort the array numerically
    #
    my @sorted = sort {$a <=> $b} @new_array;

    print "Min: $sorted[0], ",
    "Max: $sorted[$#sorted]\n";
}}

void minMaxDemo() {
    int[] data = {101, 99, 42, 666, 23};
    min_max( data );
}

Some JNI Array Functions

GetBooleanArrayElements( scalar): Converts scalar to an array of booleans.
GetByteArrayElements( scalar ): Converts scalar to an array of bytes.
GetCharArrayElements( scalar ): Converts scalar to an array of characters.
GetShortArrayElements( scalar ): Converts scalar to an array of short integers.
GetIntArrayElements( scalar ): Converts scalar to an array of integers.
GetLongArrayElements( scalar ): Converts scalar to an array of long integers.
GetFloatArrayElements( scalar ): Converts scalar to an array of floating point numbers.
GetDoubleArrayElements( scalar ): Converts scalar to an array of double precision numbers.
GetArrayLength( scalar ): Returns the length of the array.

PerlTakesArray.jpl // Show how to pass an array from Java to Perl. //

public class PerlTakesArray {

perl void min_max( int[] data ) {{
    # Get the array elements
    #
    my @new_array = GetIntArrayElements( $data );

    # Sort the array numerically
    #
    my @sorted = sort {$a <=> $b} @new_array;
    print "Min: $sorted[0], ",
    "Max: $sorted[$#sorted]\n";
}}

void minMaxDemo() {
    // Create an array and ask Perl to tell us
    // the min and max values.
    int[] data = {101, 99, 42, 666, 23};
    min_max( data );
}

public static void main(String[] argv) {
    PerlTakesArray demo = new PerlTakesArray();
    demo.minMaxDemo();
}

}

2.3.4 Passing Arrays of Objects

Working with arrays of objects is a little more complicated, because you need to work with them one at a time.

Fetch one element at a time with GetObjectArrayElement(), which returns an object of type java.lang.Object (the most generic type).

Explicitly cast the Object to its real type with bless().

perl void sortArray( String[] names ) {{
    my @new_array;
    for (my $i = 0; $i < GetArrayLength($names); $i++) {
        my $string = GetObjectArrayElement($names, $i);
        bless $string, "java::lang::String";
        push @new_array, $string;
    }
    print join(', ', sort @new_array), "\n";
}}

void arrayDemo() {
    String[] names = {"Omega", "Gamma", "Beta", "Alpha"};
    sortArray( names );
}

Note. String is not a primitive type: it is a class (java.lang.String). So, you need to use this technique for Strings as well. You can't use the technique in 2.3.3.

PerlTakesObjectArray.jpl

public class PerlTakesObjectArray {

// Perl method to sort an array of strings.
//
perl void sortArray( String[] names ) {{
    my @new_array; # an array to copy names[] to

    # Fetch each element from the array.
    for (my $i = 0; $i < GetArrayLength($names); $i++) {
        
        # Get the object (it's not a String yet!) at
        # the current index ($i).
        my $string = GetObjectArrayElement($names, $i);

        # Cast (bless) it into a String.
        bless $string, "java::lang::String";

        # Add it to the array.
        push @new_array, $string;
    }

    # Print the sorted, comma-delimited array.
    print join(', ', sort @new_array), "\n";

}}

// Create a String array and ask Perl to sort it for us.
//

void arrayDemo() {
    String[] names = {"Omega", "Gamma", "Beta", "Alpha"};
    sortArray( names );
}

public static void main(String[] argv) {
    PerlTakesObjectArray demo = new PerlTakesObjectArray();
    demo.arrayDemo();
}
}

2.3.5 Returning Arrays from Perl to Java

To write a Perl method that returns an array, declare its return value as an array type. Make sure you return a reference to the array, not a list:

perl int[] getTime() {{
    my ($sec, $min, $hour, @unused) = localtime(time);
    # Return an array with seconds, minutes, hours
    my @time_array = ($sec, $min, $hour);
    return \@time_array;
}}

void testArray() {
    int time[] = getTime();
    System.out.println(time[2] + ":" + time[1]);
}

PerlGivesArray.jpl

// Simple JPL demo to show how to send an array to Java
// from Perl

class PerlGivesArray {
// Call the Perl method to get an array and print
// the hour and minute elements.

void testArray() {
    int time[] = getTime();
    System.out.println(time[2] + ":" + time[1]);
}

// Perl method that returns an array reference.
//
perl int[] getTime() {{
    # Get the first three arguments from localtime,
    # discard the rest.
    my ($sec, $min, $hour, @unused) = localtime(time);

    # Return an array with seconds, minutes, hours
    my @time_array = ($sec, $min, $hour);
    return \@time_array;
}}

public static void main(String[] argv) {
    PerlGivesArray demo = new PerlGivesArray();
    demo.testArray();
}
}

2.3.6 Arrays from Strings

JPL will slice Perl strings up into Java arrays for you. If you declare a Perl method as an array type and return a string (instead of an array reference), JPL splits up the elements into an array.

Consider this example, where a GIF stored in a string gets turned into an array of bytes so Java can make an Image out of it:

void generateImage() {
    Toolkit kit = Toolkit.getDefaultToolkit();
    byte[] image_data = mkImage();
    img = kit.createImage( image_data );
}

perl byte[] mkImage() {{
    use GD;
    my $im = new GD::Image( $self->width, $self->height);
    my $white = $im->colorAllocate(255, 255, 255);
    my $blue = $im->colorAllocate(0, 0, 255);
    $im->fill($white, 0, 0);
    $im->string(gdLargeFont, 10, 10, "Hello, World", $blue);
    return $im->gif;
}}

GifDemo.jpl

import java.awt.*;
import java.awt.event.*;
import java.awt.image.*;

/*
* A JPL program that demonstrates passing byte arrays
* between Java and Perl
*
*/

class GIFDemo extends Canvas {
    Image img;
    int width = 200;
    int height = 30;
    
    // Constructor for this class.
    public GIFDemo() {
        this.setSize(width, height);
    }

// Java method to create an image.
//
void generateImage() {
    Toolkit kit = Toolkit.getDefaultToolkit();

    // Invoke the mkImage() Perl method to generate an
    // image.

    byte[] image_data = mkImage();

    // Create the image with the byte array we got
    // from the Perl method.

    img = kit.createImage( image_data );
}

// A Perl method to generate an image.

perl byte[] mkImage() {{

    # Use the GD image manipulation extension.

    use GD;

    # Create a new image with the height and width specified
    # in the enclosing Java class.

    my $im = new GD::Image( $self->width, $self->height);

    # Allocate two colors.

    my $white = $im->colorAllocate(255, 255, 255);
    my $blue = $im->colorAllocate(0, 0, 255);

    # Fill the image with white and draw a greeting.

    $im->fill($white, 0, 0);
    $im->string(gdLargeFont, 10, 10,
    "Hello, World", $blue);
    return $im->gif;
}}

// Java uses this to repaint the image when necessary.

public void paint(Graphics g) {
    g.drawImage(img, 0, 0, this);
}

// The entry point.

public static void main(String[] argv) {

    // Set up a frame and create an image.

    Frame f = new Frame("GD Example");
    f.setLayout(new BorderLayout());
    
    GIFDemo demo = new GIFDemo();
    demo.generateImage();

    f.add("Center", demo);
    f.addWindowListener( new Handler() );

    f.pack();
    f.show();

}
}

// A handler to process a request to close a window.

class Handler extends WindowAdapter {
    public void windowClosing(WindowEvent e) {
    System.exit(0);
}
}

2.3.7 Summary: Calling Perl from Java

Put your embedded Perl code in methods that are declared perl.
Use double, rather than single, curly braces ({{ and }}).
Invoke the Perl methods from Java just like any other Java method.
No need to pull arguments off of @_ with shift: JPL takes care of this for you. This includes $self.
If you pass a Java array into a Perl method, it comes in as a scalar reference.
Convert references to arrays of primitives with Get*ArrayElements
Use GetObjectArrayElement to get elements from arrays of strings and other objects.
To return an array from a perl method, declare the method as returning an array type, and either:
Return an array reference.
Return a string: JPL slices it up for you.

2.4 Calling Java from Perl

Next, let's look at how to invoke Java from Perl.

2.4.1 Java in Perl in Java

Remember the issues from 2.1.2 - this is unstable unless you are calling Java from Perl methods that are themselves embedded in a Java program.

2.4.2 Java in Perl: Simple Constructors

Use JPL::Class to load the class:

use JPL::Class "java::awt::Frame";

Invoke the constructor to create an instance of the class:

my $f = java::awt::Frame-new;>

You've got a reference to a Java object in $f, a Perl scalar. I think this is cool.

2.4.3 Constructors that Take Parameters

If the constructor has parameters, look up the method signature with getmeth:

my $new = getmeth("new", ['java.lang.String'], []);

The first argument to getmeth is the name of the method. The second argument is a reference to an array that contains a list of the argument types. The final argument to getmeth is a reference to an array containing a single element with the return type. Constructors always have a null (void) return type, even though they return an instance of an object.

Invoke the method through the variable you created:

my $f = java::awt::Frame->$new( "Frame Demo" );

Because Java supports method overloading, the only way Java can distinguish between different methods that have the same name is through the method signature. The getmeth function simply returns a mangled, Perl-friendly version of the signature. JPL's AutoLoader takes care of finding the right class.

For example, the method signature for $new is (Ljava/lang/String;)V. In Perl, this is translated to new__Ljava_lang_String_2__V. Sure, it means something to Java, but thanks to getmeth and JPL's AutoLoader, we don't have to worry about it!

2.4.4 More on getmeth

The getmeth function is not just for constructors. You'll use it to look up method signatures for any method that takes arguments.

To use getmeth, just supply the Java names of the types and objects in the argument or return value list. Here are a few examples:

Two int arguments, void return type:

$setSize = getmeth("setSize", ['int', 'int'], []);

One argument (java.awt.Component), with a return type of the same:

$add = getmeth("add", ['java.awt.Component'],

['java.awt.Component']);

Two arguments, a String object and a boolean value, and a void return type:
```
$new = getmeth("new",

['java.lang.String', 'boolean'], []);
```

A String argument with a java.lang.Class return type:

$forName = getmeth("forName",

['java.lang.String'],

['java.lang.Class']);

No arguments, but a boolean return value:

$next = getmeth("next", [], ['boolean']);

2.4.5 Instance Variables

Java instance variables that belong to a class can be reached through $self and a method with the same name as the instance variables:

$frame->$setSize( $self->width, $self->height );

Here is an example:

class VarDemo {

int foo = 100;

perl int perlChange() {{
    my $current_value = $self->foo;

    # Change foo to ten times itself.

    $self->foo( $current_value * 10 );

}}

void executeChange() {

    perlChange();
    System.out.println(foo);

}

public static void main(String[] args) {

    VarDemo demo = new VarDemo();
    demo.executeChange();

}

}

Note. JPL creates these methods with the same name as the variable. You can also supply a value to set the variable's value. If you create a method with this name, it will collide with the one that JPL defines.

FrameDemo.jpl

/*
* FrameDemo - create and show a Frame in Perl.
*
*/

public class FrameDemo {

    int height = 50;
    int width = 200;
    perl void make_frame () {{

    # Import two Java classes.

    use JPL::Class "java::awt::Frame";
    use JPL::Class "java::awt::Button";

    # Create a Frame and a Button. The two calls to new()
    # have the same signature.

    my $new = getmeth("new", ['java.lang.String'], []);
    my $frame = java::awt::Frame->$new( "Frame Demo" );
    my $btn = java::awt::Button->$new( "Do Not Press Me" );

    # Add the button to the frame.

    my $add = getmeth("add", ['java.awt.Component'],
    ['java.awt.Component']);
    $frame->$add( $btn );

    # Set the size of the frame and show it.

    my $setSize = getmeth("setSize", ['int', 'int'], []);
    $frame->$setSize($self->width, $self->height);
    $frame->show;

}}

public static void main(String[] argv) {

    FrameDemo demo = new FrameDemo();
    demo.make_frame();

}

}

2.4.6 Summary: Calling Java from Perl

Use JPL::Class to specify a Java class to import.
You can directly invoke constructors and methods that take no arguments.
If the constructor or method takes arguments, use getmeth to look up its signature.
Use $self to access Java instance variables and methods.

COPYRIGHT

You may distribute this file under the same terms as Perl itself.

Converted from FrameMaker by Kevin Falcone.

To install if, copy and paste the appropriate command in to your terminal.

cpanm

cpanm if

CPAN shell

perl -MCPAN -e shell
install if

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

Note:

1.1 Perl and Java, Compared

1.2 Opportunities to Combine Java and Perl

1.3 Important Differences between Java and Perl

Note:

2.1 JPL Overview

2.1.1 Calling Perl from Java

2.1.2 Calling Java from Perl

Note:

2.2 Working with JPL

2.2.1 Setting up a Project

2.2.2 Compiling and Installing a Project

2.2.3 What's in the jpl Directory?

Note:

2.3 Calling Perl from Java

2.3.1 Perl Methods

Where did $self go?

Passing Arrays

2.3.4 Passing Arrays of Objects

2.3.5 Returning Arrays from Perl to Java

2.3.6 Arrays from Strings

2.3.7 Summary: Calling Perl from Java

2.4 Calling Java from Perl

2.4.1 Java in Perl in Java

2.4.2 Java in Perl: Simple Constructors

2.4.3 Constructors that Take Parameters

2.4.4 More on getmeth

2.4.5 Instance Variables

2.4.6 Summary: Calling Java from Perl

COPYRIGHT

Module Install Instructions