Add a Java bindings generator on top of the C bindings

[Fedr]

A Java backend, generated on top of the C bindings the same way the Rust one (#54) is. Stacked on #54, since it reads the C signatures and the std::function callback types that PR added to the description JSON; rebased on its current head.

What's generated

mrbind_gen_java --input-json c_desc.json --output-dir src --package com.example.mylib --imported-lib-name MyLib [--force-namespace MyLib] emits plain Java sources calling the C library through the foreign function API (java.lang.foreign, Java 22+), so there's no JNI glue and no dependencies:

• <package>.ffi mirrors the C file hierarchy: one class per C file holding the downcall MethodHandle of every function (in nested classes of 200 handles each, to keep the static initializers under the bytecode limit). A function the library lacks gets a handle that throws UnsatisfiedLinkError when called, so the rest of its class stays usable.
• The C++ namespaces become packages (MR::Foo → mr.foo), classes become classes, free functions become static methods of a Functions class per package. Opaque classes are CppObject wrappers that own their C++ object when created in Java (destroyed by a Cleaner or close()), and when returned by reference keep alive what the reference points into: the objects named by the [[clang::lifetimebound]] annotations, or this / the only object parameter without them. --expose-as-struct classes are CppStruct views over native memory with the C++ layout, built at runtime with the C alignment rules and checked against the sizes in the JSON. Enums are newtype classes with constants. Parameters take wrappers (nullable for pointers and default arguments), std::string-like ones take String, scalars by const pointer take primitives. C++ exceptions become CppException. Anything the safe layer doesn't understand still gets a wrapper with raw MemorySegments and primitives, so the whole API is reachable.
• Every class with bases gets upcastTo<Base>(), plus staticDowncastFrom<Base>() for the non-virtual bases and dynamicDowncastFrom<Base>() (null on failure) for the polymorphic ones, calling the cast functions of the C bindings (derived from inheritance_info with the same rules as the C generator).
• The std_function_... wrappers get of(lambda) and assignFn(lambda), built on ConstructEx/AssignEx through upcall stubs. The lambda implements a nested Fn interface with the natural Java types (scalars, enums, exposed structs by value, classes by reference, classes returned by value as owned wrappers); the copies of the std::function share it through the user data callback; an exception it throws is rethrown by the wrapper that called into C once the call returns.
• Unlike Rust, Java has overloading, so overloads keep their C++ names when their Java parameter types differ, and only clashing ones get the disambiguated C names. Operators are opAdd, opEqual, opNotEqual, opAddAssign, ... Constructors are real Java constructors when unambiguous.
• On Windows the library is loaded with LoadLibraryExW(LOAD_WITH_ALTERED_SEARCH_PATH), so its dependencies are found next to it, and the Windows error code is reported when that fails.

See docs/generating_java.md for the details and the known limitations. examples/java has the same structure as examples/rust.

Testing

test/make_java.sh generates the three test outputs, compiles them with -Xlint:all -Werror, and runs test/run_java/Main.java, which exercises opaque classes with string fields, copy constructors, std::vector<int>, enum default arguments, an exposed struct with arrays, a C++ exception turning into a CppException, std::function from lambdas (shared by copies, class passed and returned by value, a lambda exception rethrown by the caller), and the casts. On the full test suite the generator wraps all 4668 functions, 433 of them with raw types, 0 skipped. Verified on Windows (MSYS2 clang64 for the C library, Temurin JDK 25), and examples/java/run.sh runs there too.

On the full MeshLib API (37764 functions, 3157 classes) the generated sources compile in ~20 s with zero warnings; MeshInspector/MeshLib#7115 builds and runs them in CI on Ubuntu, Windows and macOS, x64 and arm64, with all 92 ported tests plus the callback and cast tests passing.

The committed test/output_java* sources are generated on Linux like the C and Rust ones.

🤖 Generated with Claude Code

[adalisk-emikhaylov]

Don't add those comments to generated code: /** The downcall handles of the C bindings file MR/test_abstract_classes. Generated by mrbind, do not edit. */.