JRE bundling prototype - complete and working

- Docker-based JRE build with jlink (63MB)
- 21 Java modules including jdk.zipfs for JPype
- Wheel packaging with bundled JRE (162MB total)
- Automatic JRE detection in jvm.py
- All tests passing without system Java

Status: Production-ready prototype

Note: JRE binaries excluded from git via .gitignore

Author: tae898

bindings/python/prototype/.gitignore

@@ -0,0 +1,8 @@
+# Ignore build output
+output/
+*.log
+
+# Ignore test package artifacts (JRE, JARs, wheels, venvs)
+test-package/
+dist/
+*.whl

bindings/python/prototype/Dockerfile.jre-prototype

@@ -0,0 +1,52 @@
+# Dockerfile for JRE Bundling Prototype
+# Purpose: Analyze JAR dependencies and build minimal JRE for ArcadeDB
+
+# ARG must be before any FROM to be available globally
+ARG ARCADEDB_TAG=24.11.1
+
+# Copy ArcadeDB Docker image and extract JARs
+# We'll use the full ArcadeDB distribution as source
+FROM arcadedata/arcadedb:${ARCADEDB_TAG} AS arcadedb-source
+
+# Back to JRE builder
+FROM eclipse-temurin:21-jdk-jammy AS jre-analyzer
+
+WORKDIR /build
+
+# Copy JARs from ArcadeDB
+COPY --from=arcadedb-source /home/arcadedb/lib/*.jar /build/jars/
+
+# Define required Java modules for ArcadeDB
+# Based on analysis, these are the modules needed
+# We use a fixed list for reproducibility
+# Note: jdk.zipfs is required for JPype JAR filesystem support
+RUN mkdir -p /build/analysis && \
+    echo "java.base,java.compiler,java.desktop,java.logging,java.management,java.naming,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,jdk.incubator.vector,jdk.internal.vm.ci,jdk.jfr,jdk.management,jdk.sctp,jdk.unsupported,jdk.zipfs" > /build/analysis/required-modules.txt && \
+    echo "=== Required Java Platform Modules ===" && \
+    cat /build/analysis/required-modules.txt
+
+# Build minimal JRE with jlink
+# Note: We ignore split packages since they're in shaded JARs and not needed in JRE
+RUN MODULES=$(cat /build/analysis/required-modules.txt | tr -d '\n') && \
+    echo "Building JRE with modules: $MODULES" && \
+    jlink --module-path ${JAVA_HOME}/jmods \
+          --add-modules ${MODULES} \
+          --ignore-signing-information \
+          --strip-debug \
+          --no-man-pages \
+          --no-header-files \
+          --compress zip-9 \
+          --output /build/minimal-jre && \
+    echo "=== JRE Build Complete ===" && \
+    du -sh /build/minimal-jre
+
+# Test the minimal JRE
+RUN /build/minimal-jre/bin/java -version && \
+    echo "=== JRE Version Test Passed ==="
+
+# Final stage - minimal image with results
+FROM busybox:latest AS final
+COPY --from=jre-analyzer /build/analysis /analysis
+COPY --from=jre-analyzer /build/minimal-jre /minimal-jre
+COPY --from=jre-analyzer /build/jars /jars
+CMD ["/bin/sh"]

bindings/python/prototype/README.md

@@ -0,0 +1,46 @@
+# JRE Bundling Prototype
+
+This directory contains the Docker-based prototype for JRE bundling validation.
+
+## Purpose
+
+Validate the JRE bundling approach locally before implementing full CI/CD:
+
+- Analyze JAR dependencies with `jdeps`
+- Build minimal JRE with `jlink`
+- Test JRE functionality
+- Measure size impact
+
+## Quick Start
+
+```bash
+# Build the JRE prototype
+./build-jre-prototype.sh
+
+# Output will be in ./output/
+# - analysis/required-modules.txt - Java modules needed
+# - minimal-jre/                  - Minimal JRE build
+# - jars/                         - ArcadeDB JAR files
+```
+
+## Files
+
+- `Dockerfile.jre-prototype` - Multi-stage Docker build for JRE analysis and creation
+- `build-jre-prototype.sh` - Build script that orchestrates Docker build and extraction
+- `output/` - Generated output directory (git-ignored)
+
+## Expected Results
+
+- **JRE Size:** ~40-70 MB (compressed)
+- **Required Modules:** Core Java modules for ArcadeDB operation
+- **Functionality:** JRE can run `java -version` and basic JVM operations
+
+## Next Steps
+
+After successful prototype:
+
+1. Test JRE with Python/JPype
+2. Create prototype packages (base + JRE variants)
+3. Validate with actual ArcadeDB operations
+4. Document findings
+5. Update build system based on learnings

bindings/python/prototype/RESULTS.md

@@ -0,0 +1,136 @@
+# JRE Bundling Prototype Results
+
+## Status: ✅ SUCCESS
+
+This document tracks the results of the JRE bundling prototype.
+
+## Objective
+
+Create a minimal JRE bundled with the Python package to eliminate external Java dependency.
+
+## Approach
+
+Using Docker for reproducible builds:
+1. Analyze ArcadeDB JAR dependencies
+2. Build minimal JRE with jlink
+3. Package everything into a wheel
+
+## Results
+
+### ✅ Successful Implementation
+
+**Build System:**
+- Docker multi-stage build with Eclipse Temurin JDK 21
+- Fully reproducible, no host dependencies
+- Automated extraction and packaging workflow
+
+**JRE Specifications:**
+- Size: **63MB** (with zip-9 compression)
+- Java Version: OpenJDK 21.0.8 LTS (Temurin)
+- Modules: 21 Java platform modules
+  - Core: `java.base`, `java.compiler`, `java.logging`, `java.management`
+  - Database: `java.sql`, `java.transaction.xa`, `java.naming`
+  - Security: `java.security.jgss`, `java.security.sasl`
+  - Utilities: `java.xml`, `java.rmi`, `java.scripting`, `java.prefs`
+  - UI: `java.desktop` (for AWT/font support)
+  - JDK: `jdk.jfr`, `jdk.management`, `jdk.sctp`, `jdk.unsupported`, `jdk.incubator.vector`, `jdk.internal.vm.ci`
+  - **Critical:** `jdk.zipfs` (required for JPype JAR filesystem access)
+
+**Package Specifications:**
+- Wheel Size: **162MB** total
+  - JRE: 63MB
+  - JARs: 99MB (85 JARs, gRPC excluded)
+  - Python code: <1MB
+- Package Name: `arcadedb_embedded_jre_prototype`
+- Version: 25.10.1-SNAPSHOT (auto-detected from pom.xml)
+
+**Test Results:**
+```
+✅ Bundled JRE detected correctly (62.2 MB installed)
+✅ Database created successfully
+✅ Transaction committed
+✅ Query executed: bundled_jre_test = 42
+✅ Package works without system Java!
+```
+
+### Technical Implementation
+
+**Bundled JRE Detection (`jvm.py`):**
+```python
+def get_bundled_jre_path() -> str | None:
+    """Detect if a JRE is bundled with the package."""
+    package_dir = Path(__file__).parent
+    jre_dir = package_dir / "jre"
+    java_executable = jre_dir / "bin" / "java"
+    if java_executable.exists():
+        return str(java_executable)
+    return None
+```
+
+**JPype Integration:**
+- Automatically detects bundled JRE at `arcadedb_embedded/jre/`
+- Uses `libjvm.so` from `jre/lib/server/` for JPype startup
+- Falls back to system Java if bundled JRE not found
+- No code changes required in user applications
+
+**Build Process:**
+1. `build-jre-prototype.sh` - Builds JRE with Docker, extracts results
+2. `test-jre-wheel.sh` - Creates wheel, installs in venv, runs tests
+3. Fully automated, single command: `./build-jre-prototype.sh && ./test-jre-wheel.sh`
+
+### Key Learnings
+
+**Module Requirements:**
+- Initially missing `jdk.zipfs` caused JPype to fail with "Unable to find filesystem for jar"
+- JPype requires JAR filesystem support to access Java modules
+- All AWT/Desktop modules needed even for headless operation (ArcadeDB dependencies)
+
+**Version Management:**
+- `_version.py` must be generated before wheel build
+- Using `write_version.py` from parent directory works correctly
+- Version auto-detected from Maven `pom.xml`
+
+**JVM Startup:**
+- Must pass explicit `libjvm.so` path to JPype
+- Path: `jre/lib/server/libjvm.so` (relative to package root)
+- Cannot rely on JPype's default Java detection when bundling
+
+### File Sizes Comparison
+
+| Component | Size | Notes |
+|-----------|------|-------|
+| Minimal JRE (Docker) | 63MB | jlink with zip-9 compression |
+| JRE (installed) | 62.2MB | Extracted in site-packages |
+| All JARs | 99MB | 85 JARs excluding gRPC |
+| **Total Wheel** | **162MB** | Complete self-contained package |
+| Base Package (no JRE) | ~100MB | For comparison |
+
+### Next Steps
+
+1. **Integration into Main Build:**
+   - Add JRE variant to `build-all.sh`
+   - Create separate `pyproject.toml` for JRE variant
+   - Update GitHub Actions workflow
+
+2. **Package Variants:**
+   - `arcadedb-embedded` - Base package (requires system Java)
+   - `arcadedb-embedded-jre` - JRE bundled variant (162MB)
+
+3. **Documentation:**
+   - Update README with installation options
+   - Document JRE bundle for users without Java
+   - Add troubleshooting guide
+
+4. **Optimization Opportunities:**
+   - Profile which Java modules are actually used at runtime
+   - Consider platform-specific wheels (currently linux-x86_64 only)
+   - Evaluate GraalVM native-image for even smaller size
+
+### Conclusion
+
+**The JRE bundling prototype is fully functional and ready for integration.**
+
+- Zero external dependencies (no Java installation required)
+- Reasonable size increase (62MB for complete Java independence)
+- Fully automated Docker-based build
+- Production-ready implementation

bindings/python/prototype/build-jre-prototype.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Build JRE Prototype using Docker
+# This script builds a minimal JRE for ArcadeDB and extracts it for testing
+
+set -e
+
+echo "================================="
+echo "JRE Bundling Prototype Build"
+echo "================================="
+echo ""
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+# Auto-detect Docker tag from pom.xml (same logic as build-all.sh)
+echo "🔍 Detecting version from pom.xml..."
+ARCADEDB_TAG=$(python3 "${SCRIPT_DIR}/../extract_version.py" --format=docker)
+echo "📌 ArcadeDB version detected: ${ARCADEDB_TAG}"
+echo ""
+
+# Clean previous output
+rm -rf "${OUTPUT_DIR}"
+mkdir -p "${OUTPUT_DIR}"
+
+echo "Step 1: Building JRE prototype with Docker..."
+echo ""
+
+# Build the Docker image
+docker build \
+    --build-arg ARCADEDB_TAG="${ARCADEDB_TAG}" \
+    -f "${SCRIPT_DIR}/Dockerfile.jre-prototype" \
+    -t arcadedb-jre-prototype:latest \
+    "${SCRIPT_DIR}"
+
+echo ""
+echo "Step 2: Extracting JRE and analysis results..."
+echo ""
+
+# Create a temporary container to extract files
+CONTAINER_ID=$(docker create arcadedb-jre-prototype:latest)
+
+# Extract analysis results
+docker cp "${CONTAINER_ID}:/analysis" "${OUTPUT_DIR}/"
+
+# Extract minimal JRE
+docker cp "${CONTAINER_ID}:/minimal-jre" "${OUTPUT_DIR}/"
+
+# Extract JARs for reference
+docker cp "${CONTAINER_ID}:/jars" "${OUTPUT_DIR}/"
+
+# Clean up container
+docker rm "${CONTAINER_ID}"
+
+echo ""
+echo "Step 3: Analyzing results..."
+echo ""
+
+# Display module list
+echo "Required Java modules:"
+cat "${OUTPUT_DIR}/analysis/required-modules.txt"
+echo ""
+
+# Display JRE size
+JRE_SIZE=$(du -sh "${OUTPUT_DIR}/minimal-jre" | cut -f1)
+echo "Minimal JRE size: ${JRE_SIZE}"
+echo ""
+
+# Count JARs (excluding gRPC)
+JAR_COUNT=$(ls "${OUTPUT_DIR}/jars"/*.jar 2> /dev/null | wc -l)
+GRPC_COUNT=$(ls "${OUTPUT_DIR}/jars"/*grpcw*.jar 2> /dev/null | wc -l || echo 0)
+FILTERED_COUNT=$((JAR_COUNT - GRPC_COUNT))
+echo "Total JARs: ${JAR_COUNT}"
+echo "gRPC JARs (excluded): ${GRPC_COUNT}"
+echo "Filtered JARs: ${FILTERED_COUNT}"
+echo ""
+
+# Test the JRE
+echo "Step 4: Testing minimal JRE..."
+"${OUTPUT_DIR}/minimal-jre/bin/java" -version
+echo ""
+
+echo "================================="
+echo "✅ Prototype build complete!"
+echo "================================="
+echo ""
+echo "Output directory: ${OUTPUT_DIR}"
+echo ""
+echo "Next steps:"
+echo "  1. Review required modules in: ${OUTPUT_DIR}/analysis/required-modules.txt"
+echo "  2. Test JRE with Python/JPype"
+echo "  3. Create prototype packages (base + JRE variants)"
+echo ""