Readme.java
Jperl provides a set of methods to call PERL subroutines and pass
parameters and accept values from Java.
In the following methods, 'fname' can be a PERL function name like "foo",
or a fully qualified method name like "mypackage::foo". Do not use "()" in
calls. See main.java for examples.
Arguments :
All PLCall methods, take an Object array as argument. Valid Objects
are one of
Integer
Double
Float
String
Long
Short
Hashtable
Vector
Other types cause an IllegalArgumentException to be thrown.
Public methods
public jp(String perlfile) throws RuntimeException;
//Takes perlfilename as input. Throws exception on error.
//Only one instance of jp can be alive at a given time
public void DebugOn();
//Turns debug on in native code.
public void DebugOff();
//Turns debug off in native code.
public String PLCallScalar(String fname) throws RuntimeExceptio;
//Calls PERL subroutine 'fname'. Returns scalar result from Perl
//Throws exception in case of error
public String PLCallScalar(String fname, Object[] args)
throws RuntimeException,IllegalArgumentException
//Calls PERL subroutine 'fname'.
//Passes arguments Object args[] to PERL subroutine.
//Refer arguments for a list of valid arguments
//Returns scalar result from Perl
//Throws exception in case of error
public String[] PLCallArray(String fname, Object[] args)
throws RuntimeException,IllegalArgumentException
//Calls PERL subroutine 'fname'.
//Passes arguments Object args[] to PERL subroutine.
//Refer arguments for a list of valid arguments
//Returns Array result from Perl as a an array of String
//Throws exception in case of error
public Hashtable PLCallHash(String fname, Object[] args)
throws RuntimeException,IllegalArgumentException
//Calls PERL subroutine 'fname'.
//Passes arguments Object args[] to PERL subroutine.
//Refer arguments for a list of valid arguments
//Returns Hasharray from Perl as Object Hashtable
//Throws Runtime exception in case of error or odd number of arguments
//returned to Hashtable
public native void IPLLoadLibrary(String libname)
throws RuntimeException;
// Internal routine available as public.
// Can be used to load additioal PERL modules at run time
public native String[] IPLEval(String expression)
throws RuntimeException;
// Internal routine available as public.
// Can be used to evaluate PERL expressions and return values
// example PLEval("$a = 'MyString'; $b = reverse($a); return ($a,$b);");
Points to Note
1. All values are returned as String/String[].
It is left to the application to decide and convert the values
2. When Hashtable is returned, all values are stored as strings.
3. String can contain "" if nothing was returned from PERL. In case of
error in conversion from PERL Datastructure to JAVA, the string will
contain "(null)" as its value. All strings are guaranteed to be non
null
4. In case of PERL modules using dynamic libraries,
an error will be reported.
Support for this will be added soon.
5. Flush STDIN/OUT in PERL, so that output of print in PERL is
not buffered. This can be done by
select((select(STDOUT),$| = 1)[0]);
6. Add the directory of libperl.so to your LD_LIBRARY_PATH
7. Data transfer mechanism from PERL to JAVA is restricted to those
described above. In case of PERL taking complex data structures
like Hash of Hash, Array of Hash etc., a wrapper PERL function needs to
be written
8. In Perl returning non existant values causes "(null)" to be returned.
for example
sub foo { return ("Iam there",$nonexistent); }
9. If the PERL program exits or dies, control will not return to Java
10. Using Scalar return, when PERL returns a list causes an exception to
be thrown
This has been tested only with JDK 1.1.4 and Perl 5.002 modules on Solaris