One of the goals of Jython is to make it as simple as possible to use existing Java libraries from Python.
The following example of an interactive session with Jython 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:\jython>jython Jython 2.0 on java1.2.1 Type "copyright", "credits" or "license" for more information. >>> 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 >>>
Hopefully, this example should make it clear that there are very few differences between using Java packages and using Python packages when working under Jython. There are a few things to keep in mind.
Jython 2.0 on java1.2.1 Type "copyright", "credits" or "license" for more information. >>> from java.util import * >>> Random <jclass java.util.Random at 31702169> >>> Hashtable <jclass java.util.Hashtable at 7538094> >>>
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.
Java classes have both static and instance methods, which 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 Strings when a
java.lang.Object is expected. This behavior might change if
it turns out to cause problems.
| Java Types | Allowed Python Types |
|---|---|
| char | str (must have length 1) |
| boolean | bool, int (true = nonzero) |
| byte, short, int, long | int |
| float, double | float |
| java.lang.String, byte[], char[] | string (will be encoded), unicode |
| java.lang.Class Class or JavaClass | (only if class subclasses from exactly one Java class; mutiple inheritance from more than one Java class is illegal) |
| Foo[] | array (must contain objects of class or subclass of Foo), jarray (legacy) |
| java.lang.Object | string or unicode -> 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 | unicode (of length 1) |
| boolean | bool |
| byte, short, int, long | int |
| float, double | float |
| java.lang.String | unicode |
| java.lang.Class | type for the given Java class |
| Foo[] | array (containing objects of class or subclass of Foo) |
| org.python.core.PyObject (or subclass) | Unchanged |
| Foo | instance which represents the Java Class Foo |
| 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 |
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.
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))
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. Where the intent can be unambiguously determined, no identifier mangling is necessary, such as when keywords are used as attributes on objects. Thus you can naturally write:
orjava.lang.System.out.print("hi")
java.lang.Runtime.getRuntime().exec(cmd)
In the rare case where the conflict can't be resolved due to Python's
grammar, you should modify the reserved word by appended an underscore
to the end of it, e.g. print_.