Reference¶
Python API¶
This reference addresses the jpy Python module.
jpy Functions¶
-
jpy.
create_jvm
(options)¶ Create the Java VM using the given options sequence of strings. Possible option strings are of the form:
Option Meaning -D<name>=<value>
Set a Java system property. The most important system property is java.class.path
to include your Java libraries. You may also considerjava.library.path
if your Java code uses native code provided in shared libraries.-verbose[:class|gc|jni]
Enable verbose output. The options can be followed by a comma-separated list of names indicating what kind of messages will be printed by the JVM. For example, -verbose:gc,class
instructs the JVM to print GC and class loading related messages. Standard names include: gc, class, and jni.-X<value>
Set a non-standard JVM option which usually begins with -X
or an underscore. For example, the Oracle JDK/JRE supports-Xms
and-Xmx
options to allow programmers specify the initial and maximum heap size. Please refer to the documentation of the used Java Runtime Environment (JRE).The function throws a runtime error on failure. It has no return value.
Usage example:
jpy.create_jvm(['-Xmx512M', '-Djava.class.path=/usr/home/norman/jpy-test/classes'])
-
jpy.
destroy_jvm
()¶ Destroy the Java Virtual Machine. The function has no effect if the JVM is has not yet been created or has already been destroyed. No return value.
-
jpy.
get_type
(name, resolve=False)¶ Return a type object for the given, fully qualified Java type name which is the name of a Java primitive type, a Java class name, or a Java array type name.
Java class names must be fully qualified, e.g.
'java.awt.Point'
. For inner classes a dollar sign is used to separate it from its containing class, e.g.'java.awt.geom.Ellipse2D$Float'
.Java array type names have a trailing opening bracket, followed by either a Java class name and a trailing semicolon or followed by one of the primitive type indicators:
'Z'
, the Javaboolean
type (an 8-bit Boolean value)'C'
, Javachar
type (a 16-bit unicode character)'B'
, Javabyte
type (an 8-bit signed integer number)'S'
, Javashort
type (a 16-bit signed integer number)'I'
, Javaint
type (a 32-bit signed integer number)'J'
, Javalong
type (a 64-bit signed integer number)'F'
, Javafloat
type (a 32-bit floating point number)'D'
, Javadouble
type (a 64-bit floating point number)
Examples:
'[java.awt.Point;'
(1d object array),'[[[F'
(3d float array).If the returned Java type has public constructors it can be used to create Java object instances in the same way Python objects are created from their types, e.g.:
String = jpy.get_type('java.lang.String') s = String(‘Hello jpy!’) s = s.substring(0, 5)
The returned Java types are also used to access the type’s static fields and methods:
Runtime = jpy.get_type('java.lang.Runtime') rt = Runtime.getRuntime() tm = rt.totalMemory()
The returned Java types have a jclass attribute which returns the actual Java object. This allows for using the Java types where a Java method would expect a parameter of type java.lang.Class.
To instantiate Java array objects, the
jpy.array()
function is used.Implementation note: All types loaded so far from the Java VM are stored in the global
jpy.types
variable. If the requested type does not already exists injpy.types
, the class is newly loaded from the Java VM. The root class of all Java types retrieved that way isjpy.JType
.Make sure that
jpy.create_jvm()
has already been called. Otherwise the function fails with a runtime exception.
-
jpy.
array
(item_type, init)¶ Create a Java array object for the given item_type and of the given initializer init.
item_type may be a type object as returned by the
jpy.get_type()
function or a type name as it is used for thejpy.get_type()
function. In addition, the name of a Java primitive type can be used:'boolean'
(an 8-bit Boolean value)'char'
(a 16-bit unicode character)'byte'
(an 8-bit signed integer number)'short'
(a 16-bit signed integer number)'int'
(a 32-bit signed integer number)'long'
(a 64-bit signed integer number)'float'
(a 32-bit floating point number)'double'
(a 64-bit floating point number)
The value for the init parameter may bei either an array length in the range
0
to2**31-1
or a sequence of objects which all must be convertible to the given item_type.Make sure that
jpy.create_jvm()
has already been called. Otherwise the function fails with a runtime exception.Examples::
a = jpy.array('java.lang.String', ['A', 'B', 'C']) a = jpy.array('int', [1, 2, 3]) a = jpy.array('float', 512)
-
jpy.
cast
(jobj, type)¶ Convert a Java object to a Java object with the given Java type (type object or type name, see
jpy.get_type()
). If jobj is already of type, jobj is returned. If jobj is an instance of type, a new wrapper object will be created for this type, otherwiseNone
is returned.This function is useful if you need to convert the java.util.Object values returned e.g. by Java collections (implementations of the java.util.Set, java.util.Map, java.util.List & Co.) to specific types. For example:
ArrayList = jpy.get_type('java.util.ArrayList') File = jpy.get_type('java.io.File') al = ArrayList() al.add(File('/home/bibo/.jpy')) item = al.get(0) # item has type java.util.Object, but actually is a java.io.File print(type(item)) item = jpy.cast(item, File) # item has now type java.io.File print(type(item))
Make sure that
jpy.create_jvm()
has already been called. Otherwise the function fails with a runtime exception.
Variables¶
-
jpy.
types
¶ A dictionary that maps Java class names to the respective Python type objects (wrapped Java classes). You should never modify the value of this variable nor directly modify the dictionary’s contents.
-
jpy.
type_callbacks
¶ Contains callbacks which are called before jpy translates Java methods to Python methods while Java classes are being loaded. These callbacks can be used to annotate Java methods so that jpy can better translate them to Python. This is a powerful but advanced jpy feature that you usually don’t have to use.
Consider a Java method:
double[] readData(long offset, int length, double[] data);
of some Java class
Reader
. From the method’s documentation we know that if we passnull
for data, it will create a new array of the given length, read data into it and the return that instance. If we pass an existing array it will be reused instead. From plain Java class introspection, jpy can neither detect if a primitive array parameter is modified by a method and/or whether it shall serve as the method’s return value.To overcome the problem of such semantics inherent to a Java method implementation, jpy uses a dictionary
type_callbacks
in which you can register a Java class name with a callable of following signature:callback(type, method)
This can be used to equip specific Java methods of a class with additional information while the Java class is being loaded from the Java VM. type is the Java class and method is the current class method being loaded. method is of type
jpy.JMethod
. The callback should return eitherTrue
orFalse
. If it returnsFalse
, jpy will not add the given method to the Python version of the Java class.Here is an example:
def annotate_Reader_readData_methods(type, method): if method.name == 'readData' and method.param_count == 3: param_type_str = str(method.get_param_type(1)) if param_type_str == "<class '[I'>" || param_type_str == "<class '[D'>": method.set_param_mutable(2, True) method.set_param_return(2, True) return True class_name = 'com.acme.Reader' jpy.type_callbacks[class_name] = annotate_Reader_readData_methods # This will invoke the callback above Reader = jpy.get_type(class_name)
Once a method parameter is annotated that way, jpy can transfer the semantics of a Java method to Python. For example:
import numpy as np r = Reader('test.tif') a = np.array(1024, np.dtype=np.float64) a = r.read(0, len(a), a) r.close()
Here a call to the
read
method will modify the numpy array’s content as desired and return the same array instance as indicated by the Java method’s specification.
-
jpy.
diag
¶ An object used to control output of diagnostic information for debugging. This variable is only useful for jpy modification and further development.
-
diag.
flags
¶ Integer bit-combination of diagnostic flags (see following F_* constants). If this value is not zero, diagnostic messages are printed to the standard output stream for any subsequent jpy library calls. Its default value is
jpy.diag.F_OFF
which is zero.For example:
jpy.diag.flags = jpy.diag.F_EXEC + jpy.diag.F_JVM
The following flags are defined:
F_OFF
- Don’t print any diagnostic messagesF_ERR
- Errors: print diagnostic information when erroneous states are detectedF_TYPE
- Type resolution: print diagnostic messages while generating Python classes from Java classesF_METH
- Method resolution: print diagnostic messages while resolving Java overloaded methodsF_EXEC
- Execution: print diagnostic messages when Java code is executedF_MEM
- Memory: print diagnostic messages when wrapped Java objects are allocated/deallocatedF_JVM
- JVM: print diagnostic information usage of the Java VM Invocation APIF_ALL
- Print all possible diagnostic messages
Types¶
You will never have to use the following type directly. But it may be of use to know where they come from when they are referred to, e.g. in error messages.
-
class
jpy.
JType
¶ This type is the base class for all type representing Java classes. It is actually a meta-type used to dynamically create Python type instances from loaded Java classes. Such derived types are returned by
jpy.get_type()
instead or can be directly looked up injpy.types
.
-
class
jpy.
JOverloadedMethod
¶ This type represents an overloaded Java method. It is composed of one or more
jpy.JMethod
objects.
-
class
jpy.
JMethod
¶ This type represents a Java method. It is part of a
jpy.JOverloadedMethod
.-
name
¶ The method’s name. Read-only attribute.
-
return_type
¶ The method’s return type. Read-only attribute.
-
param_count
¶ The method’s parameter count. Read-only attribute.
-
get_param_type
(i) → type¶ Get the type of the i-th Java method parameter.
-
is_param_return
(i) → bool¶ Return
True
if arguments passed to the i-th Java method parameter will be the return value of the method,False
otherwise.
-
set_param_return
(i, value)¶ Set if arguments passed to the i-th Java method parameter will be the return value of the method, with value being a Boolean.
-
is_param_output
(i) → bool¶ Return
True
if the arguments passed to the i-th Java method parameter is a mere output (and not read from),False
otherwise.
-
set_param_output
(i, value)¶ Set if arguments passed to the i-th Java method parameter is a mere output (and not read from), with value being a Boolean. Used to optimise Python buffer to Java array parameter passing.
-
is_param_mutable
(i) → bool¶ Return
True
if the arguments passed to the i-th Java method parameter is mutable,False
otherwise.
-
set_param_mutable
(i, value)¶ Set if arguments passed to the i-th Java method parameter is mutable, with value being a Boolean.
-
-
class
jpy.
JField
¶ This type represents is used to represent Java class fields.
Type Conversions¶
This section describes the type possible type conversions made by jpy when Python values are passed as arguments to Java typed parameters. In the tables given below are the generated match values ranging from (types never match) to 100 (full match) when comparing a given Java parameter type (rows) with a provided Python value (columns). These match values are also used for finding the best matching Java method overload for a given Python argument tuple.
Java primitive types¶
NoneType |
bool |
int |
float |
number | |
---|---|---|---|---|---|
boolean |
1 | 100 | 10 | 0 | 0 |
char |
0 | 10 | 100 | 0 | 0 |
byte |
0 | 10 | 100 | 0 | 0 |
short |
0 | 10 | 100 | 0 | 0 |
int |
0 | 10 | 100 | 0 | 0 |
long |
0 | 10 | 100 | 0 | 0 |
float |
0 | 1 | 10 | 90 | 50 |
double |
0 | 1 | 10 | 100 | 50 |
Java object types¶
NoneType |
bool |
int |
float |
str |
|
---|---|---|---|---|---|
java.lang.Boolean |
1 | 100 | 10 | 0 | 0 |
java.lang.Character |
1 | 10 | 100 | 0 | 0 |
java.lang.Byte |
1 | 10 | 100 | 0 | 0 |
java.lang.Short |
1 | 10 | 100 | 0 | 0 |
java.lang.Integer |
1 | 10 | 100 | 0 | 0 |
java.lang.Long |
1 | 10 | 100 | 0 | 0 |
java.lang.Float |
1 | 1 | 10 | 90 | 0 |
java.lang.Double |
1 | 1 | 10 | 100 | 0 |
java.lang.String |
1 | 0 | 0 | 0 | 100 |
java.lang.Object |
1 | 10 | 10 | 10 | 10 |
Java primitive array types¶
NoneType |
seq | buf(‘b’) | buf(‘B’) | buf(‘u’) | buf(‘h’) | buf(‘H’) | buf(‘i’) | buf(‘I’) | buf(‘l’) | buf(‘L’) | buf(‘q’) | buf(‘Q’) | buf(‘f’) | buf(‘d’) | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
boolean[] |
1 | 10 | 100 | 100 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
char[] |
1 | 10 | 0 | 0 | 100 | 80 | 90 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
byte[] |
1 | 10 | 100 | 90 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
short[] |
1 | 10 | 0 | 0 | 0 | 100 | 90 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
int[] |
1 | 10 | 0 | 0 | 0 | 0 | 0 | 100 | 90 | 100 | 90 | 0 | 0 | 0 | 0 |
long[] |
1 | 10 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 100 | 90 | 0 | 0 |
float[] |
1 | 10 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 100 | 0 |
double[] |
1 | 10 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 100 |
If a python buffer is passed as argument to a primitive array parameter, but it doesn’t match the buffer types given above, the a match value of 10 applies, as long as the item size of a buffer matches the Java array item size.
Java object array types¶
todo