feat(jni): Maven distribution of the Java API on GitHub Packages

.github/workflows/maven.yml

@@ -0,0 +1,55 @@
+name: maven
+
+on:
+  push:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: version to publish (e.g. 5.5.0-test1)
+        required: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: setup java
+        uses: actions/setup-java@f4f1212c880fdec8162ea9a6493f4495191887b4 # v5
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+          server-id: github
+
+      - name: get version
+        if: github.event_name != 'push'
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+        run: |
+          if [ "${{ github.event_name }}" = release ]; then
+            echo "REVISION=${GITHUB_REF_NAME:1}" >> $GITHUB_ENV
+          else
+            echo "REVISION=${INPUT_VERSION}" >> $GITHUB_ENV
+          fi
+
+      - name: build
+        if: github.event_name == 'push'
+        run: mvn --batch-mode --no-transfer-progress --file jni/pom.xml verify
+
+      - name: publish
+        if: github.event_name != 'push'
+        run: mvn --batch-mode --no-transfer-progress --file jni/pom.xml deploy -Drevision="${REVISION}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -37,6 +37,8 @@
 ## OpenDocument.core
 build/
 cmake-build-*/
+jni/target/
+jni/.flattened-pom.xml
 .clangd
 CMakeUserPresets.json
 # machine-specific Conan cache paths, generated by scripts/gen-vscode-env.py

jni/AGENTS.md

@@ -9,6 +9,7 @@ package `app.opendocument.core`. Mirrors the surface of the python bindings
 | Path | What |
 |------|------|
 | `CMakeLists.txt` | Builds `libodr_jni` + `odr-core-java.jar`; included from the root build via `ODR_JNI`, or standalone against an installed `odrcore`. |
+| `pom.xml` | Maven distribution of the Java classes only (`app.opendocument:odr-core-java`); published to GitHub Packages on release via `.github/workflows/maven.yml`. Keep `--release`/`-Xlint` in sync with `CMAKE_JAVA_COMPILE_FLAGS`. |
 | `src/` | JNI sources, one `jni_*` unit per public-API area; `odr_jni.hpp` (strings, exceptions, handles) and `jni_convert.hpp` (struct/POJO marshalling) are the helpers. |
 | `java/app/opendocument/core/` | Java API: enums, POJOs (styles, metas, `HtmlConfig`), and handle-backed wrappers extending `NativeResource`. |
 | `tests/` | JUnit 5 suite, run via ctest (`odr_jni_junit`); inputs are generated inline (tmp files, zip-built minimal ODT) — no fixture files. |

jni/README.md

@@ -22,6 +22,36 @@ The native library is loaded from `java.library.path` as `odr_jni`
 (`libodr_jni.so`/`libodr_jni.dylib`); the system property
 `app.opendocument.core.library` overrides it with an absolute path.
 
+## Maven distribution
+
+The Java classes are published as `app.opendocument:odr-core-java` to
+[GitHub Packages](https://github.com/orgs/opendocument-app/packages?repo_name=OpenDocument.core)
+on release (`.github/workflows/maven.yml`, built from `pom.xml`). The artifact
+contains **only the Java API** — consumers build the native `odr_jni` library
+themselves for their target platform (see below) and provide it at runtime.
+
+```gradle
+repositories {
+    maven {
+        url = uri("https://maven.pkg.github.com/opendocument-app/OpenDocument.core")
+        credentials {
+            username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR")
+            password = providers.gradleProperty("gpr.key").orNull ?: System.getenv("GITHUB_TOKEN")
+        }
+    }
+}
+
+dependencies {
+    implementation "app.opendocument:odr-core-java:<version>"
+}
+```
+
+Note: GitHub Packages requires authentication (a token with `read:packages`)
+even for public packages.
+
+Local build: `mvn --file jni/pom.xml verify` (produces the jar plus sources
+and javadoc jars in `jni/target/`).
+
 ## Building
 
 The bindings are part of the main CMake build, toggled by `ODR_JNI` (requires

jni/pom.xml

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Maven distribution of the Java API (`app.opendocument.core`), classes only.
+     The native library (`libodr_jni`) is not part of this artifact; consumers
+     build it themselves against their target platform (see README.md).
+     The version is injected by CI via `-Drevision=<version>` on release. -->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>app.opendocument</groupId>
+  <artifactId>odr-core-java</artifactId>
+  <version>${revision}</version>
+  <packaging>jar</packaging>
+
+  <name>odr-core-java</name>
+  <description>Java bindings for OpenDocument.core — decode office documents (ODF, OOXML, legacy MS binary, PDF, CSV, ...) and render them to HTML</description>
+  <url>https://github.com/opendocument-app/OpenDocument.core</url>
+
+  <licenses>
+    <license>
+      <name>MPL-2.0</name>
+      <url>https://www.mozilla.org/en-US/MPL/2.0/</url>
+    </license>
+  </licenses>
+
+  <scm>
+    <connection>scm:git:https://github.com/opendocument-app/OpenDocument.core.git</connection>
+    <developerConnection>scm:git:git@github.com:opendocument-app/OpenDocument.core.git</developerConnection>
+    <url>https://github.com/opendocument-app/OpenDocument.core</url>
+  </scm>
+
+  <properties>
+    <revision>0.0.0-SNAPSHOT</revision>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <!-- Keep in sync with CMAKE_JAVA_COMPILE_FLAGS in CMakeLists.txt. -->
+    <maven.compiler.release>17</maven.compiler.release>
+  </properties>
+
+  <build>
+    <sourceDirectory>java</sourceDirectory>
+
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.13.0</version>
+        <configuration>
+          <compilerArgs>
+            <arg>-Xlint:all</arg>
+          </compilerArgs>
+        </configuration>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-source-plugin</artifactId>
+        <version>3.3.1</version>
+        <executions>
+          <execution>
+            <id>attach-sources</id>
+            <goals>
+              <goal>jar-no-fork</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>3.11.2</version>
+        <configuration>
+          <doclint>all,-missing</doclint>
+        </configuration>
+        <executions>
+          <execution>
+            <id>attach-javadocs</id>
+            <goals>
+              <goal>jar</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+
+      <!-- Resolves ${revision} in the deployed pom (CI-friendly versions). -->
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>flatten-maven-plugin</artifactId>
+        <version>1.6.0</version>
+        <configuration>
+          <flattenMode>ossrh</flattenMode>
+        </configuration>
+        <executions>
+          <execution>
+            <id>flatten</id>
+            <phase>process-resources</phase>
+            <goals>
+              <goal>flatten</goal>
+            </goals>
+          </execution>
+          <execution>
+            <id>flatten.clean</id>
+            <phase>clean</phase>
+            <goals>
+              <goal>clean</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+  <distributionManagement>
+    <repository>
+      <id>github</id>
+      <name>GitHub Packages</name>
+      <url>https://maven.pkg.github.com/opendocument-app/OpenDocument.core</url>
+    </repository>
+  </distributionManagement>
+</project>