Java QuickStart Guide ===================== This is a quick start guide to using JPype with Java. This guide will show a series of snippets with the corresponding commands in both Java and Python for using JPype. The :doc:`userguide` and :doc:`api` have additional details on the use of the JPype module. JPype uses two factory classes (``JArray`` and ``JClass``) to produce class wrappers which can be used to create all Java objects. These serve as both the base class for the corresponding hierarchy and as the factory to produce new wrappers. Casting operators are used to construct specify types of Java types (``JObject``, ``JString``, ``JBoolean``, ``JByte``, ``JChar``, ``JShort``, ``JInt``, ``JLong``, ``JFloat``, ``JDouble``). Two special classes serve as the base classes for exceptions (``JException``) and interfaces (``JInterface``). There are a small number of support methods to help in controlling the JVM. Lastly, there are a few annotations used to create customized wrappers. For the purpose of this guide, we will assume that the following classes were defined in Java. We will also assume the reader knows enough Java and Python to be dangerous. .. code-block:: java package org.pkg; public class BaseClass { public void callMember(int i) {} } public class MyClass extends BaseClass { final public static int CONST_FIELD = 1; public static int staticField = 1; public int memberField = 2; int internalField =3; public MyClass() {} public MyClass(int i) {} public static void callStatic(int i) {} public void callMember(int i) {} // Python name conflict public void pass() {} public void throwsException() throws java.lang.Exception {} // Overloaded methods public void call(int i) {} public void call(double d) {} } Starting JPype -------------- The hardest thing about using JPype is getting the jars loaded into the JVM. Java is curiously unfriendly about reporting problems when it is unable to find a jar. Instead, it will be reported as an ``ImportError`` in Python. These patterns will help debug problems with jar loading. Once the JVM is started Java packages that are within a top level domain (TLD) are exposed as Python modules allowing Java to be treated as part of Python. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Start Java Virtual | | .. code-block:: python | | Machine (JVM) | | | | | | # Import module | | | | import jpype | | | | | | | | # Enable Java imports | | | | import jpype.imports | | | | | | | | # Pull in types | | | | from jpype.types import * | | | | | | | | # Launch the JVM | | | | jpype.startJVM() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Start Java Virtual | | .. code-block:: python | | Machine (JVM) with a | | | | classpath | | # Launch the JVM | | | | jpype.startJVM(classpath = ['jars/*']) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import default Java | | .. code-block:: python | | namespace [1]_ | | | | | | import java.lang | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Add a set of jars from a | | .. code-block:: python | | directory [2]_ | | | | | | jpype.addClassPath("/my/path/*") | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Add a specific jar to the | | .. code-block:: python | | classpath [2]_ | | | | | | jpype.addClassPath('/my/path/myJar.jar') | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Print JVM CLASSPATH [3]_ | | .. code-block:: python | | | | | | | | from java.lang import System | | | | print(System.getProperty("java.class.path")) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [1] All ``java.lang.*`` classes are available. .. [2] Must happen prior to starting the JVM .. [3] After JVM is started Classes/Objects --------------- Java classes are presented wherever possible similar to Python classes. The only major difference is that Java classes and objects are closed and cannot be modified. As Java is strongly typed, casting operators are used to select specific overloads when calling methods. Classes are either imported using a module, loaded using ``JPackage`` or loaded with the ``JClass`` factory. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Import a class [4]_ | .. code-block:: java | .. code-block:: python | | | | | | | import org.pkg.MyClass | from org.pkg import MyClass | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import a class and rename | | .. code-block:: python | | [4]_ | | | | | | from org.pkg import MyClass as OurClass | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import multiple classes | | .. code-block:: python | | from a package [5]_ | | | | | | from org.pkg import MyClass, AnotherClass | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import a java package for | | .. code-block:: python | | long name access [6]_ | | | | | | import org.pkg | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import a class static | .. code-block:: java | .. code-block:: python | | [7]_ | | | | | import org.pkg.MyClass.CONST_FIELD | from org.pkg.MyClass import CONST_FIELD | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import a class without | .. code-block:: java | .. code-block:: python | | tld [8]_ | | | | | import zippy.NonStandard | NonStandard = JClass('zippy.NonStandard') | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Construct an object | .. code-block:: java | .. code-block:: python | | | | | | | MyClass myObject = new MyClass(1); | myObject = MyClass(1) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Constructing a class with | | .. code-block:: python | | full class name | | | | | | import org.pkg | | | | myObject = org.pkg.MyClass(args) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get a static field | .. code-block:: java | .. code-block:: python | | | | | | | int var = MyClass.staticField; | var = MyClass.staticField | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get a member field | .. code-block:: java | .. code-block:: python | | | | | | | int var = myObject.memberField; | var = myObject.memberField | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Set a static field [9]_ | .. code-block:: java | .. code-block:: python | | | | | | | MyClass.staticField = 2; | MyClass.staticField = 2 | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Set a member field [9]_ | .. code-block:: java | .. code-block:: python | | | | | | | myObject.memberField = 2; | myObject.memberField = 2 | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Call a static method | .. code-block:: java | .. code-block:: python | | | | | | | MyClass.callStatic(1); | MyClass.callStatic(1) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Call a member method | .. code-block:: java | .. code-block:: python | | | | | | | myObject.callMember(1); | myObject.callMember(1) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Access member with Python | .. code-block:: java | .. code-block:: python | | naming conflict [10]_ | | | | | myObject.pass() | myObject.pass_() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Checking inheritance | .. code-block:: java | .. code-block:: python | | | | | | | if (obj instanceof MyClass) {...} | if (isinstance(obj, MyClass): ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Checking if Java class | | .. code-block:: python | | wrapper | | | | | | if (isinstance(obj, JClass): ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Checking if Java object | | .. code-block:: python | | wrapper | | | | | | if (isinstance(obj, JObject): ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Casting to a specific | .. code-block:: java | .. code-block:: python | | type [11]_ | | | | | BaseClass b = (BaseClass)myObject; | b = (BaseClass) @ myObject | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [4] This will report an error if the class is not found. .. [5] This will report an error if the classes are not found. .. [6] Does not report errors if the package is invalid. .. [7] Constants, static fields, and static methods can be imported. .. [8] ``JClass`` loads any class by name including inner classes. .. [9] This produces an error for final fields. .. [10] Underscore is added during wrapping. .. [11] Matmul(@) is used as the casting operator. Exceptions ---------- Java exceptions extend from Python exceptions and can be dealt with in the same way as Python native exceptions. JException serves as the base class for all Java exceptions. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Catch an exception | .. code-block:: java | .. code-block:: python | | | | | | | try { | try: | | | myObject.throwsException(); | myObject.throwsException() | | | } catch (java.lang.Exception ex) | except java.lang.Exception as ex: | | | { ... } | ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Throw an exception to | .. code-block:: java | .. code-block:: python | | Java | | | | | throw new java.lang.Exception( | raise java.lang.Exception( | | | "Problem"); | "Problem") | | | | | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Checking if Java | | .. code-block:: python | | exception wrapper | | | | | | if (isinstance(obj, JException): ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Closeable items | .. code-block:: java | .. code-block:: python | | | | | | | try (InputStream is | with Files.newInputStream(file) as is: | | | = Files.newInputStream(file)) | ... | | | { ... } | | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ Primitives ---------- Most Python primitives directly map into Java primitives. However, Python does not have the same primitive types, and it is necessary to cast to a specific Java primitive type whenever there are Java overloads that would otherwise be in conflict. Each of the Java types are exposed in JPype (``JBoolean``, ``JByte``, ``JChar``, ``JShort``, ``JInt``, ``JLong``, ``JFloat``, ``JDouble``). +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Casting to hit an | .. code-block:: java | .. code-block:: python | | overload [12]_ | | | | | myObject.call((int)v); | myObject.call(JInt(v)) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create a primitive array | .. code-block:: java | .. code-block:: python | | | | | | | int[] array = new int[5] | array = JInt[5] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create a rectangular | .. code-block:: java | .. code-block:: python | | primitive array | | | | | int[][] array = new int[5][10] | array = JInt[5, 10] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create an array of arrays | .. code-block:: java | .. code-block:: python | | | | | | | int[][] array = new int[5][] | array = JInt[5, :] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create an initialized | .. code-block:: java | .. code-block:: python | | primitive array [13]_ | | | | | int[] array = new int[]{1,2,3} | array = JInt[:]([1,2,3]) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create an initialized | .. code-block:: java | .. code-block:: python | | boxed array [13]_ | | | | | Integer[] array = new Integer[]{1,2,3} | array = java.lang.Integer[:]([1,2,3]) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Put a specific primitive | .. code-block:: java | .. code-block:: python | | type on a list | | | | | List myList | from java.util import ArrayList | | | = new ArrayList<>(); | myList = ArrayList() | | | myList.add(1); | myList.add(JInt(1)) | | | | | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Boxing a primitive [14]_ | .. code-block:: java | .. code-block:: python | | | | | | | Integer boxed = 1; | boxed = JObject(JInt(1)) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [12] ``JInt`` acts as a casting operator .. [13] list, sequences, or np.array can be used to initialize. .. [14] ``JInt`` specifies the prmitive type. ``JObject`` boxes the primitive. Strings ------- Java strings are similar to Python strings. They are both immutable and produce a new string when altered. Most operations can use Java strings in place of Python strings, with minor exceptions as Python strings are not completely duck typed. When comparing or using as dictionary keys, all JString objects should be converted to Python. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Create a Java string | .. code-block:: java | .. code-block:: python | | [15]_ | | | | | String javaStr = new String("foo"); | myStr = JString("foo") | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create a Java string from | .. code-block:: java | .. code-block:: python | | bytes [16]_ | | | | | byte[] b; | b= b'foo' | | | String javaStr = new String(b, "UTF-8"); | myStr = JString(b, "UTF-8") | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Converting Java string | | .. code-block:: python | | | | | | | | str(javaStr) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Comparing Python and Java | | .. code-block:: python | | strings [17]_ | | | | | | str(javaStr) == pyString | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Comparing Java strings | .. code-block:: java | .. code-block:: python | | | | | | | javaStr.equals("foo") | javaStr == "foo" | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Checking if Java string | | .. code-block:: python | | | | | | | | if (isinstance(obj, JString): ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [15] ``JString`` constructs a ``java.lang.String`` .. [16] All ``java.lang.String`` constuctors work. .. [17] ``str()`` converts the object for comparison Arrays ------ Arrays are create using the JArray class factory. They operate like Python lists, but they are fixed in size. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Create a single dimension | .. code-block:: java | .. code-block:: python | | array | | | | | MyClass[] array = new MyClass[5]; | array = MyClass[5] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create a multi dimension | .. code-block:: java | .. code-block:: python | | array (old) | | | | | MyClass[][] array2 = new MyClass[5][]; | array2 = JArray(MyClass, 2)(5) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Create a multi dimension | .. code-block:: java | .. code-block:: python | | array (new) | | | | | MyClass[][] array2 = new MyClass[5][]; | array2 = MyClass[5,:] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Access an element | .. code-block:: java | .. code-block:: python | | | | | | | array[0] = new MyClass() | array[0] = MyClass() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Size of an array | .. code-block:: java | .. code-block:: python | | | | | | | array.length | len(array) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get last element | .. code-block:: java | .. code-block:: python | | | | | | | MyClass a = array[array.length]; | a = array[-1] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Slice an array [18]_ | | .. code-block:: python | | | | | | | | a = array[2:5] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Clone an array | .. code-block:: java | .. code-block:: python | | | | | | | MyClass[] a = array.clone(); | a = array.clone() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Convert to Python list | | .. code-block:: python | | | | | | | | pylist = list(array) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Iterate elements | .. code-block:: java | .. code-block:: python | | | | | | | for (MyClass element: array) | for element in array: | | | {...} | ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Checking if java array | | .. code-block:: python | | wrapper | | | | | | if (isinstance(obj, JArray): ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [18] A Slice is a view and changes will be reflected on original. Slices passed to Java will clone. Collections ----------- Java standard containers are available and are overloaded with Python syntax where possible to operate in a similar fashion to Python objects. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Import list type | .. code-block:: java | .. code-block:: python | | | | | | | import java.util.ArrayList; | from java.util import ArrayList | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Construct a list | .. code-block:: java | .. code-block:: python | | | | | | | List myList=new ArrayList<>(); | myList=ArrayList() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get length of list | .. code-block:: java | .. code-block:: python | | | | | | | int sz = myList.size(); | sz = len(myList) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get list item | .. code-block:: java | .. code-block:: python | | | | | | | Integer i = myList.get(0) | i = myList[0] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Set list item [19]_ | .. code-block:: java | .. code-block:: python | | | | | | | myList.set(0, 1) | myList[0]=Jint(1) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Iterate list elements | .. code-block:: java | .. code-block:: python | | | | | | | for (Integer element: myList) | for element in myList: | | | {...} | ... | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Import map type | .. code-block:: java | .. code-block:: python | | | | | | | import java.util.HashMap; | from java.util import HashMap | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Construct a map | .. code-block:: java | .. code-block:: python | | | | | | | Map myMap = new HashMap<>(); | myMap = HashMap() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get length of map | .. code-block:: java | .. code-block:: python | | | | | | | int sz = myMap.size(); | sz = len(myMap) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Get map item | .. code-block:: java | .. code-block:: python | | | | | | | Integer i = myMap.get("foo") | i = myMap["foo"] | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Set map item [19]_ | .. code-block:: java | .. code-block:: python | | | | | | | myMap.set("foo", 1) | myMap["foo"] = Jint(1) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Iterate map entries | .. code-block:: java | .. code-block:: python | | | | | | | for (Map.Entry e | for e in myMap.entrySet(): | | | : myMap.entrySet()) | ... | | | {...} | | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [19] Casting is required to box primitives to the correct type. Reflection ---------- Java reflection can be used to access operations that are outside the scope of the JPype syntax. This includes calling a specific overload or even accessing private methods and fields. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Access Java reflection | .. code-block:: java | .. code-block:: python | | class | | | | | MyClass.class | MyClass.class_ | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Access a private field by | | .. code-block:: python | | name [20]_ | | | | | | cls = myObject.class_ | | | | field = cls.getDeclaredField( | | | | "internalField") | | | | field.setAccessible(True) | | | | field.get() | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Accessing a specific | | .. code-block:: python | | overload [21]_ | | | | | | cls = MyClass.class_ | | | | cls.getDeclaredMethod("call", JInt) | | | | cls.invoke(myObject, JInt(1)) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Convert a | | .. code-block:: python | | ``java.lang.Class`` into | | | | Python wrapper [22]_ | | # Something returned a java.lang.Class | | | | MyClassJava = getClassMethod() | | | | | | | | # Convert to it to Python | | | | MyClass = JClass(myClassJava) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Load a class with a | .. code-block:: java | .. code-block:: python | | external class loader | | | | | ClassLoader cl | cl = ExternalClassLoader() | | | = new ExternalClassLoader(); | cls = JClass("External", loader=cl) | | | Class cls | | | | = Class.forName("External", | | | | True, cl) | | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Accessing base method | | .. code-block:: python | | implementation | | | | | | from org.pkg import \ | | | | BaseClass, MyClass | | | | myObject = MyClass(1) | | | | BaseClass.callMember(myObject, 2) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [20] This is prohibited after Java 8 .. [21] types must be exactly specified. .. [22] Rarely required unless the class was supplied external such as generics. Implements and Extension ------------------------ JPype can implement a Java interface by annotating a Python class. Each method that is required must be implemented. JPype does not support extending a class directly in Python. Where it is necessary to exend a Java class, it is required to create a Java extension with an interface for each methods that are to be accessed from Python. +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | Description | Java | Python | +===========================+=========================================================+=========================================================+ | | | | | Implement an interface | .. code-block:: java | .. code-block:: python | | | | | | | public class PyImpl | @JImplements(MyInterface) | | | implements MyInterface | class PyImpl(object): | | | { | @JOverride | | | public void call() | def call(self): | | | {...} | pass | | | } | | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | None | | Extending classes [23]_ | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ | | | | | Lambdas [24]_ | .. code-block:: java | .. code-block:: python | | | | | | | DoubleUnaryOperator u = (p->p*2); | u=DoubleUnaryOperator@(lambda x: x*2) | | | | | +---------------------------+---------------------------------------------------------+---------------------------------------------------------+ .. [23] Support for use of Python function as Java 8 lambda is WIP. .. [24] Any Java functional interface can take a lambda or callable. Don't like the formatting? Feel the guide is missing something? Submit a pull request at the project page.