JPype User Guide¶

Why Use JPype?¶

JPype makes it easy to integrate Python and Java, enabling developers to:

1. Access Java libraries directly from Python code.

2. Debug Java data structures interactively using Python tools.

3. Use Python’s flexibility for scientific computing while leveraging Java’s robustness for enterprise applications.

Prerequisites¶

Before using JPype, ensure the following:

1. Python: JPype requires Python 3.8 or later. Check your Python version by running:

   python --version
   

2. Java: JPype requires a Java Runtime Environment (JRE) or Java Development Kit (JDK) version 11 or later. Check your Java version by running:

   java -version
   

3. Architecture Compatibility: Ensure the Python interpreter and JVM have matching architectures (e.g., both 64-bit or both 32-bit).

Installation¶

JPype can be installed using either pip or conda.

pip install JPype1

conda install -c conda-forge jpype1

import jpype
print("JPype installed successfully!")

Your First JPype Program¶

Follow these steps to write and run your first JPype program:

import jpype

# Start the JVM
jpype.startJVM(classpath=[])

from java.lang import String

java_string = String("Hello from Java!")
print(java_string.toUpperCase())  # Output: HELLO FROM JAVA!

import jpype
import jpype.imports

# Start the JVM
jpype.startJVM(classpath=["../jar/*","../classes","com.amce-1.0.jar"])

# Import Java classes
from java.lang import String

# Use the Java String class
java_string = String("Hello from Java!")
print(java_string.toUpperCase())  # Output: HELLO FROM JAVA!

python hello_jpype.py

HELLO FROM JAVA!

Next Steps¶

Once you’ve successfully set up JPype, explore the following topics:

1. Accessing Java Libraries: Learn how to use JPype to interact with third- party Java libraries.

2. Working with Java Collections: Discover how JPype integrates Java collections with Python’s collections module.

3. Implementing Java Interfaces in Python: Use JPype’s proxy functionality to implement Java interfaces in Python.

4. Debugging Java Code: Use JPype as an interactive shell for debugging Java programs.

Summary of JPype¶

JPype bridges Python and Java, enabling seamless integration between the two languages. With JPype, you can access Java libraries, implement Java interfaces, and debug Java code—all from the comfort of Python. Happy coding!

Case 1: Access to a Java library¶

Suppose you are a hard core Python programmer. You can easily use lambdas, threading, dictionary hacking, monkey patching, been there, done that. You are hard at work on your latest project but you just need to pip in the database driver for your customers database and you can call it a night. Unfortunately, it appears that your customers database will not connect to the Python database API. The whole thing is custom and the customer isn’t going to supply you with a Python version. They did send you a Java driver for the database but fat lot of good that will do for you.

Stumbling through the internet you find a module that says it can natively load Java packages as Python modules. Well, it’s worth a shot…

So first thing the guide says is that you need to install Java and set up a JAVA_HOME environment variable pointing to the JRE. Then start the JVM with classpath pointed to customers jar file. The customer sent over an example in Java so you just have to port it into Python.

package com.paying.customer;

import com.paying.customer.DataBase

public class MyExample {
   public void main(String[] args) {
     Database db = new Database("our_records");
     try (DatabaseConnection c = db.connect())
     {
        c.runQuery();
        while (c.hasRecords())
        {
          Record record = db.nextRecord();
          ...
        }
     }
  }
}

It does not look too horrible to translate. You just need to look past all those pointless type declarations and meaningless braces. Once you do, you can glue this into Python and get back to what you really love, like performing dictionary comprehensions on multiple keys.

You glance over the JPype quick start guide. It has a few useful patterns… set the class path, start the JVM, remove all the type declarations, and you are done.

# Boiler plate stuff to start the module
import jpype
import jpype.imports
from jpype.types import *

# Launch the JVM
jpype.startJVM(classpath=['jars/database.jar'])

# import the Java modules
from com.paying.customer import DataBase

# Copy in the patterns from the guide to replace the example code
db = Database("our_records")
with db.connect() as c:
    c.runQuery()
    while c.hasRecords():
        record = db.nextRecord()
        ...

Launch it in the interactive window. You can get back to programming in Python once you get a good night sleep.

Case 2: Visualization of Java structures¶

Suppose you are a hard core Java programmer. Weakly typed languages are for wimps, if it isn’t garbage collected it is garbage. Unfortunately your latest project has suffered a nasty data structure problem in one of the threads. You managed to capture the data structure in a serialized form but if you could just make graph and call a few functions this would be so much easier. But the interactive Java shell that you are using doesn’t really have much in the way of visualization and you don’t have time to write a whole graphing applet just to display this dataset.

So poking around on the internet you find that Python has exactly the visualization that you need for the problem, but it only runs in CPython. So in order to visualize the structure, you need to get it into Python, extract the data structures and, send it to the plotting routine.

You install conda, follow the install instructions to connect to conda-forge, pull JPype1, and launch the first Python interactive environment that appear to produce a plot.

You get the shell open and paste in the boilerplate start commands, and load in your serialized object.

import jpype
import jpype.imports

jpype.startJVM(classpath = ['jars/*', 'test/classes'])

from java.nio.file import Files, Paths
from java.io import ObjectInputStream

with Files.newInputStream(Paths.get("myobject.ser")) as stream:
    ois = ObjectInputStream(stream)
    obj = ois.readObject()

print(obj)  # prints org.bigstuff.MyObject@7382f612

It appears that the structure is loaded. The problematic structure requires you call the getData method with the correct index.

d = obj.getData(1)

> TypeError: No matching overloads found for org.bigstuff.MyObject.getData(int),
> options are:
       public double[] org.bigstuff.MyObject.getData(double)
       public double[] org.bigstuff.MyObject.getData(int)

Looks like you are going to have to pick the right overload as it can’t figure out which overload to use. Darn weakly typed language, how to get the right type in so that you can plot the right data. It says that you can use the casting operators.

from jpype.types import *
d = obj.getData(JInt(1))
print(type(d))  # prints double[]

Great. Now you just need to figure out how to convert from a Java array into something our visualization code can deal with. As nothing indicates that you need to convert the array, you just copy out of the visualization tool example and watch what happens.

import matplotlib.pyplot as plt
plt.plot(d)
plt.show()

A graph appears on the screen. Meaning that NumPy has not issue dealing with Java arrays. It looks like ever 4th element in the array is zero. It must be the PR the new guy put in. And off you go back to the wonderful world of Java back to the safety of curly braces and semicolons.

Case 3: Interactive Java¶

Suppose you are a laboratory intern running experiments at Hawkins National Laboratory. (For the purpose of this exercise we will ignore the fact that Hawkins was shut down in 1984 and Java was created in 1995). You have the test subject strapped in and you just need to start the experiment. So you pull up Jupyter notebook your boss gave you and run through the cells. You need to add some heart wave monitor to the list of graphed results.

The relevant section of the API for the Experiment appears to be

package gov.hnl.experiment;

public interface Monitor {
   public void onMeasurement(Measurement measurement);
}

public interface Measurement {
   public double getTime();
   public double getHeartRate();
   public double getBrainActivity();
   public double getDrugFlowRate();
   public boolean isNoseBleeding();
}

public class Experiment {
   public void addCondition(Instant t, Condition c);
   public void addMoniter(Monitor m);
   public void run();
}

The notebook already has all the test conditions for the experiment set up and the JVM is started, so you just need to implement the monitor.

Based on the previous examples, you start by defining a monitor class

from jpype import JImplements, JOverride
from gov.hnl.experiment import Monitor

@JImplements(Monitor)
class HeartMonitor:
    def __init__(self):
        self.readings = []
    @JOverride
    def onMeasurement(self, measurement):
        self.readings.append([measurement.getTime(), measurement.getHeartRate()])
    def getResults(self):
        return np.array(self.readings)

There is a bit to unpack here. You have implemented a Java class from within Python. The Java implementation is simply an ordinary Python class which has be decorated with @JImplements and @JOverride. When you forgot to place the @JOverride, it gave you the response:

NotImplementedError: Interface 'gov.hnl.experiment.Monitor' requires
method 'onMeasurement' to be implemented.

But once you added the @JOverride, it worked properly. The subject appears to be getting impatient so you hurry up and set up a short run to make sure it is working.

hm = HeartMonitor()
experiment.addMonitor(hm)
experiment.run()
readings = hm.getResults()
plt.plot(readings[:,0], readings[:,1)
plt.show()

To your surprise, it says unable to find method addMonitor with an error message:

AttributeError: 'gov.hnl.experiment.Experiment' object has no attribute 'addMonitor'

You open the cell and type experiment.add<TAB>. The line completes with experiment.addMoniter. Whoops, looks like there is typo in the interface. You make a quick correction and see a nice plot of the last 30 seconds pop up in a window. Job well done, so you set the runtime back to one hour. Looks like you still have time to make the intern woodlands hike and forest picnic. Though you wonder if maybe next year you should sign up for another laboratory. Maybe next year, you will try to sign up for those orbital lasers the President was talking about back in March. That sounds like real fun.

(This advanced demonstration utilized the concept of Proxies and Code completion)

Supported JVM-Based Languages¶

1. Kotlin:

   • Kotlin is a modern JVM-based language that emphasizes conciseness and safety. JPype can interact with Kotlin libraries and classes just as it does with Java.

   • Kotlin’s null safety and extension functions are fully compatible with JPype, though developers may need to handle Kotlin’s nullable types explicitly when working in Python.

   • Example: Using Kotlin’s List class in Python via JPype.

from kotlin.collections import List
my_list = List.of("apple", "orange", "banana")
print(my_list.size())  # Access Kotlin methods

2. Scala:

   • Scala combines object-oriented and functional programming paradigms, making it a popular choice for big data and distributed systems.

   • JPype can interact with Scala libraries, including those built on frameworks like Akka or Spark.

   • Scala’s collections and functional constructs (e.g., map, flatMap) can be accessed directly from Python, though some functional idioms may require adaptation.

from scala.collection.mutable import ArrayBuffer
buffer = ArrayBuffer()
buffer.append(1)
buffer.append(2)
print(buffer.mkString(", "))  # Outputs: "1, 2"

3. Groovy:

   • Groovy is a dynamic language for the JVM, often used for scripting and lightweight application development.

   • JPype can interact with Groovy scripts and libraries, enabling Python developers to leverage Groovy’s concise syntax and dynamic capabilities.

   • Groovy’s dynamic typing aligns well with Python, but accessing from within JPype may cause difficulties.

from groovy.util import Eval
result = Eval.me("3 + 5")
print(result)  # Outputs: 8

4. Clojure:

   • Clojure is a functional programming language that runs on the JVM. Its emphasis on immutability and concurrency makes it ideal for certain types of applications.

   • JPype can interact with Clojure libraries, though developers may need to adapt to Clojure’s Lisp-like syntax and functional paradigms.

from clojure.lang import PersistentVector
vector = PersistentVector.create([1, 2, 3])
print(vector.nth(1))  # Access elements using Clojure methods

Using JPype with Other JVM Languages¶

JPype can be used with JVM-based languages, but the following considerations apply:

1. Language-Specific Features:

   • Each language introduces unique features (e.g., Kotlin’s null safety, Scala’s functional constructs, Groovy’s dynamic typing). These may require adaptation when working with Python.

2. Interoperability:

   • JPype relies on the JVM’s native interoperability mechanisms, ensuring seamless interaction with JVM-based languages. However, developers should be aware of differences in naming conventions, type systems, and runtime behavior.

3. Testing and Integration:

   • To fully support a JVM-based language, developers should set up a test bench to exercise its features, write language-specific quick-start guides, and ensure compatibility with JPype’s existing API.

Expanding JPype for Other JVM Languages¶

If you wish to extend JPype’s capabilities for a specific JVM-based language, the following steps are recommended:

1. Create a Test Bench:

   • Set up a test environment for your language under JPype’s test directory. Use Ivy or Maven to pull in the required JAR files and exercise the language’s unique features.

2. Write a Language-Specific Guide:

   • Document how your language interacts with JPype, highlighting differences from Java and providing examples for common use cases.

3. Set Up a Test Harness:

   • Build a test harness to verify compatibility for each language feature. Place the setup script (e.g., test_kotlin, test_scala) alongside JPype’s existing tests.

Conclusion on Languages¶

JPype’s ability to interact with JVM-based languages opens up exciting possibilities for Python developers. Whether you’re working with Kotlin’s modern syntax, Scala’s functional paradigms, Groovy’s dynamic scripting, or Clojure’s immutability, JPype provides a powerful bridge to leverage the strengths of these languages within Python. By following the steps outlined above, you can ensure smooth integration and expand JPype’s capabilities for your specific needs.

Py4J¶

Py4J is a Python library that enables communication with a JVM through a remote tunnel. Unlike JPype, which embeds the JVM directly into the Python process using JNI, Py4J operates the JVM as a separate process, allowing Python and Java to run independently. This separation introduces several unique advantages:

1. Cross-Architecture Compatibility: Py4J allows Python and Java to run on different architectures or platforms. For example, you can run Python on a 64-bit architecture while connecting to a 32-bit JVM, or even run Python and Java on entirely different machines. This flexibility is particularly useful for distributed systems or environments where the Python and Java components have different hardware or software requirements.

2. Restartable Java Sessions: Because Py4J operates the JVM as a separate process, it is possible to stop and restart the JVM without restarting the Python process. This is a feature frequently requested by JPype users but is not feasible with JPype due to its use of JNI, which tightly couples the Python and Java memory spaces. Py4J’s ability to restart the JVM makes it suitable for applications requiring dynamic lifecycle management of the Java environment.

3. Memory Isolation: Since Python and Java run in separate processes, Py4J provides complete memory isolation between the two environments. This ensures that a crash in the JVM does not affect the Python process and vice versa. Such isolation can be critical for applications requiring high reliability and fault tolerance.

4. RPC-Style Communication: Py4J operates more like a remote procedure call (RPC) framework, where Python sends commands to the JVM and receives responses. While this approach is less integrated than JPype’s direct JNI-based interaction, it is intended for applications where tight coupling between Python and Java is not required.

Despite these advantages, Py4J has some limitations compared to JPype:

• Performance: The remote communication introduces a transfer penalty when moving data between Python and Java, making Py4J less suitable for applications requiring high-performance data exchange.

• Integration: Py4J does not provide the seamless integration of Java objects into Python syntax that JPype offers. For example, Java collections and arrays do not behave like native Python objects.

Py4J is a good choice for applications requiring cross-architecture compatibility, restartable JVM sessions, or memory isolation between Python and Java. However, for applications needing tight integration and high-performance data exchange, JPype may be a better fit.

Jep¶

Jep stands for Java embedded Python. It is designed to allow Java to access Python as a sub-interpreter. The syntax for accessing Java resources from within the embedded Python is similar to JPype, with support for imports. However, Jep has limitations due to Python’s sub-interpreter model, which restricts the use of many Python modules. Additionally, Jep’s documentation is sparse, making it difficult to assess its full capabilities without experimentation. Jep is best suited for applications where Java needs to embed Python for scripting purposes.

PyJnius¶

PyJnius <https://github.com/kivy/pyjnius>_ is another Python-to-Java bridge. Its syntax is somewhat similar to JPype, allowing classes to be loaded and accessed with Java-native syntax. PyJnius supports customization of Java classes to make them appear more Pythonic. However, PyJnius lacks support for primitive arrays, requiring Python lists to be converted manually whenever an array is passed as an argument or return value. This limitation makes PyJnius less suitable for scientific computing or applications requiring efficient array manipulation. PyJnius is actively developed and is particularly focused on Android development, making it a strong choice for mobile applications requiring Python-Java integration.

Jython¶

Jython <https://www.jython.org/>_ is a reimplementation of Python in Java. It allows Python code to run directly on the JVM, providing seamless access to Java libraries. Jython, while limited to Python 2, played a significant role in bridging Python and Java in earlier development eras. It may still be useful for legacy systems or environments where Python 2 compatibility is required. Its development has largely stalled, and it lacks support for popular Python libraries like NumPy and pandas, making it unsuitable for modern applications.

Javabridge¶

Javabridge provides direct low-level JNI control from Python. Its integration level is low, offering only the JNI API to Python rather than attempting to wrap Java in a Python-friendly interface. While Javabridge can be useful for advanced users familiar with JNI, it requires significant expertise to use effectively. Javabridge is best suited for applications needing fine-grained control over JNI interactions.

JCC¶

JCC is a C++ code generator that produces a C++ object interface wrapping a Java library via JNI. JCC also generates C++ wrappers conforming to Python’s C type system, making instances of Java classes directly available to a Python interpreter. JCC is actively maintained as part of PyLucene and is useful for exposing specific Java libraries to Python rather than providing general Java access. It is best suited for applications requiring tight integration with libraries like Apache Lucene. It is best suited for applications requiring tight integration with specific Java libraries.

Key Features of the Guide¶

• No JNI Knowledge Required: JPype abstracts away the complexities of the Java Native Interface (JNI). Users do not need to understand JNI concepts or its naming conventions to use JPype effectively. In fact, relying on JNI knowledge may lead to incorrect assumptions about the JPype API. Where JNI imposes limitations, the guide explains the consequences in practical programming terms.

• Python 3 Compatibility: JPype supports only Python 3. All examples in this guide use Python 3 syntax and assume familiarity with Python’s new-style object model. If you’re using an older version of Python, you will need to upgrade to Python 3 to use JPype.

• Java Naming Conventions: JPype adheres to Java’s naming conventions for methods and fields to ensure consistency and avoid potential name collisions. While this may differ from Python’s conventions, it is a deliberate choice to maintain compatibility with Java libraries and APIs.

By following this guide, you’ll learn how to use JPype to seamlessly integrate Python and Java, unlocking the strengths of both languages in your projects.

Getting JPype started¶

This document holds numerous JPype examples. For the purposes of clarity the module is assumed to have been started with the following command

# Import the module
import jpype

# Allow Java modules to be imported
import jpype.imports

# Import all standard Java types into the global scope
from jpype.types import *

# Import each of the decorators into the global scope
from jpype import JImplements, JOverride, JImplementationFor

# Start JVM with Java types on return
jpype.startJVM()

# Import default Java packages
import java.lang
import java.util

This is not the only style used by JPype users. Some people feel it is best to limit the number for symbols in the global scope and instead start with a minimalistic approach.

import jpype as jp                 # Import the module
jp.startJVM()                      # Start the module

Either style is usable and we do not wish to force any particular style on the user. But as the extra jp. tends to just clutter up the space and implies that JPype should always be used as a namespace due to namespace conflicts, we have favored the global import style. JPype only exposes 40 symbols total including a few deprecated functions and classes. The 13 most commonly used Java types are wrapped in a special module jpype.types which can be used to import all for the needed factories and types with a single command without worrying about importing potentially problematic symbols.

We will detail the starting process more later in the guide. See Starting the JVM.

Core Concepts¶

1. Type Factories:

   • Type factories allow you to declare specific Java types in Python. These factories produce wrapper classes for Java types.

   • Examples include JClass for Java classes and JArray for Java arrays.

   • Factories also exist for implementing Java classes from within Python using proxies (e.g., JProxy).

2. Meta Classes:

   • Meta classes describe properties of Java classes, such as whether a class is an interface.

   • Example: JInterface can be used to check if a Java class is an interface.

3. Base Classes:

   • JPype provides base classes for common Java types, such as Object, String, and Exception.

   • These classes can be used for convenience, such as catching all Java exceptions with JException.

   • Example: java.lang.Throwable can be caught using JException.

4. Wrapper Classes:

   • Wrapper classes correspond to individual Java classes and are dynamically created by JPype. These wrappers encapsulate Java objects and provide a Pythonic interface for interacting with them. Depending on the context, a wrapper may contain a Java reference, such as a class instance, primitive array, or boxed type or a Java proxy which implements dynamically implements a Java interface.

   • Wrappers are designed to make Java objects behave like native Python objects, enabling seamless integration between Python and Java. These wrappers provide a Pythonic interface to Java objects, making them behave like native Python objects while retaining their Java functionality.

   • They allow access to static variables, static methods, constructors, and casting.

   • Example: java.lang.Object, java.lang.String.

5. Object Instances:

   • These are Java objects created or accessed within Python. They behave like Python objects, with Java fields mapped to Python attributes and Java methods mapped to Python methods.

   • Example: A Java String object can be accessed and manipulated like a Python string.

6. Primitive Types:

   • JPype maps Java’s primitive types (e.g., boolean, int, float) into Python classes.

   • Example: JInt, JFloat, JBoolean.

7. Decorators:

   • JPype provides decorators to augment Python classes and methods with Java-specific functionality.

   • Examples include @JImplements for implementing Java interfaces and @JOverride for overriding Java methods.

8. Mapping Java Syntax to Python:

   • JPype maps Java syntax to Python wherever possible. For example:

     • Java’s try, throw, and catch are mapped to Python’s try, raise, and except.

     • Java’s synchronized keyword is mapped to Python’s with statement using jpype.synchronized.

9. JVM Control Functions:

   • JPype provides functions for controlling the JVM, such as starting and shutting it down.

   • Examples: jpype.startJVM() and jpype.shutdownJVM().

Additional Details¶

• Name Mangling:

  • JPype handles naming conflicts between Java and Python by appending an underscore (_) to conflicting names.

  • Example: A Java method named with will appear as with_ in Python.

  • For details see Name Mangling.

• Lifetime Management:

  • Java objects remain alive as long as their corresponding Python handles exist. Once the Python handle is disposed, the Java object is eligible for garbage collection.

By understanding these core concepts, you can effectively use JPype to integrate Python and Java, leveraging the strengths of both languages.

Best Practices on JVM Startup¶

Starting the Java Virtual Machine (JVM) correctly is critical for ensuring the smooth operation of JPype-based applications. A well-configured JVM startup process minimizes runtime issues, optimizes performance, and ensures compatibility with the required Java libraries. This section provides a detailed explanation of best practices to guide developers in setting up the JVM effectively.

1. Start the JVM Early The JVM should always be started early in the application lifecycle. By initializing the JVM at the beginning of your program, you can avoid issues related to delayed imports or incomplete initialization. This approach ensures that all Java classes and libraries required by your application are properly loaded and accessible throughout the program’s execution.

2. Configure the Classpath Explicitly Classpath configuration is another essential consideration. The classpath specifies the location of Java classes and JAR files that the JVM needs to load. For optimal results, explicitly define the classpath when starting the JVM. This can be done using the classpath argument in the startJVM() function or dynamically through the addClassPath() method prior to JVM startup. Explicit configuration prevents errors caused by missing dependencies and ensures that the correct versions of libraries are loaded.

3. Disable Automatic String Conversion When dealing with large-scale data transfers or computationally intensive operations, it is advisable to disable automatic string conversion by setting the convertStrings argument to False. This prevents unnecessary overhead caused by automatic conversion of Java strings to Python strings, allowing developers to retain control over string handling and improve performance. While enabling automatic string conversion may seem convenient, it is considered a legacy option and should be avoided in modern applications.

4. Avoid Restarting the JVM It is important to note that the JVM cannot be restarted once it has been shut down. Therefore, design your application to start the JVM once and keep it running for the program’s lifetime. Attempting to restart the JVM will result in errors due to lingering references and resource conflicts. This limitation underscores the importance of careful planning when initializing the JVM.

5. Optimize Data Transfers When Python and Java need to exchange large amounts of data, such as arrays or complex structures, the efficiency of these transfers can significantly impact application performance. Without optimization, frequent back-and- forth calls between Python and Java can create bottlenecks, especially in computationally intensive applications like scientific computing or machine learning.

   To ensure smooth data exchange, consider the following strategies:

   1. Use NumPy Arrays: NumPy arrays integrate seamlessly with JPype and allow fast, memory-efficient data transfers to Java. For example, a NumPy array can be mapped directly to a Java primitive array, enabling high-speed operations without unnecessary copying.

   2. Leverage Java Buffers: Java’s nio buffers provide a mechanism for shared memory between Python and Java. These buffers are particularly useful for large datasets or memory-mapped files, as they eliminate the overhead of repeated conversions and allow both languages to operate on the same memory space.

   3. Cache Java Objects: If a Java object is used repeatedly in Python, consider caching it to reduce the frequency of cross-language calls. This avoids redundant conversions and improves overall runtime efficiency.

   4. Validate Data Structures: Ensure that arrays or collections being transferred are rectangular and compatible with the expected Java types. For example, jagged arrays or incompatible data types can lead to errors or performance degradation.

   By implementing these strategies, you can optimize the interaction between Python and Java, ensuring that your application performs efficiently even when handling large-scale data or computationally intensive tasks.

6. Handle Exceptions Properly Exception handling is another key aspect of JVM startup. Always catch Java exceptions using jpype.JException or specific Java exception classes to ensure robust error handling. When debugging issues, the stacktrace() method can provide detailed information about Java exceptions, helping developers identify and resolve problems effectively.

7. Document Your Setup Finally, document the JVM startup process and configuration settings clearly within your codebase. This practice not only aids in debugging but also ensures that other developers working on the project can understand and replicate the setup. By adhering to these best practices, you can maximize the reliability, performance, and maintainability of your JPype-based applications.

By adhering to these best practices, you can maximize the performance, reliability, and maintainability of your JPype-based applications.

Java conversions¶

A conversion is a permitted change from an object of one type to another. Conversions have three different degrees. These are: exact, derived, implicit, and explicit.

Exact conversions are those in which the type of an object is identical. In Java each class has only one definition thus there is no need for an exact conversion. But when dealing with Python we have objects that are effectively identical for which exact conversion rules apply. For example, a Java string and a Python string both bind equally well to a method which requires a string, thus this is an exact conversion for the purposes of bind types.

The next level of conversion is derived. A derived class is one which is a descends from a required type. It is better that implicit but worse than exact. If all of the types in a method match are exact or derived then it will override a method in which one argument is implicit.

The next level of conversion is implicit. An implicit conversion is one that Java would perform automatically. Java defines a number of other conversions such as converting a primitive to a boxed type or from a boxed type back to a primitive as implicit conversions. Python conversions defined by the user are also considered to be implicit.

Of course not every cast is safe to perform. For example, converting an object whose type is currently viewed as a base type to a derived type is not performed automatically nor is converting from one boxed type to another. For those operations the conversion must be explicitly requested, hence these are explicit conversions. In Java, a cast is requested by placing the type name in parentheses in front of the object to be cast. Python does not directly support Java casting syntax. To request an explicit conversion an object must be “cast” using a cast operator @. Overloaded methods with an explicit argument will not be matched. After applying an explicit cast, the match quality can improve to exact or derived depending on the cast type.

Not every conversion is possible between Java types. Types that cannot be converted are considerer to be conversion type “none”.

Details on how method overloads are resolved are given in Method Resolution. Details on the standard conversions provided by JPype are given in the section Type Matching.

Java casting¶

To access a casting operation we use the casting JObject wrapper. For example, JObject(object, Type) would produce a copy with specified type. The first argument is the object to convert and the second is the type to cast to. The second argument should always be a Java type specified using a class wrapper, a Java class instance, or a string. Casting will also add a hidden class argument to the resulting object such that it is treated as the cast type for the duration of that variable lifespan. Therefore, a variable create by casting is stuck as that type and cannot revert back to its original for the purposes of method resolution.

The object construction and casting are sometimes a bit blurry. For example, when one casts a sequence to a Java list, we will end up constructing a new Java list that contains the elements of the original Python sequence. In general JPype constructors only provide access the Java constructor methods that are defined in the Java documentation. Casting on the other hand is entirely the domain of whatever JPype has defined including user defined casts.

As JObject syntax is long and does not look much like Java syntax, the Python matmul operator is overloaded on JPype types such that one can use the @ operator to cast to a specific Java type. In Java, one would write (Type)object to cast the variable object to Type. In Python, this would be written as Type@object. This can also be applied to array types JLong[:]@[1,2,3], collection types Iterable@[1,2,3] or Java functors DoubleUnaryOperator@(lambda x:x*2). The result of the casting operator will be a Java object with the desired type or raise a TypeError if the cast or conversion is not possible. For Python objects, the Java object will generally be a copy as it is not possible to reflect changes in an array back to Python. If one needs to retrieve the resulting changes keep a copy of the converted array before passing it. For an existing Java object, casting changes the resolution type for the object. This can be very useful when trying to call a specific method overload. For example, if we have a Java a=String("hello") and there were an overload of the method foo between String and Object we would need to select the overload with foo(java.lang.Object@a).

Casting is performed through the Python class JObject. JObject is called with two arguments which are the object to be cast and the type to cast too. The cast first consults the conversion table to decide if the cast it permitted and produces a TypeError if the conversion is not possible.

JObject also serves as a abstract base class for testing if an object instance belongs to Java. All objects that belong to Java will return true when tested with isinstance. Like Python’s sequence, JObject is an abstract base class. No classes actual derive from JObject.

Of particular interest is the concept of Java null. In Java, null is a typeless entity which can be placed wherever an object is taken to indicate that the object is not available. The equivalent concept in Python is None. Thus all methods that accept any object type that permit a null will accept None as an augment with implicit conversion. However, sometime it is necessary to pass an explicit type to the method resolution. To achieve this in JPype use Type@None which will create a null pointer with the desired type. To test if something is null we have to compare the handle to None. This unfortunately trips up some code quality checkers. The idiom in Python is obj is None, but as this only matches things that Python considers identical, we must instead use obj==None.

Casting None is use to specify types when calling between overloads with variadic arguments such as foo(Object a) and foo(Object... many). If we want to call foo(None) is is ambiguous whether we intend to call the first with a null object or the second with a null array. We can resolve the ambiguity with foo(java.lang.Object@None) or foo(java.lang.Object[:]@None)

Type enforcement appears in three different places within JPype. These are whenever a Java method is called, whenever a Java field is set, and whenever Python returns a value back to Java.

JBoolean¶

Represents a logical value (True or False). In JPype, True and False are exact matches for JBoolean. Methods returning a JBoolean will always return a Python bool.

# Example usage
java_boolean = JBoolean(True)
print(java_boolean)  # Output: True

JChar¶

Represents a single character. Java char types are 16-bit Unicode characters, but some Unicode characters require more than 16 bits. JPype maps JChar to Python strings of length 1. While JChar supports numerical operations, modifying characters numerically can corrupt their encoding.

# Example usage
java_char = JChar('A')
print(java_char)  # Output: 'A'

JByte, JShort, JInt, JLong¶

These types represent signed integers of varying sizes:

• JByte: 8 bits

• JShort: 16 bits

• JInt: 32 bits

• JLong: 64 bits

JPype maps these types to Python’s int. Methods returning integer primitives will return Python int values. Methods accepting integer primitives will accept Python integers or any object that can be converted into the appropriate range.

# Example usage
java_int = JInt(42)
print(java_int)  # Output: 42

JFloat, JDouble¶

These types represent floating-point numbers:

• JFloat: 32-bit precision

• JDouble: 64-bit precision

JPype maps these types to Python’s float. Numbers exceeding the range of JFloat or JDouble will result in positive or negative infinity. Range checks are performed when converting Python types, and an OverflowError will be raised if the value is out of bounds.

# Example usage
java_double = JDouble(3.14)
print(java_double)  # Output: 3.14

Classes¶

In JPype, Java classes are instances of the Python type and function like any ordinary Python class. However unlike Python types, Java classes are closed and cannot be extended. To enforce extension restrictions, all Java classes are created from a special private meta class called _jpype._JClass. This gatekeeper ensures that the attributes of classes cannot be changed accidentally nor extended. The type tree of Java is fixed and closed.

All Java classes have the following functionality.

Class constructor

The class constructor is accessed by using the Python call syntax (). This special method invokes a dispatch whenever the class is called as a function. If an matching constructor is found a new Java instance is created and a Python handle to that instance is returned. In the case of primitive types, the constructor creates a Java value with the exact type requested.

Get attribute

The Python . operator gets an attribute from a class with a specified name. If no method or field exists a AttributeError will be raised. For public static methods, the getattr will produce a Python descriptor which can be called to invoke the static method. For public static fields, a Python descriptor will be produced that allows the field to be get or set depending on whether the field is final or not. Public instance methods and instance fields will produce a function that can be applied to a Java object to execute that method or access the field. Function accessors are non-virtual and thus they can provide access to behaviors that have been hidden by a derived class.

Set attribute

In general, JPype only allows the setting of public non-final fields. If you attempt to set any attribute on an object that does not correspond to a settable field it will produce an AttributeError. There is one exception to this rule. Sometime it is necessary to attach addition private meta data to classes and objects. Attributes that begin with an underbar are consider to be Python private attributes. Private attributes handled by the default Python attribute handler allowing these attributes to be attached to to attach data to the Python handle. This data is invisible to Java and it is retained only on the Python instance. If an object with Python meta data is passed to Java and Java returns the object, the new Python handle will not contain any of the attached data as this data was lost when the object was passed to Java.

class_ Attribute

For Java classes there is a special attribute called class. This is a keyword in Python so name mangling applies. This is a class instance of type java.lang.Class. It can be used to access fields and methods.

Inner classes

For methods and fields, public inner classes appear as attributes of the class. These are regular types that can be used to construct objects, create array, or cast.

String

The Java method toString is mapped into the Python function str(obj).

Equality

The Java method equals() has been mapped to Python == with special augmentations for null pointers. Java == is not exposed directly as it would lead to numerous errors. In principle, Java == should map to the Python concept of is but it is not currently possible to overload Python in such a way to achieve the desired effect.

Hash

The Java method hashCode is mapped to Python hash(obj) function. There are special augmentations for strings and nulls. Strings will return the same hash code as returned by Python so that Java strings and Python strings produce the same dictionary lookups. Null pointers produce the same hash value as None.

Java defines hashCode on many objects including mutable ones. Often the hashCode for a mutable object changes when the object is changed. Only use immutable Java object (String, Instant, Boxed types) as dictionary keys or risk undefined behavior.

Java objects are instances of Java classes and have all of the methods defined in the Java class including static members. However, the get attribute method converts public instance members and fields into descriptors which act on the object.

Now that we have defined the basics of Java objects and classes, we will define a few special classes that operate a bit differently.

Array Classes¶

In Java, all arrays are objects, but they cannot define any methods beyond a limited set of Java array operations. These operations have been mapped into Python to their closest Python equivalent.

JArray is an abstract base class for all Java array classes. Thus, you can test if something is an array class using issubclass, and check if a Java object is an array using isinstance.

# Example: Creating array types
int_array_type = JInt[:]
object_array_type = java.lang.Object[:]

# Creating arrays
int_array = int_array_type([1, 2, 3])
object_array = object_array_type([None, "Hello", 42])

print(int_array)  # Output: [1, 2, 3]
print(object_array)  # Output: [null, Hello, 42]

# Example: Creating multidimensional arrays
int_2d_array_type = JInt[:, :]
int_2d_array = int_2d_array_type([[1, 2], [3, 4]])

print(int_2d_array[0][1])  # Output: 2

# Creating a 3D array
double_3d_array_type = JDouble[:, :, :]
double_3d_array = double_3d_array_type([[[1.1, 2.2], [3.3, 4.4]], [[5.5, 6.6], [7.7, 8.8]]])

print(double_3d_array[1][0][1])  # Output: 6.6

# Example: Creating jagged arrays
jagged_int_array_type = JInt[3, :]
jagged_int_array = jagged_int_array_type([[1, 2], [3, 4, 5], [6]])

print(jagged_int_array[1][2])  # Output: 5

orig = [1, 2, 3]
obj = jpype.JInt[:](orig)
a.modifies(obj)   # Modifies the array by multiplying all elements by 2
orig[:] = obj     # Copies all the values back from Java to Python

Buffer classes¶

In addition to array types, JPype also supports Java nio buffer types. Buffers in Java come in two flavors. Array backed buffers have no special access. Direct buffers are can converted to Python buffers with both read and write capabilities.

Each primitive type in Java has its own buffer type named based on the primitive type. java.nio.ByteBuffer has the greatest control allowing any type to be read and written to it. Buffers in Java function are like memory mapped files and have a concept of a read and write pointer which is used to traverse the array. They also have direct index access to their specified primitive type.

Java buffer provide an additional Python method:

Buffer transfer

Buffer transfers from a Java buffer works for a direct buffer. Array backed buffers will raise a BufferError. Use the Python memoryview(jarray) function to create a buffer that can be used to transfer any portion of a Java buffer out. Memory views of Java buffers are readable and writable.

Buffers do not currently support element-wise access.

Boxed Classes¶

Often one wants to be able to place a Java primitive into a method of fields that only takes an object. The process of creating an object from a primitive is referred to as creating a “boxed” object. The resulting object is an immutable object which stores just that one primitive.

Java boxed types in JPype are wrapped with classes that inherit from Python int and float types as both are immutable in Python. This means that a boxed type regardless of whether produced as a return or created explicitly are treated as Python types. They will obey all the conversion rules corresponding to a Python type as implicit matches.

In addition, they produce an exact match with their corresponding Java type. The type conversion for this is somewhat looser than Java. While Java provides automatic unboxing of a Integer to a double primitive, JPype can implicitly convert Integer to a Double boxed.

To box a primitive into a specific type such as to place it into a java.util.List use JObject on the desired boxed type or call the constructor for the desired boxed type directly. For example:

lst = java.util.ArrayList()
lst.add(JObject(JInt(1)))      # Create a Java integer and box it
lst.add(java.lang.Integer(1))  # Explicitly create the desired boxed object

JPype boxed classes have some additional functionality. As they inherit from a mathematical type in Python they can be used in mathematical operations. But unlike Python numerical types they can take an addition state corresponding to being equal to a null pointer. The Python methods are not aware of this new state and will treat the boxed type as a zero if the value is a null.

To test for null, cast the boxed type to a Python type explicitly and the result will be checked. Casting null pointer will raise a TypeError.

b = JObject(None, java.lang.Integer)
a = b+0      # This succeeds and a gets the value of zero
a = int(b)+0 # This fails and raises a TypeError

Boxed objects have the following additional functionality over a normal object.

Convert to index

Integer boxed types can be used as Python indices for arrays and other indexing tasks. This method checks that the value of the boxed type is not null.

Convert to int

Integer and floating point boxed types can be cast into a Python integer using the int() method. The resulting object is always of type int. Casting a null pointer will raise a TypeError.

Convert to float

Integer and floating point boxed types can be cast into a Python float using the float() method. The resulting object is always of type float. Casting a null pointer will raise a TypeError.

Comparison

Integer and floating point types implement the Python rich comparison API. Comparisons for null pointers only succeed for == and != operations. Non-null boxed types act like ordinary numbers for the purposes of comparison.

Number Class¶

The Java class java.lang.Number is a special type in Java. All numerical Java primitives and Python number types can convert implicitly into a Java Number.

Additional user defined conversion are also applied. The primitive types boolean and char and their corresponding boxed types are not considered to numbers in Java.

Object Class¶

Although all classes inherit from Object, the object class itself has special properties that are not inherited. All Java primitives will implicitly convert to their box type when placed in an Object. In addition, a number of Python types implicitly convert to a Java object. To convert to a different object type, explicitly cast the Python object prior to placing in a Java object.

Here a table of the conversions:

In addition it inherits the conversions from java.lang.Number. Additional user defined conversion are also applied.

String Class¶

The String class in Java is a special representation often pointing either to a dynamically created string or to a constant pool item defined in the class. All Java strings are immutable just like Python strings and thus these are considered to be equivalent classes.

Because Java strings are in fact just pointers to blob of bytes they are actually slightly less than a full object in some JVM implementation. This is a violation of the Object Orients (OO) principle, never take something away by inheritance. Unfortunately, Java is a frequent violator of that rule, so this is just one of those exceptions you have to trip over. Therefore, certain operations such as using a string as a threading control with notify or wait may lead to unexpected results. If you are thinking about using a Java string in synchronized statement then remember it is not a real object.

Java strings have a number of additional functions beyond a normal object.

Length

Java strings have a length measured in the number of characters required to represent the string. Extended Unicode characters count for double for the purpose of counting characters. The string length can be determined using the Python len(str) function.

Indexing

Java strings can be used as a sequence of characters in Python and thus each character can be accessed as using the Python indexing operator [].

Hash

Java strings use a special hash function which matches the Python hash code. This ensures that they will always match the same dictionary keys as the corresponding string in Python. The Python hash can be determined using the Python hash(str) function. Null pointers are not currently handled. To get the actually Java hash, use s.hashCode()

Contains

Java strings implement the concept of in when using the Java method contains. The Java implementation is sufficiently similar that it will work fairly well on strings. For example, "I" in java.lang.String("team") would be equal to False.

Testing other types using the in operator will likely raise a TypeError if Java is unable to convert the other item into something that can be compared with a string.

Concatenation

Java strings can be appended to create a new string which contains the concatenation of the two strings. This is mapped to the Python operator +.

Comparison

Java strings are compared using the Java method compareTo. This method does not currently handle null and will raise an exception.

For each

Java strings are treated as sequences of characters and can be used with a for-loop construct and with list comprehension. To iterate through all of the characters, use the Python construct for c in str:.

Unfortunately, Java strings do not yet implement the complete list of requirements to act as Python sequences for the purposes of collections.abc.Sequence.

The somewhat outdated JString factory is a Python class that pretends to be a Java string type. It has the marginal advantage that it can be imported before the JVM is actually started. Once the JVM is started, its class representation is pointed to java.lang.String and can be used to construct a new string object or to test if an object is actually a Java string using isinstance. It does not implement any of the other string methods and just serves as convenience class. The more capable java.lang.String can be imported in place of JString, but only after the JVM is started.

String objects may optionally convert to Python strings when returned from Java methods, though this option is a performance issue and can lead to other difficulties. This setting is selected when the JVM is started. See String Conversions for details.

Java strings will cache the Python conversion so we only pay the conversion cost once per string.

Exception Classes¶

Both Python and Java treat exception classes differently from other objects. Only these types may be caught as part of a try block. Therefore, the exceptions have a special wrapper. Most of the mechanics of exceptions happen under the surface. The one difference between Python and Java is the behavior when the argument is queried. Java arguments can either be the string value, the exception itself, or the internal construction key depending on how the exception came into existence. Therefore, the arguments to a Java exception should never be used as their values are not guaranteed.

Java exception can report their stacktrace to Python in two different ways. If printed through the Python stack trace routine, Java exceptions are split between the Python code that raised and a phantom Java cause which contains the Java exception in Python order. If the debugging information for the Java source is enabled, Python may even print the Java source code lines where the error occurred. If you prefer Java style stack traces then print the result from the stacktrace() method. Unhandled exception that terminate the program will print the Python style stack trace information.

The base class JException is a special type located in jpype.types that can be imported prior to the start of the JVM. This serves as the equivalent of java.lang.Throwable and contains no additional methods. It is currently being phased out in favor of catching the Java type directly.

Using jpype.JException with a class name as a string was supported in previous JPype versions but is currently deprecated. For further information on dealing with exception, see the Exception Handling section. To create a Java exception use JClass or any of the other importing methods.

Anonymous Classes¶

Sometimes Java will produce an anonymous class which does to have any actual class representation. These classes are generated when a method implements a class directly as part of its body and they serve as a closure with access to some of the variables that were used to create it.

For the purpose of JPype these classes are treated as their parents. But this is somewhat problematic when the parent is simply an interface and not an actual object type.

Lambdas¶

The companion of anonymous classes are lambda classes. These are generated dynamically and their parent is always an interface. Lambdas are always Single Abstract Method (SAM) type interfaces. They can implement additional methods in the form of default methods but those are generally not accessible within JPype.

Inner Classes¶

For the most part, inner classes can be used like normal classes, with the following differences:

• Inner classes in Java natively use $ to separate the outer class from the inner class. For example, inner class Foo defined inside class Bar is called Bar.Foo in Java, but its real native name is Bar$Foo.

• Inner classes appear as member of the containing class. Thus to access them import the outer class and call them as members.

• Non-static inner classes cannot be instantiated from Python code. Instances received from Java code can be used without problem.

Buffer Transfers¶

Java arrays provide efficient buffer transfers for primitive types using Python’s memoryview. This allows seamless integration with libraries like NumPy for numerical operations. For strategies to optimize data exchange, see Optimize Data Transfers.

# Example: Buffer transfer
import numpy as np

int_array = JInt[:](5)
int_array[:] = [1, 2, 3, 4, 5]  # Transfer data to Java array

buffer = memoryview(int_array)
np_array = np.array(buffer)     # Convert to NumPy array

print(np_array)  # Output: [1, 2, 3, 4, 5]

Dispatch Example¶

When JPype is unable to decide which overload of a method to call, the user must resolve the ambiguity. This is where casting comes in. Take for example the java.io.PrintStream class. This class has a variant of the print and println methods! So for the following code:

java.lang.System.out.println(1)

JPype will automatically choose the println(long) method, because the Python int matches exactly with the Java long, while all the other numerical types are only “implicit” matches. However, if that is not the version you wanted to call, you must cast it. In this case, we will use a primitive type to construct the correct type. Changing the line thus:

java.lang.System.out.println(JByte(1))  # <--- wrap the 1 in a JByte

This tells JPype to choose the byte version. When dealing with Java types, JPype follows the standard Java matching rules. Types can implicitly grow to larger types but will not shrink without an explicit cast.

Caching Optimization for Method Resolution¶

JPype optimizes method resolution by caching the results of previous matches. If the same method is called repeatedly with the same argument types (e.g., inside a loop or list comprehension), JPype reuses the cached resolution, avoiding the overhead of re-evaluating all overloads. This greatly improves performance for repetitive calls.

For example, consider the following code:

fruits = ["apple", "orange", "banana"]
jlist = java.util.ArrayList()
[jlist.add(fruit) for fruit in fruits]  # Cached resolution for each iteration

In this case, JPype caches the resolution for add(str) to add(String) method after the first call, and subsequent calls reuse the cached result. This optimization is particularly beneficial in loops and list comprehensions. A call to add(int) would trigger a new resolution. The next call to add(str) will once again trigger a resolution request.

Note: For an in-depth discussion on how this caching mechanism improves loop performance, particularly in list comprehensions, see the Performance section.

Interactions of Custom Converters and Caching¶

It is unwise to define very broad conversions as it can interact poorly with caching. Suppose that one defined a convertion from all Python strings to the Java class for date under some condition. Or perhaps an even broader conversion was defined such as all Python classes that inherit from object.

If such overly broad conversions are applied to a function for which both date and string were acceptable it were prefer the date conversion when method resolution starts. As the type for the cache was string it would attempt the out of order resolution of date first. If the condition yield a fail it will fall back to normal method resolution, but an overly broad conversion specialization may end up being dispatched to the previously defined conversion.

Under normal operation of JPype the type conversions are narrowly defined such that the cache will always yield the proper resolution. But user defined conversions may cause unexpected results. In such a case, a cast operation to the Java type would be required to resolve the ambiguity.

Catching a Specific Java Exception¶

The following example demonstrates catching a specific Java exception:

try:
    # Code that throws a java.lang.RuntimeException
except java.lang.RuntimeException as ex:
    print("Caught the runtime exception:", str(ex))
    print(ex.stacktrace())

Catching Multiple Java Exceptions¶

Multiple Java exceptions can be caught together or separately:

try:
    # Code that may throw various exceptions
except (java.lang.ClassCastException, java.lang.NullPointerException) as ex:
    print("Caught multiple exceptions:", str(ex))
    print(ex.stacktrace())
except java.lang.RuntimeException as ex:
    print("Caught runtime exception:", str(ex))
    print(ex.stacktrace())
except jpype.JException as ex:
    print("Caught base exception:", str(ex))
    print(ex.stacktrace())
except Exception as ex:
    print("Caught Python exception:", str(ex))

Raising Exceptions from Python to Java¶

Exceptions can be raised in proxies to throw an exception back to Java. Exceptions within the JPype core are issued with the most appropriate Python exception type, such as TypeError, ValueError, AttributeError, or OSError.

Raising Exceptions in Proxies¶

JPype allows Python proxies to raise exceptions that are propagated back to Java. This is particularly useful when implementing Java interfaces in Python and handling invalid inputs or unexpected conditions.

When an exception is raised in Python, it is wrapped in a RuntimeException in Java. If the exception propagates back to Python, it is unpacked to return the original Python exception.

import jpype
import jpype.imports

jpype.startJVM()

from java.util.function import Function

@jpype.JImplements(Function)
class MyFunction:
    @jpype.JOverride
    def apply(self, value):
        if value is None:
            raise ValueError("Invalid input: None is not allowed")
        return value.upper()

try:
    func = MyFunction()
    result = func.apply(None)  # This will raise a ValueError
except ValueError as ex:
    print("Caught Python exception:", str(ex))

Exception Aliasing¶

Certain exceptions in Java have a direct correspondence with existing Python exceptions. Rather than forcing JPype to translate these exceptions or requiring the user to handle Java exception types throughout the code, these exceptions are “derived” from their Python counterparts. This allows the user to catch them using standard Python exception types.

try:
    # Code that throws a java.lang.IndexOutOfBoundsException
except IndexError as ex:
    print("Caught IndexError:", str(ex))

Key Requirements¶

Before starting the JVM, ensure the following prerequisites are met:

1. Java Installation: A Java Runtime Environment (JRE) or Java Development Kit (JDK) must be installed. JPype supports Java versions 11 and later.

2. Architecture Match: The architecture of the Python interpreter (e.g., 64-bit or 32-bit) must match the architecture of the installed JVM.

3. Classpath Configuration: Specify the paths to Java classes or JAR files required by your application.

4. Environment Variable: Ensure the JAVA_HOME environment variable is set to the directory containing the Java installation.

How to Start the JVM¶

To start the JVM, use the jpype.startJVM() function. This function initializes the JVM with the specified options. The key arguments are:

• ``classpath``: A list of paths to JAR files or directories containing Java classes.

• ``convertStrings``: A boolean flag controlling whether Java strings are automatically converted to Python strings.

• ``ignoreUnrecognized``: A flag that suppresses errors for unrecognized JVM options.

• Additional JVM options: Any valid JVM arguments (e.g., -Xmx for memory allocation).

import jpype

# Start the JVM with classpath and options
jpype.startJVM(
    classpath=['lib/*', 'classes'],
    jvmOptions=["-ea"]  # Enable assertions
)

Classpath Configuration¶

JPype supports two methods for specifying the classpath:

1. ``classpath`` Argument: Pass a list of paths directly to the startJVM() function. Wildcards (*) are supported for JAR files in a directory.

jpype.startJVM(classpath=['lib/*', 'classes'])

2. ``addClassPath()`` Function: Use jpype.addClassPath() to add paths dynamically before starting the JVM.

jpype.addClassPath('lib/*')
jpype.addClassPath('classes')
jpype.startJVM()

To debug classpath issues, print the effective classpath after starting the JVM:

print(java.lang.System.getProperty('java.class.path'))

Handling JAR Files Compiled for Newer Java Versions¶

If a JAR file is compiled for a newer version of Java than the JVM being used, JPype will fail to load the classes from the JAR file, and the JVM will throw an UnsupportedClassVersionError. This occurs because the JVM cannot interpret class files compiled for a newer version.

java.lang.UnsupportedClassVersionError: <class_name> has been compiled by a
more recent version of the Java Runtime (class file version X), this
version of the Java Runtime only recognizes class file versions up to Y.

Automatic JVM Path Detection¶

JPype automatically detects the path to the JVM shared library using the JAVA_HOME environment variable. If JAVA_HOME is not set, JPype searches common directories based on the platform. You can retrieve the detected path using:

print(jpype.getDefaultJVMPath())

If the automatic detection fails, specify the JVM path manually as the first argument to startJVM():

jpype.startJVM('/path/to/libjvm.so', classpath=['lib/*'])

Handling Non-ASCII Characters in the JVM Path¶

JPype has been revised to handle JVM paths containing non-ASCII characters. Due to restrictions in Java, JPype must make a copy of the JVM shared library when the path includes non-ASCII characters. This ensures compatibility with the Java Virtual Machine.

Windows-Specific Behavior: On Windows, the copied JVM shared library cannot be deleted after use due to file locking restrictions imposed by the operating system. As a result, the temporary file will remain on disk after the JVM is shut down.

Implications:

• The copied JVM shared library will occupy disk space until manually removed.

• This behavior is specific to Windows and does not affect Linux or macOS.

Best Practices:

• Avoid using non-ASCII characters in the JVM path when running JPype on Windows to prevent unnecessary file duplication.

• If non-ASCII characters are unavoidable, ensure sufficient disk space is available for temporary files.

Troubleshooting: To locate the copied JVM shared library, check the directory where the JVM path is specified. The copied file will have the same name as the original shared library but may include additional identifiers.

Example: If the original JVM path is: C:Program FilesJavajdk-11.0.7binserverjvm.dll

And it contains non-ASCII characters, JPype will create a copy in a temporary directory.

This behavior is necessary to ensure compatibility with Java’s handling of non-ASCII paths.

Additional Flags for startJVM()¶

JPype provides several optional flags for startJVM() to customize the JVM startup process:

1. `jvmOptions`: A list of JVM options for memory, debugging, or garbage collection tuning. Example: jpype.startJVM(jvmOptions=["-Xmx512m", "-XX:+UseG1GC"])

2. `ignoreUnrecognized`: Suppresses errors for unrecognized JVM options. Example: jpype.startJVM(ignoreUnrecognized=True)

3. `convertStrings`: Controls automatic conversion of Java strings to Python strings. Example: jpype.startJVM(convertStrings=False)

4. `classpath`: Specifies paths to JAR files and Java classes. Example: jpype.startJVM(classpath=["lib/*", "classes"])

5. `jvmPath`: Specifies the path to the JVM shared library. Example: jpype.startJVM(jvmPath="/path/to/libjvm.so")

6. `attachThread`: Automatically attaches Python threads to the JVM. Example: jpype.startJVM(attachThread=True)

7. `disableGC`: Disables JPype’s garbage collection hooks. Example: jpype.startJVM(disableGC=True)

8. `stackTrace`: Enables detailed stack traces for Java exceptions. Example: jpype.startJVM(stackTrace=True)

9. `initializers`: A list of Python functions executed during JVM startup. Example: jpype.startJVM(initializers=[setup])

10. `modulePath`: Specifies the module path for Java modular applications. Example: jpype.startJVM(modulePath=["modules/*"])

String Conversions¶

The convertStrings argument controls whether Java strings are automatically converted to Python strings. By default, this behavior is disabled (convertStrings=False) to preserve Java string methods and avoid unnecessary conversions.

If enabled (convertStrings=True), Java strings are returned as Python strings, but this can impact performance and chaining of Java string methods. This option is consisted a legacy option as it will result in unncessary calls to str() every time a String is passed from Java.

Best practice: Set convertStrings=False unless your application explicitly requires automatic conversion.

Checking JVM State¶

Use the following functions to check the status of the JVM:

• ``jpype.isJVMStarted()``: Returns True if the JVM is running.

• ``jpype.getJVMVersion()``: Retrieves the version of the running JVM.

Example:

if not jpype.isJVMStarted():
    print("JVM is not running!")
else:
    print("JVM version:", jpype.getJVMVersion())

Common Issues and Troubleshooting¶

1. Classpath Errors: Ensure that all required JAR files and directories are included in the classpath. Use java.lang.System.getProperty('java.class.path') to verify the effective classpath.

2. Architecture Mismatch: Ensure the Python interpreter and JVM have matching architectures (e.g., both 64-bit or both 32-bit). Running a 64-bit Python interpreter with a 32-bit JVM will cause startup failures.

3. Environment Variable Issues: Verify that the JAVA_HOME environment variable is set correctly. If necessary, set it manually: - Windows: set JAVA_HOME=C:\Program Files\Java\jdk-<version> - Linux/Mac: export JAVA_HOME=/usr/lib/jvm/java-<version>

4. Unrecognized JVM Options: If you encounter errors for unrecognized JVM options, use the ignoreUnrecognized=True flag to suppress them.

5. Memory Allocation Errors: Ensure sufficient memory is allocated to the JVM using the -Xmx option.

6. Debugging Startup Failures: Enable stack traces for additional diagnostics:

import _jpype
_jpype.enableStacktraces(True)

Best Practices for JVM starting¶

• Start Early: Start the JVM at the beginning of your program to avoid issues with imports and initialization.

• Specify Classpath Explicitly: Use the classpath argument to ensure all required JAR files and directories are loaded.

• Disable String Conversion: Set convertStrings=False for better control and performance.

• Avoid Restarting the JVM: JPype does not support restarting the JVM after it has been shut down. Design your application to start the JVM once and keep it running for the program’s lifetime.

• Monitor Resource Usage: If your application uses large Java objects, monitor memory usage to avoid out-of-memory errors.

Summary of JVM starting¶

Starting the JVM is a critical step in using JPype to integrate Python with Java. By following the guidelines in this section, you can ensure a smooth startup process, avoid common pitfalls, and configure the JVM to meet your application’s needs. Proper classpath configuration, architecture matching, and memory allocation are key to successful integration. Debugging tools and best practices are available to help troubleshoot issues and optimize performance.

Risks of Shutting Down the JVM¶

Shutting down the JVM manually can lead to serious risks and instability, especially if there are lingering Java references or shared resources. Once the JVM is shut down, all Java objects become invalid, and any attempt to access them will result in errors. This includes:

• Lingering Java References: Any Java objects held by Python will become invalid after the JVM is shut down. Accessing these objects will raise exceptions and could result in undefined behavior.

• Shared Resources: Shared resources such as buffers (e.g., memory mapped from Java to NumPy) will become unstable. Accessing these buffers after the JVM is shut down may cause crashes or memory corruption.

• Proxies and Threads: If Java threads or proxies are active when the JVM is shut down, they will be terminated abruptly, potentially leaving the system in an inconsistent state.

• Non-Daemon Threads: All threads must be attached as daemon threads before shutting down the JVM. Non-daemon threads will block the shutdown process, causing it to hang indefinitely. Python threads that interact with Java are automatically attached as daemon threads by JPype, but any custom threads created in Java must also be marked as daemon.

For most applications, it is safer to allow the JVM to shut down automatically when the Python process exits. This ensures that all resources are cleaned up properly and avoids the risks associated with manual shutdown.

How JPype Shuts Down the JVM¶

JPype performs the following steps during JVM shutdown to ensure proper cleanup:

1. Request JVM Shutdown: JPype requests the JVM to shut down gracefully.

2. Wait for Non-Daemon Threads: The JVM waits for all non-daemon threads to terminate. If you have active Java threads, ensure they are properly terminated or marked as daemon before shutting down the JVM.

3. Execute Shutdown Hooks: The JVM executes any registered shutdown hooks. These hooks can be used to clean up resources before the JVM terminates.

4. Release JPype Reference Queue: JPype shuts down its internal reference queue, which is responsible for dereferencing Python resources tied to Java objects.

5. Release JPype Type Manager: JPype releases its type manager, which handles mappings between Python and Java types.

6. Unload JVM Shared Library: The JVM shared library is unloaded, freeing memory used by the JVM.

7. Finalize Python Resources: JPype cleans up any remaining Python handles tied to Java objects, ensuring that no invalid references remain.

Once the JVM is shut down, all Java objects are considered dead and cannot be reactivated. Any attempt to access their data field will raise an exception.

Managing Threads During JVM Shutdown¶

The JVM requires all threads to be attached as daemon threads during shutdown. Daemon threads are background threads that do not prevent the JVM from terminating. Non-daemon threads, on the other hand, will block the shutdown process, causing it to hang indefinitely until those threads terminate.

JPype automatically attaches Python threads that interact with Java as daemon threads. However, if you create custom threads in Java, you must explicitly mark them as daemon threads to ensure they do not block the JVM shutdown.

To mark a Java thread as a daemon, use the following pattern:

import java.lang.Thread

# Create a Java thread
thread = java.lang.Thread()

# Mark the thread as daemon
thread.setDaemon(True)

# Start the thread
thread.start()

If you need to check whether a thread is a daemon, use the isDaemon() method:

print(f"Thread is daemon: {thread.isDaemon()}")

Ensure that all non-daemon threads are properly terminated or marked as daemon before shutting down the JVM. Failure to do so may cause the shutdown process to hang indefinitely.

How to Shut Down the JVM¶

If you must shut down the JVM manually, you can use the jpype.shutdownJVM() function. This should only be called from the main Python thread. Calling it from any other thread will raise an exception.

import jpype

# Shut down the JVM
jpype.shutdownJVM()

Numerous examples found on the internet explicity state that shutdownJVM is a good practice. These examples are legacy from early development. At the time shutdownJVM brutally closed the JVM and bypassed all for the JVM shutdown routines thus causing the program to skip over errors in the JPype module resulting from mishandled race conditions. While it is still acceptable to shutdown the JVM and may be desirable to do so if a module needs a particular order to shutdown cleanly, the use of an explicit shutdown is discouraged.

Debugging JVM Shutdown¶

If the JVM shutdown process hangs or fails, it is often due to lingering threads or resources that were not properly terminated. Use the following techniques to debug shutdown issues:

1. Check Active Threads: Before shutting down the JVM, check for active non-daemon threads that may be preventing the shutdown. You can use the following Java code to list all active threads:

   import java.lang.Thread
   
   # Get all active threads
   threads = java.lang.Thread.getAllStackTraces().keySet()
   for thread in threads:
       print(f"Thread: {thread.getName()}, Daemon: {thread.isDaemon()}")
   

   Ensure that all non-daemon threads are terminated or marked as daemon before calling jpype.shutdownJVM().

2. Inspect Shutdown Hooks: If you have attached shutdown hooks, verify that they complete quickly and do not hang. Long-running shutdown hooks can delay or block JVM termination.

3. Monitor Resource Usage: If shared resources such as buffers are in use, ensure that they are properly released before shutting down the JVM. For example, copy buffer contents to a Python object to preserve data.

4. Enable Debugging Logs: JPype can provide additional diagnostics during the shutdown process. Use the following command to enable debugging logs:

   import _jpype
   _jpype.enableStacktraces(True)
   

   This will print detailed stack traces for exceptions that occur during the shutdown process.

5. Handle Hanging Threads: If the JVM shutdown hangs due to threads that cannot terminate, you can forcefully terminate the Python process using os._exit() or java.lang.Runtime.exit(). However, note that calling `exit` will bypass normal `atexit` routines in both Python and Java. This means that any cleanup tasks, such as writing logs (e.g., Jacoco coverage reports) or flushing buffers, will not be executed. Use this approach only as a last resort when all other debugging techniques fail.

Best Practices for JVM Shutdown¶

• Avoid Manual Shutdown: Whenever possible, allow the JVM to shut down automatically when the Python process exits. This avoids the risks of lingering references and shared resource instability.

• Terminate Threads Properly: Ensure all non-daemon Java threads are terminated or marked as daemon before shutting down the JVM. Failure to do so may cause the shutdown process to hang indefinitely.

• Handle Buffers Carefully: If you are using shared buffers (e.g., Java direct buffers with NumPy), avoid accessing them after the JVM is shut down. If you need to preserve data, copy the buffer contents to a Python object before shutting down the JVM.

• Use Shutdown Hooks: Attach shutdown hooks only when necessary to clean up resources. Ensure that the hooks complete quickly to avoid delaying JVM termination.

• Avoid Forceful Termination: Avoid using os._exit() or java.lang.Runtime.exit() unless absolutely necessary. These methods prevent normal cleanup routines from executing, which can result in missing logs, incomplete resource cleanup, or other unintended consequences.

Summary of JVM Shutdown¶

JPype’s shutdown process is designed to ensure that resources are cleaned up properly and the JVM terminates gracefully. While shutting down the JVM manually is possible, it introduces risks that can lead to instability and crashes. For most applications, the JVM should be allowed to shut down automatically when the Python process exits. If manual shutdown is required, take precautions to ensure that all Java references and shared resources are properly cleaned up before shutting down the JVM. Avoid forceful termination unless absolutely necessary, as it bypasses critical cleanup routines in both Python and Java.

Example: Customizing java.util.Map¶

The following example demonstrates how to customize the java.util.Map class to behave like a Python dictionary:

@_jcustomizer.JImplementationFor('java.util.Map')
class _JMap:
    def __jclass_init__(self):
        Mapping.register(self)

    def __len__(self):
        return self.size()

    def __iter__(self):
        return self.keySet().iterator()

    def __delitem__(self, i):
        return self.remove(i)

The name of the class does not matter for the purposes of the customizer, though it should be a private class so that it does not get used accidentally. The customizer code will steal from the prototype class rather than acting as a base class, ensuring that the methods will appear on the most derived Python class and are not hidden by the Java implementations.

The customizer copies methods, callable objects, __new__, class member strings, and properties.

Example: Converting Python Sequences to Java Collections¶

The following example demonstrates how to convert Python sequences into Java collections:

@JConversion("java.util.Collection", instanceof=Sequence,
                          excludes=str)
def _JSequenceConvert(jcls, obj):
    return _jclass.JClass('java.util.Arrays').asList(obj)

JPype supplies customizers for certain Python classes by default. These include:

Overview of JPype Beans¶

The jpype.beans module is an optional feature that converts Java Bean-style getter and setter methods into Python properties. This customization is particularly useful for interactive programming or when working with Java classes that follow the Bean pattern.

However, this behavior is not enabled by default because it can lead to confusion about whether a class is exposing a variable or a property added by JPype. Additionally, it violates Python’s principle of “There should be one– and preferably only one –obvious way to do it.” and the C++ principle of “You only pay for what you use.”

If you find this feature useful, you can enable it explicitly by importing the jpype.beans module.

Enabling Beans as Properties¶

To enable the jpype.beans module, simply import it into your Python program:

import jpype.beans

Once enabled, the module applies globally to all Java classes that have already been loaded, as well as any classes loaded afterward. This behavior cannot be undone after the module is imported.

How It JPype beans Works¶

The jpype.beans module scans Java classes for methods that follow the Bean naming conventions:

• Getter methods: Methods prefixed with get (e.g., getName) are treated as property accessors.

• Setter methods: Methods prefixed with set (e.g., setName) are treated as property mutators.

For example, a Java class with the following methods:

public class Person {
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

Will automatically expose the name field as a Python property:

import jpype
import jpype.beans

jpype.startJVM()

Person = jpype.JClass("Person")
person = Person()
person.name = "Alice"  # Calls setName("Alice")
print(person.name)     # Calls getName(), Output: Alice

Implementation Details of JPype beans¶

The module works by:

1. Identifying getter and setter methods in Java classes using the _isBeanAccessor() and _isBeanMutator() methods.

2. Creating Python properties for these methods.

3. Adding the properties to the class dynamically.

The customization applies retroactively to all classes currently loaded and globally to all future classes.

Limitations of JPype beans¶

1. Global Behavior: Once enabled, the customization applies to all Java classes globally. It cannot be undone.

2. Confusion with Existing Members: If a Java class already has a Python member with the same name as a property, the property will not be added to avoid conflicts.

3. Ambiguity: This feature can make it unclear whether a field is a true Java variable or a property added by JPype.

Best Practices for JPype beans¶

• Use this module only when working with Java classes that heavily rely on the Bean pattern.

• Avoid enabling this module in large projects unless absolutely necessary, as the global behavior may lead to unintended consequences.

• Document its usage clearly in your codebase to avoid confusion for other developers.

Summary of JPype beans¶

The jpype.beans module provides a convenient way to work with Java Bean-style classes in Python by exposing getter and setter methods as Python properties. While useful in certain scenarios, it is an optional feature that must be explicitly enabled and should be used with caution due to its global and irreversible behavior.

Overview of conflict resolution¶

When working with Java classes in Python, conflicts can arise between public fields and methods that share the same name. JPype provides tools to resolve these conflicts using customizers, allowing you to rename fields or methods dynamically and expose them in a Pythonic way.

This section demonstrates how to use a customizer to resolve such conflicts by renaming fields or methods and exposing them as Python properties.

Example: Renaming Conflicting Fields and Methods¶

Consider a Java class with a field and a method that share the same name. Without customization, JPype will expose the method, and the field will be hidden. To resolve this, you can use a customizer to rename the conflicting field or method and expose it as a Python property.

Here’s an example:

def asProperty(field):
    def get(E):
        return field.get(E)
    def set(E, V):
        field.set(E, V)
    return property(get, set)

@jpype.JImplementationFor("java.lang.Object")  # Use your base class.
class MyCustomizer(object):

    # This is applied to every class that derives from the type
    def __jclass_init__(cls):
        # Traverse the fields
        for field in cls.class_.getDeclaredFields():
            name = str(field.getName())
            tp = type(cls.__dict__.get(str(field.getName()), None))

            # Watch for private methods
            if tp is type(None):
                continue

            # Resolve conflicts between public fields and methods
            if tp is jpype.JMethod:
                cls._customize("%s_" % name, asProperty(field))

How It Conflict Resolution Works¶

1. Field Traversal: The customizer iterates over all declared fields in the class using getDeclaredFields().

2. Conflict Detection: For each field, it checks whether a public method with the same name exists.

3. Renaming: If a conflict is detected, the field is renamed by appending an underscore (_) to its name.

4. Property Creation: The renamed field is exposed as a Python property using the property() function.

Example Usage of Conflict Resolution¶

Suppose you have a Java class A with a field mean and a method mean. Without customization, the field would be inaccessible. Using the customizer above, you can expose the field as mean_:

A = jpype.JClass("A")
a = A()
print(a.mean_)  # Access the renamed field
a.mean_ = 2      # Modify the field
print(a.mean_)   # Verify the updated value

Notes on Global Customizers¶

• The customizer is applied globally to all classes that derive from the specified base class (java.lang.Object in this example). You can replace the base class with a more specific class to limit the scope of the customization.

• This approach is particularly useful for resolving conflicts in large Java libraries or frameworks where method and field names overlap frequently.

Best Practices Regarding Name Resolution Customizers¶

• Use meaningful naming conventions when renaming fields or methods to avoid confusion.

• Document customizations clearly in your codebase to help other developers understand the changes.

• Test the customizer thoroughly to ensure it behaves as expected across all relevant classes.

Summary of Naming Conflict Resolution¶

This example demonstrates how to use JPype customizers to resolve conflicts between fields and methods in Java classes. By renaming conflicting fields or methods and exposing them as Python properties, you can create a more Pythonic interface for interacting with Java classes.

Iterable¶

Java classes that implement java.util.Iterable are customized to support Python’s iteration constructs. This allows seamless use in Python for loops and list comprehensions. For example, a Java ArrayList can be iterated directly:

from java.util import ArrayList

jlist = ArrayList()
jlist.add("apple")
jlist.add("orange")
jlist.add("banana")

for item in jlist:
    print(item)

This integration ensures that Java collections behave like Python sequences, providing a natural experience for Python developers.

Iterators¶

Java classes that implement java.util.Iterator act as Python iterators. This means they can be used in Python for loops and list comprehensions without requiring additional conversion. For example:

from java.util import Vector

jvector = Vector()
jvector.add("apple")
jvector.add("orange")

iterator = jvector.iterator()
for item in iterator:
    print(item)

Collection¶

Java classes that inherit from java.util.Collection integrate seamlessly with Python’s collection constructs. They support operations such as length retrieval, iteration, and implicit conversion of Python sequences into Java collections. For example:

from java.util import ArrayList

pylist = ["apple", "orange", "banana"]
jlist = ArrayList(pylist)  # Convert Python list to Java collection

print(len(jlist))  # Output: 3
for item in jlist:
    print(item)

Methods that accept Java collections can automatically convert Python sequences if all elements are compatible with Java types. Otherwise, a TypeError is raised.

Lists¶

Java List classes, such as ArrayList and LinkedList, can be used in Python for loops and list comprehensions. They also support indexing and deletion, making them behave like Python lists. For example:

from java.util import ArrayList

jlist = ArrayList()
jlist.add("apple")
jlist.add("orange")
jlist.add("banana")

print(jlist[0])  # Output: apple
del jlist[1]     # Remove "orange"
print(jlist)     # Output: [apple, banana]

Java lists can also be converted to Python lists and vice versa using the copy constructor. For example:

pylist = ["apple", "orange", "banana"]
jlist = ArrayList(pylist)  # Convert Python list to Java list
pylist2 = list(jlist)      # Convert Java list back to Python list

Note that individual elements remain Java objects when converted to Python. Converting to Java will attempt to convert each argument individually to Java. If there is no conversion it will produce a TypeError. The conversion can be forced by casting to the appropriate Java type with a list comprehension or by defining a new conversion customizer.

Lists also have iterable, length, item deletion, and indexing. Note that indexing of java.util.LinkedList is supported but can have a large performance penalty for large lists. Use of iteration is much for efficient.

Maps¶

Java classes that implement java.util.Map behave like Python dictionaries. They support key-value access, iteration, and deletion. Here is a summary of their capabilities:

Example using Java HashMap with Pythonic interface:

from java.util import HashMap

jmap = HashMap()
jmap.put("key1", "value1")
jmap.put("key2", "value2")

print(jmap["key1"])  # Output: value1
del jmap["key2"]     # Remove "key2"
print(len(jmap))     # Output: 1

Maps also support iteration over keys and values:

for key, value in jmap.items():
    print(f"{key}: {value}")

Methods that accept Java maps can implicitly convert Python dictionaries if all keys and values are compatible with Java types. Otherwise, a TypeError is raised.

Map Entries¶

Java map entries unpack into key-value pairs, allowing easy iteration in Python loops. For example:

for key, value in jmap.items():
    print(f"{key}: {value}")

Sets¶

Java classes that implement java.util.Set behave like Python sets. They support operations such as item deletion, iteration, and length retrieval. For example:

from java.util import HashSet

jset = HashSet()
jset.add("apple")
jset.add("orange")

print(len(jset))  # Output: 2
jset.remove("orange")
print(jset)       # Output: [apple]

Enumeration¶

Java classes that implement java.util.Enumeration act as Python iterators. This allows them to be used in Python for loops and list comprehensions. For example:

from java.util import Vector

jvector = Vector()
jvector.add("apple")
jvector.add("orange")

enumeration = jvector.elements()
for item in enumeration:
    print(item)

Using Pythonic Constructs with Java Collections¶

JPype enables Python developers to interact with Java collections while leveraging Python’s idiomatic constructs, such as list comprehensions and generator expressions. For example:

from java.util import ArrayList

jlist = ArrayList()
jlist.add("apple")
jlist.add("orange")
jlist.add("banana")

filtered = [item.upper() for item in jlist if item.startswith("a")]
print(filtered)  # Output: ['APPLE']

Combining Pythonic constructs with Java methods allows developers to use the best tools for the task, whether they prefer Python’s simplicity or Java’s robustness.

Using Java Streams for Functional Operations¶

Java’s Stream API provides powerful functional programming constructs, such as filter, map, and reduce. JPype allows Python developers to use these methods with Java collections, enabling them to leverage Java’s robust libraries.

from java.util.stream import Collectors

# Use Java Stream API for filtering and mapping
filtered = jlist.stream().filter(lambda s: s.startswith("a")).map(
    lambda s: s.upper()).collect(Collectors.toList())
print(filtered)  # Output: [APPLE]

Comparison: Pythonic Constructs vs Java Methods¶

Combining Pythonic Constructs and Java Methods¶

JPype allows developers to mix Pythonic constructs and Java methods for maximum flexibility. For example, you can use Java streams for complex operations and Pythonic constructs for post-processing.

# Use Java Stream API for filtering
filtered_stream = jlist.stream().filter(lambda s: s.startswith("a")).collect(
    Collectors.toList())

# Use Pythonic list comprehension for further processing
final_result = [item.lower() for item in filtered_stream]
print(final_result)  # Output: ['apple']

When to Use Each Approach¶

Best Practices for Collection Processing¶

1. Choose the Right Tool for the Job: - Use Pythonic constructs for simplicity and readability. - Use Java streams for performance-critical or enterprise applications.

2. Leverage JPype’s Seamlessness: - Combine Pythonic constructs and Java methods to get the best of both worlds.

3. Optimize for Performance: - Avoid frequent back-and-forth calls between Python and Java. Cache results when possible.

Conclusion on Collection Processing¶

JPype enables Python developers to work with Java collections using both Pythonic constructs and Java methods. Whether you prefer Python’s simplicity or Java’s robustness, JPype provides the flexibility to choose the paradigm that best fits your workflow.

How JPickler Works¶

JPickler uses Java’s Serializable interface to serialize Java objects into a byte stream that can be stored or transferred. It also provides a companion utility, JUnpickler, for deserializing these byte streams back into Java objects.

import jpype
import jpype.imports
from jpype.pickle import JPickler, JUnpickler

# Start the JVM
jpype.startJVM()

# Create a Java object
java_list = jpype.java.util.ArrayList()
java_list.add("Hello")
java_list.add("World")

# Serialize the Java object to a file
with open("serialized_java_list.pkl", "wb") as f:
    JPickler(f).dump(java_list)

print("Java object serialized successfully!")

# Deserialize the Java object from the file
with open("serialized_java_list.pkl", "rb") as f:
    deserialized_list = JUnpickler(f).load()

print("Deserialized Java object:", deserialized_list)
# Output: [Hello, World]

// Save this as MySerializableClass.java and compile it
import java.io.Serializable;

public class MySerializableClass implements Serializable {
    private String name;
    private int value;

    public MySerializableClass(String name, int value) {
        this.name = name;
        this.value = value;
    }

    @Override
    public String toString() {
        return "MySerializableClass{name='" + name + "', value=" + value + "}";
    }
}

import jpype
import jpype.imports
from jpype.pickle import JPickler, JUnpickler

# Start the JVM
jpype.startJVM(classpath=["."])

# Create an instance of the custom Java class
MySerializableClass = jpype.JClass("MySerializableClass")
java_object = MySerializableClass("TestObject", 42)

# Serialize the Java object to a file
with open("serialized_java_object.pkl", "wb") as f:
    JPickler(f).dump(java_object)

print("Custom Java object serialized successfully!")

# Deserialize the Java object from the file
with open("serialized_java_object.pkl", "rb") as f:
    deserialized_object = JUnpickler(f).load()

print("Deserialized Java object:", deserialized_object)
# Output: MySerializableClass{name='TestObject', value=42}

Transferring Arrays to NumPy¶

Java arrays can be transferred into NumPy arrays using Python’s memoryview. This enables efficient bulk data transfer for rectangular arrays.

Example: Transferring a Java Array to NumPy

import jpype
import numpy as np

# Start the JVM
jpype.startJVM()

# Create a Java array
java_array = jpype.JDouble[:]([1.1, 2.2, 3.3])

# Transfer the Java array to NumPy
numpy_array = np.array(memoryview(java_array))

print(numpy_array)  # Output: [1.1 2.2 3.3]

Constraints: - The Java array must be rectangular. Jagged arrays are not supported. - Only primitive types (e.g., double, int) are supported for direct transfer.

Transferring Arrays to Java¶

NumPy arrays can be transferred to Java using the JArray.of function. This maps the structure of a NumPy array to a Java multidimensional array.

Example: Transferring a NumPy Array to Java

import jpype
import numpy as np

# Start the JVM
jpype.startJVM()

# Create a NumPy array
numpy_array = np.zeros((5, 10, 20))  # 5x10x20 array filled with zeros

# Transfer the array to Java
java_array = jpype.JArray.of(numpy_array)

print(java_array[0][0][0])  # Output: 0.0

Constraints: - The NumPy array must be rectangular. Jagged arrays are not supported. - Data types must be compatible with Java primitives (e.g., np.float64 → double).

Requirements and Constraints¶

1. Rectangular Arrays:

   • Both NumPy and Java arrays must be rectangular for direct transfer.

2. Data Type Compatibility:

   • NumPy types must map to Java primitives (e.g., np.int32 → int).

3. Error Handling:

   • Jagged arrays or incompatible types will raise a TypeError.

Best Practices with NumPy¶

1. Validate Array Structure: - Ensure arrays are rectangular before transferring.

2. Optimize Data Types: - Use NumPy types that map directly to Java primitives for efficiency.

3. Monitor Memory Usage: - Large arrays can consume significant memory. Monitor resources carefully.

Summary of NumPy¶

JPype provides efficient bidirectional array transfers between Python and Java. By following the outlined constraints and best practices, users can achieve seamless integration for numerical and scientific applications.

Creating Buffer Backed Arrays¶

To create a buffer-backed NumPy array, you can either originate the buffer in Java or Python. The following examples demonstrate both approaches:

Example 1: Creating a Buffer in Java

import jpype
import numpy as np

# Start the JVM
jpype.startJVM()

# Allocate a direct buffer in Java
jb = java.nio.ByteBuffer.allocateDirect(80)  # Allocates 80 bytes
db = jb.asDoubleBuffer()                     # Converts to a double buffer

# Convert the buffer to a NumPy array
np_array = np.asarray(db)                    # NumPy array backed by Java buffer
print(np_array)

Example 2: Creating a Buffer in Python

import jpype
import numpy as np

# Start the JVM
jpype.startJVM()

# Create a Python bytearray
py_buffer = bytearray(80)                    # Allocates 80 bytes
jb = jpype.nio.convertToDirectBuffer(py_buffer)  # Maps the bytearray to Java
db = jb.asDoubleBuffer()                     # Converts to a double buffer

# Convert the buffer to a NumPy array
np_array = np.asarray(db)                    # NumPy array backed by Python buffer
print(np_array)

Important Considerations for Buffer Backed Arrays¶

1. Buffer Lifetime:

   • Python and NumPy cannot detect when a Java buffer becomes invalid. Once the JVM is shut down, all buffers originating from Java become invalid, and any access to them may result in crashes.

   • To avoid this, create buffers in Python and pass them to Java, ensuring Python retains control over the memory.

2. JVM Shutdown:

   • If buffers are created in Java, consider using java.lang.Runtime.exit to terminate both the Java and Python processes simultaneously. This prevents accidental access to dangling buffers.

3. Applications:

   • Buffer-backed memory is not limited to NumPy. It can be used for shared memory between processes, memory-mapped files, or any application requiring efficient data exchange.

Summary of Buffer Backed Arrays¶

Buffer-backed NumPy arrays provide a powerful mechanism for high-speed data exchange between Python and Java. However, users must carefully manage buffer lifetimes and ensure proper handling during JVM shutdown to avoid crashes or memory leaks.

Both Python and Java have a notion of readonly memory (bytes vs bytearray in Python). ConvertToDirectBuffer will honor the the writability of the passed object and return a readonly Java ByteBuffer if the source object is readonly.

Supported NumPy Types¶

The following table summarizes how NumPy types are mapped to Java boxed types and primitive arrays:

(*) np.float16 will be automatically converted to float32 (java.lang.Float or float[]) during the transfer to Java.

Examples¶

The following examples demonstrate how to transfer np.float16 data to Java as boxed types or primitive arrays.

import jpype
import numpy as np

# Start the JVM
jpype.startJVM()

# Create a NumPy array with float16 data
float16_array = np.array([1.1, 2.2, 3.3], dtype=np.float16)

# Transfer the array to a Java boxed type (java.util.ArrayList)
java_list = jpype.java.util.ArrayList()
for value in float16_array:
    java_list.add(jpype.JFloat(value))  # Automatically converted to float32

print(java_list)  # Output: [1.1, 2.2, 3.3] (as float32)

import jpype
import numpy as np

# Start the JVM
jpype.startJVM()

# Create a NumPy array with float16 data
float16_array = np.array([1.1, 2.2, 3.3], dtype=np.float16)

# Transfer the array to a Java primitive array
java_primitive_array = jpype.JArray(jpype.JFloat)(float16_array)  # Converted
                                                                  # to float32[]

print(java_primitive_array)  # Output: [1.1, 2.2, 3.3] (as float32[])

Summary of NumPy Automatic Conversions¶

JPype supports transferring NumPy arrays to Java, with automatic conversions for certain types. While np.float16 can be transferred, it is converted to float32 on the Java side for compatibility. Users should be aware of this behavior and plan accordingly when working with float16 data.

Proxy Method Overloading¶

Overloaded methods will issue to a single method with the matching name. If they take different numbers of arguments then it is best to implement a method dispatch:

@JImplements(JavaInterface)
class MyImpl:
    @JOverride
    def callOverloaded(self, *args):
        # always use the wild card args when implementing a dispatch
        if len(args)==2:
            return self.callMethod1(*args)
        if len(args)==1 and isinstance(args[0], JString):
            return self.callMethod2(*args)
        raise RuntimeError("Incorrect arguments")

   def callMethod1(self, a1, a2):
        # ...
   def callMethod2(self, jstr):
        # ...

Multiple interfaces¶

Proxies can implement multiple interfaces as long as none of those interfaces have conflicting methods. To implement more than one interface, use a list as the argument to the JImplements decorator. Each interface must be implemented completely.

Deferred realization¶

Sometimes it is useful to implement proxies before the JVM is started. To achieve this, specify the interface using a string and add the keyword argument deferred with a value of True to the decorator.

@JImplements("org.foo.JavaInterface", deferred=True)
class MyImpl:
    # ...

Deferred proxies are not checked at declaration time, but instead at the time for the first usage. Because of this, when uses an deferred proxy the code must be able to handle initialization errors wherever the proxy is created.

Other than the raising of exceptions on creation, there is no penalty to deferring a proxy class. The implementation is checked once on the first usage and cached for the remaining life of the class.

JProxy¶

The JProxy allows Python code to “implement” any number of Java interfaces, so as to receive callbacks through them. The JProxy factory has the signature:

JProxy(int, [dict=obj | inst=obj] [, deferred=False])

The first argument is the interface to be implemented. This may be either a string with the name of the interface, a Java class, or a Java class instance. If multiple interfaces are to be implemented the first argument is replaced by a Python sequence. The next argument is a keyword argument specifying the object to receive methods. This can either be a dictionary dict which names the methods as keys or an object instance inst which will receive method calls. If more than one option is selected, a TypeError is raised. When Java calls the proxy the method is looked up in either the dictionary or the instance and the resulting method is called. Any exceptions generated in the proxy will be wrapped as a RuntimeException in Java. If that exception reaches back to Python it is unpacked to return the original Python exception.

Assume a Java interface like:

public interface ITestInterface2
{
        int testMethod();
        String testMethod2();
}

You can create a proxy implementing this interface in two ways. First, with an object:

class C:
    def testMethod(self):
        return 42

    def testMethod2(self):
        return "Bar"

c = C()  # create an instance
proxy = JProxy("ITestInterface2", inst=c)  # Convert it into a proxy

or you can use a dictionary.

def _testMethod():
    return 32

def _testMethod2():
    return "Fooo!"

d = { 'testMethod': _testMethod, 'testMethod2': _testMethod2, }
proxy = JProxy("ITestInterface2", dict=d)

Syntax¶

The JProxy factory supports both dict and inst as keyword arguments. When both are provided:

• Methods in the dictionary take precedence.

• The inst object is passed as the self argument to methods defined in the dictionary.

• If a method is not found in the dictionary, JPype will fall back to the default method implementation in Java.

JProxy(interface, dict=my_dict, inst=my_instance)

Example: Combining dict and inst Suppose you have a Java interface:

public interface MyInterface {
    String method1();
    String method2();
}

You can implement this interface using both a dictionary and an object instance:

public interface MyInterface {
    String method1();
    default String method2() {
        return "hello";
    }
}
You can implement this interface using both a dictionary and an object instance:

.. code-block:: python

from jpype import JProxy

class MyClass:
    def __init__(self, name):
        self.name = name

# Define a dictionary with methods
my_dict = {
    "method1": lambda self: f"Hello, {self.name} from method1"
}

# Create an instance of the class
my_instance = MyClass("Alice")

# Combine the dictionary and instance in a JProxy
proxy = JProxy("MyInterface", dict=my_dict, inst=my_instance)

# Use the proxy in Java
print(proxy.method1())  # Output: Hello, Alice from method1
print(proxy.method2())  # Falls back to Java's default method implementation

Notes and Best Practices¶

Method Resolution:

• Methods in the dictionary take precedence over methods in the instance.

• If a method is not found in the dictionary, JPype will attempt to resolve it in the instance.

Error Handling:

• If neither the dictionary nor the instance provides the required method, a NotImplementedError will be raised.

Flexibility:

This approach allows dynamic addition or overriding of methods via the dictionary while retaining the benefits of object-oriented programming with the instance.

Example: Dynamic Overrides You can dynamically override methods in the instance using the dictionary:

class MyClass:
    def __init__(self, name):
        self.name = name

# Define a dictionary to override methods
my_dict = {
    "method1": lambda self: f"Overridden method1 for {self.name}"
}

my_instance = MyClass("Bob")

proxy = JProxy("MyInterface", dict=my_dict, inst=my_instance)

print(proxy.method1())  # Output: Overridden method1 for Bob
print(proxy.method2())  # Falls back to Java's default method implementation