Accessing Java from JPython

One of the goals of JPython is to make it as simple as possible to use existing Java libraries from Python.

Example

The following example of an interactive session with JPython shows how a user could create an instance of the Java random number class (found in java.util.Random) and then interact with that instance.
C:\jpython>jpython
>>> from java.util import Random
>>> r = Random()
>>> r.nextInt()
-790940041
>>> for i in range(5):
...     print r.nextDouble()
...
0.23347681506123852
0.8526595592189546
0.3647833839988137
0.3384865260567278
0.5514469740469587
>>>

More Details

Hopefully, this example should make it clear that there are very few differences between using Java packages and using Python packages when working under JPython.  There are a few things to keep in mind.

Importing

You can import from any Java package, just like you would from a Python package.  However, you are not allowed to do "from package import *" with Java packages.  i.e. "from java.lang import *" is illegal.

In order to use a Java package under JPython, you must make JPython aware of the package.  This can be done in one of two ways.  You can modify the JPython registry entry to include the package under the "java.packages" key (see the previous section for more details on this).  Or you can call the function "sys.add_package(package_name)" at runtime to make JPython aware of any arbitrary package.  The previous example assumed that JPython was aware of the "java.util" package (which it is by default).  If it wasn't aware of this package, a new line would need to be added to the top of the example which read, "import sys; sys.add_package('java.util')"

Creating Class Instances

You can create an instance of a Java class exactly the way you would create an instance of a Python class.  You must "call" the class with a set of arguments that is appropriate for one of the Java class's constructors.  See the section below for more details on what constitutes appropriate arguments.

Calling Java Methods and Functions

Java classes have both static and instance methods this makes them behave much like a cross between a Python module and class.  As a user, you should rarely need to be concerned with this difference.

Java methods and functions are called just exactly like their Python counterparts.  There is some automatic type coercion that goes on both for the types being passed in and for the value returned by the method.  The following table shows how Python objects are coerced to Java objects when passed as arguments in a function call. The Java Types show the expected java type for the argument, and the Allowed Python Types shows what Python objects can be converted to the given Java type.  Notice the special behavior of String's when a java.lang.Object is expected.  This behavior might change if I am shown that it causes problems.
 
Java Types Allowed Python Types
char String (must have length 1) 
boolean Integer (true = nonzero) 
byte, short, int, long Integer or Float
float, double Float
java.lang.String, byte[] String 
java.lang.Class Class or JavaClass (only if class subclasses from exactly one Java class)
Foo[] Array (must contain objects of class or subclass of Foo)
java.lang.Object String->java.lang.String, all others unchanged 
org.python.core.PyObject All unchanged 
Foo Instance->Foo (if Instance is subclass of Foo); 
JavaInstance -> Foo (if JavaInstance is instance of Foo or subclass) 
Returned values from a Java method are also possibly coerced back to an object that is more readily usable in Python.  The following table shows those coercions.
 
 
Java Type Returned Python Type
char String (of length 1) 
boolean Integer (true = 1, false = 0) 
byte, short, int, long Integer
float, double Float
java.lang.String String 
java.lang.Class JavaClass which represents given Java Class
Foo[] Array (containing objects of class or subclass of Foo)
org.python.core.PyObject (or subclass) Unchanged 
Foo JavaInstance which represents the Java Class Foo
 

Overloaded Java Method Signatures

Java methods are allowed to be overloaded for different signatures (types and number of arguments). When different versions of the method differ in the number of arguments that they expect, the appropriate method can be easily determined from the number of arguments passed to the method.

When the difference is instead in the types of the arguments, more work is required.  The possible signatures are sorted in a consistent order that should ensure the appropriate method is chosen first.  More information on exactly how this sorting is performed will be provided when I have the time.

If you need to call a Java method with a particular signature and this is not happening in the easy way, you can use the following workaround:

Assume that foo has two methods, "void foo(int x); void foo(byte x);".  To call the second method you could write the following:

from java.lang import Byte
foo(Byte(10))
I'm not convinced that any better solution to this problem is possible.

Naming Conflicts with Python Keywords

Because Java has a different set of keywords than Python, there are many Java classes that have method and function names that conflict with Python's keyword set.  The most frequent offenders seem to be "print", "in", and "from".  While there might be better remedies for this problem in the future, the current solution is to use Python's "getattr" function.

i.e. You can't type in Python "foo.print('hello')" to call some Java objects "print" method.  However, you can do the following, "getattr(foo, 'print')('hello')".