Skip to content

Latest commit

 

History

History
722 lines (647 loc) · 80.9 KB

quickguide.rst

File metadata and controls

722 lines (647 loc) · 80.9 KB
Raw

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 userguide and 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.

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 Machine (JVM)

.. code-block:: python

# 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 Machine (JVM) with a classpath

.. code-block:: python

# Launch the JVM jpype.startJVM(classpath = ['jars/*'])
Import default Java namespace

.. code-block:: python

import java.lang
Add a set of jars from a directory

.. code-block:: python

jpype.addClassPath("/my/path/*")
Add a specific jar to the classpath

.. code-block:: python

jpype.addClassPath('/my/path/myJar.jar')
Print JVM CLASSPATH

.. code-block:: python

from java.lang import System print(System.getProperty("java.class.path"))

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

.. code-block:: java

import org.pkg.MyClass

.. code-block:: python

from org.pkg import MyClass
Import a class and rename

.. code-block:: python

from org.pkg import MyClass as OurClass
Import multiple classes from a package

.. code-block:: python

from org.pkg import MyClass, AnotherClass
Import a java package for long name access

.. code-block:: python

import org.pkg
Import a class static

.. code-block:: java

import org.pkg.MyClass.CONST_FIELD

.. code-block:: python

from org.pkg.MyClass import CONST_FIELD
Import a class without tld

.. code-block:: java

import zippy.NonStandard

.. code-block:: python

NonStandard = JClass('zippy.NonStandard')
Construct an object

.. code-block:: java

MyClass myObject = new MyClass(1);

.. code-block:: python

myObject = MyClass(1)
Constructing a class with full class name

.. code-block:: python

import org.pkg myObject = org.pkg.MyClass(args)
Get a static field

.. code-block:: java

int var = MyClass.staticField;

.. code-block:: python

var = MyClass.staticField
Get a member field

.. code-block:: java

int var = myObject.memberField;

.. code-block:: python

var = myObject.memberField
Set a static field

.. code-block:: java

MyClass.staticField = 2;

.. code-block:: python

MyClass.staticField = 2
Set a member field

.. code-block:: java

myObject.memberField = 2;

.. code-block:: python

myObject.memberField = 2
Call a static method

.. code-block:: java

MyClass.callStatic(1);

.. code-block:: python

MyClass.callStatic(1)
Call a member method

.. code-block:: java

myObject.callMember(1);

.. code-block:: python

myObject.callMember(1)
Access member with Python naming conflict

.. code-block:: java

myObject.pass()

.. code-block:: python

myObject.pass()
Checking inheritance

.. code-block:: java

if (obj instanceof MyClass) {...}

.. code-block:: python

if (isinstance(obj, MyClass): ...
Checking if Java class wrapper

.. code-block:: python

if (isinstance(obj, JClass): ...
Checking if Java object wrapper

.. code-block:: python

if (isinstance(obj, JObject): ...
Casting to a specific type

.. code-block:: java

BaseClass b = (BaseClass)myObject;

.. code-block:: python

b = (BaseClass) @ myObject

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

try {

myObject.throwsException();

} catch (java.lang.Exception ex) { ... }

.. code-block:: python

try:

myObject.throwsException()

except java.lang.Exception as ex:

...
Throw an exception to Java

.. code-block:: java

throw new java.lang.Exception(

"Problem");

.. code-block:: python

raise java.lang.Exception(

"Problem")
Checking if Java exception wrapper

.. code-block:: python

if (isinstance(obj, JException): ...
Closeable items

.. code-block:: java

try (InputStream is

= Files.newInputStream(file))

{ ... }

.. code-block:: python

with Files.newInputStream(file) as is:

...

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 overload

.. code-block:: java

myObject.call((int)v);

.. code-block:: python

myObject.call(JInt(v))
Create a primitive array

.. code-block:: java

int[] array = new int[5]

.. code-block:: python

array = JInt[5]
Create a rectangular primitive array

.. code-block:: java

int[][] array = new int[5][10]

.. code-block:: python

array = JInt[5, 10]
Create an array of arrays

.. code-block:: java

int[][] array = new int[5][]

.. code-block:: python

array = JInt[5, :]
Create an initialized primitive array

.. code-block:: java

int[] array = new int[]{1,2,3}

.. code-block:: python

array = JInt[:]([1,2,3])
Create an initialized boxed array

.. code-block:: java

Integer[] array = new Integer[]{1,2,3}

.. code-block:: python

array = java.lang.Integer[:]([1,2,3])
Put a specific primitive type on a list

.. code-block:: java

List<Integer> myList

= new ArrayList<>();

myList.add(1);

.. code-block:: python

from java.util import ArrayList myList = ArrayList() myList.add(JInt(1))
Boxing a primitive

.. code-block:: java

Integer boxed = 1;

.. code-block:: python

boxed = JObject(JInt(1))

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

String javaStr = new String("foo");

.. code-block:: python

myStr = JString("foo")
Create a Java string from bytes

.. code-block:: java

byte[] b; String javaStr = new String(b, "UTF-8");

.. code-block:: python

b= b'foo' myStr = JString(b, "UTF-8")
Converting Java string

.. code-block:: python

str(javaStr)
Comparing Python and Java strings

.. code-block:: python

str(javaStr) == pyString
Comparing Java strings

.. code-block:: java

javaStr.equals("foo")

.. code-block:: python

javaStr == "foo"
Checking if Java string

.. code-block:: python

if (isinstance(obj, JString): ...

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 array

.. code-block:: java

MyClass[] array = new MyClass[5];

.. code-block:: python

array = MyClass[5]
Create a multi dimension array (old)

.. code-block:: java

MyClass[][] array2 = new MyClass[5][];

.. code-block:: python

array2 = JArray(MyClass, 2)(5)
Create a multi dimension array (new)

.. code-block:: java

MyClass[][] array2 = new MyClass[5][];

.. code-block:: python

array2 = MyClass[5,:]
Access an element

.. code-block:: java

array[0] = new MyClass()

.. code-block:: python

array[0] = MyClass()
Size of an array

.. code-block:: java

array.length

.. code-block:: python

len(array)
Get last element

.. code-block:: java

MyClass a = array[array.length];

.. code-block:: python

a = array[-1]
Slice an array

.. code-block:: python

a = array[2:5]
Clone an array

.. code-block:: java

MyClass[] a = array.clone();

.. code-block:: python

a = array.clone()
Convert to Python list

.. code-block:: python

pylist = list(array)
Iterate elements

.. code-block:: java

for (MyClass element: array) {...}

.. code-block:: python

for element in array:

...
Checking if java array wrapper

.. code-block:: python

if (isinstance(obj, JArray): ...

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

import java.util.ArrayList;

.. code-block:: python

from java.util import ArrayList
Construct a list

.. code-block:: java

List<Integer> myList=new ArrayList<>();

.. code-block:: python

myList=ArrayList()
Get length of list

.. code-block:: java

int sz = myList.size();

.. code-block:: python

sz = len(myList)
Get list item

.. code-block:: java

Integer i = myList.get(0)

.. code-block:: python

i = myList[0]
Set list item

.. code-block:: java

myList.set(0, 1)

.. code-block:: python

myList[0]=Jint(1)
Iterate list elements

.. code-block:: java

for (Integer element: myList) {...}

.. code-block:: python

for element in myList:

...
Import map type

.. code-block:: java

import java.util.HashMap;

.. code-block:: python

from java.util import HashMap
Construct a map

.. code-block:: java

Map<String,Integer> myMap = new HashMap<>();

.. code-block:: python

myMap = HashMap()
Get length of map

.. code-block:: java

int sz = myMap.size();

.. code-block:: python

sz = len(myMap)
Get map item

.. code-block:: java

Integer i = myMap.get("foo")

.. code-block:: python

i = myMap["foo"]
Set map item

.. code-block:: java

myMap.set("foo", 1)

.. code-block:: python

myMap["foo"] = Jint(1)
Iterate map entries

.. code-block:: java

for (Map.Entry<String,Integer> e

: myMap.entrySet()) {...}

.. code-block:: python

for e in myMap.entrySet():

...

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 class

.. code-block:: java

MyClass.class

.. code-block:: python

MyClass.class
Access a private field by name

.. code-block:: python

cls = myObject.class field = cls.getDeclaredField( "internalField") field.setAccessible(True) field.get()
Accessing a specific overload

.. code-block:: python

cls = MyClass.class cls.getDeclaredMethod("call", JInt) cls.invoke(myObject, JInt(1))
Convert a java.lang.Class into Python wrapper

.. code-block:: python

# Something returned a java.lang.Class MyClassJava = getClassMethod()

# Convert to it to Python MyClass = JClass(myClassJava)
Load a class with a external class loader

.. code-block:: java

ClassLoader cl

= new ExternalClassLoader();

Class cls
= Class.forName("External",

True, cl)

.. code-block:: python

cl = ExternalClassLoader() cls = JClass("External", loader=cl)
Accessing base method implementation

.. code-block:: python

from org.pkg import BaseClass, MyClass myObject = MyClass(1) BaseClass.callMember(myObject, 2)

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

public class PyImpl

implements MyInterface

{

public void call() {...}

}

.. code-block:: python

@JImplements(MyInterface) class PyImpl(object): @JOverride def call(self): pass
Extending classes None
Lambdas

.. code-block:: java

DoubleUnaryOperator u = (p->p*2);

.. code-block:: python

u=DoubleUnaryOperator@(lambda x: x*2)

Don't like the formatting? Feel the guide is missing something? Submit a pull request at the project page.