PemJa

Common errors

• pemja.JavaException: java.lang.NoClassDefFoundError: Your/Custom/Class

  cause The specified Java class or one of its dependencies could not be found by the JVM. This usually means the JAR containing the class was not added to the JVM's classpath.
  fix Ensure that the JAR file containing 'Your/Custom/Class' (and any of its dependencies) is correctly specified in the `classpath` argument when calling `pemja.launch_jvm()`. Use `pemja.find_jar()` to help locate JARs if they are in standard locations.

• FileNotFoundError: Cannot find JDK home directory. Please ensure JAVA_HOME is set or java is in PATH.

  cause PemJa could not locate a Java Development Kit (JDK) installation on your system, which is required to launch the JVM.
  fix Install JDK 8 or higher on your system. Then, either add the JDK's `bin` directory to your system's PATH environment variable, or set the `JAVA_HOME` environment variable to point to your JDK installation directory (e.g., `/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home` on macOS).

• pemja.PemjaException: JVM already launched. Can't launch it again.

  cause You are attempting to call `pemja.launch_jvm()` more than once within the same Python process.
  fix Ensure `pemja.launch_jvm()` is called only once. Store the returned `jvm` object and reuse it throughout your application. If you need to reconfigure the JVM, you must restart your Python process.

Warnings

• breaking The parameters for `pemja.launch_jvm()` changed significantly in version 0.6.0. The `config` dictionary was replaced with more explicit parameters like `options` and `classpath`.
  Fix: Review the PemJa documentation for `launch_jvm` (e.g., on GitHub) and update your calls to use the new explicit parameters. For general JVM arguments, use the `options` list (e.g., `options=['-Xmx512m']`).
• gotcha PemJa requires a Java Development Kit (JDK) version 8 or higher to be installed on the system where Python is running. Without a properly configured JDK, PemJa cannot launch the JVM.
  Fix: Install JDK 8+ and ensure its `bin` directory is in your system's PATH environment variable, or set the `JAVA_HOME` environment variable to point to your JDK installation directory.
• gotcha The JVM should generally be launched only once per Python process using `pemja.launch_jvm()`. Attempting to launch it multiple times can lead to errors or undefined behavior.
  Fix: Call `pemja.launch_jvm()` once at the beginning of your application. Store the returned `jvm` object and reuse it throughout your application. Use a context manager (`with pemja.launch_jvm() as jvm:`) for safe shutdown.
• gotcha When working with custom Java JARs, ensuring they are correctly added to the JVM's classpath is critical. Incorrect classpath configuration leads to `NoClassDefFoundError` or similar issues.
  Fix: Use `pemja.find_jar()` to locate JARs and pass the result to the `classpath` argument of `pemja.launch_jvm()`. For multiple JARs, `classpath` accepts a list of paths.

Install

• pip install pemja Install PemJa

Imports

• launch_jvm

  from pemja import launch_jvm

• find_jar

  from pemja import find_jar

• JavaObject

  from pemja import JavaObject

  Used for type hinting Java objects returned by PemJa.

Quickstart

This quickstart demonstrates launching a JVM, accessing static Java methods, creating Java object instances, calling instance methods, and basic Java exception handling. It's crucial to have JDK 8+ installed on your system for PemJa to function.

import pemja

# Ensure JDK 8+ is installed and accessible in your system's PATH or JAVA_HOME.
# In a production environment, consider explicit JVM options or classpath management.

try:
    print("Launching JVM...")
    # Using a context manager ensures the JVM is shut down cleanly
    with pemja.launch_jvm() as jvm:
        print("JVM launched successfully.")

        # 1. Access a static method from a core Java class
        System = jvm.find_class("java.lang.System")
        java_version = System.getProperty("java.version")
        print(f"Java version reported by JVM: {java_version}")

        # 2. Create an instance of a Java class and call a method
        String = jvm.find_class("java.lang.String")
        greeting = jvm.create_instance(String, "Hello from PemJa in Python!")
        print(f"Original Java string: {greeting}")
        print(f"Uppercase Java string: {greeting.toUpperCase()}")

        # 3. Handle exceptions from Java
        # This is a simple example; real error handling would be more robust
        try:
            Integer = jvm.find_class("java.lang.Integer")
            Integer.parseInt("not_a_number") # This will throw a Java NumberFormatException
        except jvm.JavaException as e:
            print(f"Caught Java Exception: {e.get_stack_trace()}")

except pemja.PemjaException as e:
    print(f"PemJa specific error: {e}")
    print("Please ensure JDK 8+ is correctly installed and configured.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")