openrocket-jpype-interop

name	openrocket-jpype-interop
description	Work with the OpenRocket Java library through JPype — start/stop the JVM, load .ork documents, traverse the rocket component tree, and read data from both the XML (BeautifulSoup) and the live Java object. Use when touching openrocket_runtime.py, open_rocket_wrangler.py, ork_extractor.py, the JVM/Java setup, or anything that calls into net.sf.openrocket / info.openrocket.

OpenRocket ↔ JPype interop

The two-source model

ork_extractor(bs, filepath, output_folder, ork) reads from two sources simultaneously — always know which one a given value comes from:

• bs — a BeautifulSoup tree of the .ork XML (_helpers.parse_ork_file). Source of the simulation datapoints and most numeric parameters. Access via bs.find(...), bs.find_all("datapoint"), and bs.find("databranch").attrs["types"] (the comma-joined column labels).
• ork — the live Java OpenRocket document (OpenRocketSession.load_doc). Source of geometry and component positions that the XML doesn't expose cleanly. Reached via ork.getRocket() and traversed in components/open_rocket_wrangler.py.

When adding an extractor, prefer bs for scalar/sim data and only reach into ork when the value requires walking the component hierarchy.

The JVM lifecycle (read before changing session code)

JPype is pinned jpype1<1.5, which cannot restart a JVM in one process. Consequences:

• OpenRocketSession.__exit__ must not call jpype.shutdownJVM(). It only disposes AWT windows. The JVM is cleaned up by JPype's atexit hook.
• Never open a second OpenRocketSession in a test. tests/conftest.py opens one session at import time and caches every example's settings in _cached_settings.
• To use the session: with OpenRocketSession(jar_path, log_level="OFF") as s: doc = s.load_doc(path).

Package namespaces

OpenRocket moved from net.sf.openrocket (legacy, ≤ ~22) to info.openrocket (modern). OpenRocketSession._resolve_packages() tries legacy first, then modern, returning (core, swing). If you support a new jar and a symbol is missing, extend that method rather than hard-coding a namespace anywhere else.

Java version compatibility

ensure_java_compatibility(jar_path) picks the minimum Java: OpenRocket 23+ → Java 17, else Java 8. On Windows it auto-discovers a JDK under C:/Program Files/Java (and Adoptium / AdoptOpenJDK) and sets JAVA_HOME/PATH. On other OSes it only warns — the user must provide a compatible JVM. Jar version is parsed from the filename by _jar_version_tuple.

Traversing the component tree

open_rocket_wrangler.py helpers: is_sub_component(ork) (depth > 1 from root), parent_is_a_stage(ork) (parent class is Stage/AxialStage), and process_elements_position(...) which builds the position map used by fins, nose cone, transitions, and rail buttons. Component Java classes are identified by ork.getClass().getSimpleName().

Gotchas

• Java calls raise jpype.JException (plus AttributeError/TypeError/RuntimeError when internals change between versions). Catch these narrowly — see _block_loader.
• The .ork file is a zip containing rocket.ork (XML). extract_ork_from_zip handles both the zipped and already-extracted cases (it catches BadZipFile).