Java publishing (microsoft#151)

* bindings/java: Add prefix to native methods

* bindings/java: Add javadocs and missing methods to Engine

* Setup publishing uber-JAR via GitHub workflow

* bindings/java: Update README

* bindings/java: Improve native library loading from JAR

* bindings/java: Fix usage of `working-directory`

* bindings/java: Pass required `distribution` parameter to `actions/setup-java@v4`

* bindings/java: Use Corretto distribution

This is because Microsoft doesn't provide JDK8,
see https://learn.microsoft.com/en-us/java/openjdk/download#openjdk-8.

* bindings/java: Install GCC toolchain for `aarch64-unknown-linux-gnu`

* bindings/java: Upload artifacts with different names from each step

* bindings/java: Upload built JARs to GitHub

.github/workflows/publish-java.yml

@@ -0,0 +1,87 @@
+name: publish-java
+
+on: workflow_dispatch
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build for ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            extension: so
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+            extension: so
+          - target: x86_64-apple-darwin
+            os: macos-latest
+            extension: dylib
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            extension: dylib
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+            extension: dll
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 8
+          distribution: "corretto"
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - if: ${{ matrix.target == 'aarch64-unknown-linux-gnu' }}
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+          # Setup for cargo
+          echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> $GITHUB_ENV
+
+      - run: cargo build --release --target ${{ matrix.target }} --manifest-path ./bindings/java/Cargo.toml
+      - run: mkdir -p native/${{ matrix.target }}
+      - run: mv target/${{ matrix.target }}/release/*.${{ matrix.extension }} ./native/${{ matrix.target }}/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: native-libraries-${{ matrix.target }}
+          path: native/
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 8
+          distribution: "corretto"
+          server-id: ossrh
+          server-username: MAVEN_USERNAME
+          server-password: MAVEN_PASSWORD
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: native-libraries-*
+          merge-multiple: true
+          path: ./bindings/java/native/
+      - run: mvn package
+        working-directory: ./bindings/java
+      - uses: actions/upload-artifact@v4
+        with:
+          name: built-jars
+          path: ./bindings/java/target/regorus-java-*.jar
+      - run: mvn deploy
+        working-directory: ./bindings/java
+        env:
+          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

bindings/java/README.md

@@ -8,42 +8,90 @@
 
 See main [Regorus page](https://github.com/microsoft/regorus) for more details about the project.
 
-Regorus can be used in Java via `com.microsoft.regorus` package. (It is not yet available in Maven Central, but can be manually built.)
+## Usage
 
-## Building
+Regorus Java is published to Maven Central with native libraries for the following:
 
-You can build this binding using [Maven](https://maven.apache.org/):
-```shell
-$ mvn package
-$ file target/regorus-java-0.0.1*
-target/regorus-java-0.0.1-osx-aarch_64.jar: Zip archive data, at least v1.0 to extract, compression method=deflate
-target/regorus-java-0.0.1.jar:              Zip archive data, at least v1.0 to extract, compression method=deflate
+- 64-bit Linux (kernel 3.2+, glibc 2.17+)
+- ARM64 Linux (kernel 4.1, glibc 2.17+)
+- 64-bit macOS (10.12+, Sierra+)
+- ARM64 macOS (11.0+, Big Sur+)
+- 64-bit MSVC (Windows 7+)
+
+If you need to run it in a different OS or an architecture you need to manually [build it](#Building).
+
+If you're on one of the supported platforms, you can just pull prebuilt JAR from Maven Central by declaring a dependency on `com.microsoft.regorus:regorus-java`.
+
+With [Maven](https://maven.apache.org/):
+```xml
+<dependencies>
+    <dependency>
+        <groupId>com.microsoft.regorus</groupId>
+        <artifactId>regorus-java</artifactId>
+        <version>0.0.1</version>
+    </dependency>
+</dependencies>
 ```
 
-## Usage
+With [Gradle](https://gradle.org/):
+```kotlin
+// build.gradle.kts
+implementation("com.microsoft.regorus:regorus-java:0.0.1")
+```
+
+Afterwards you can use it as follows:
 
 ```java
 import com.microsoft.regorus.Engine;
 
 public class Test {
     public static void main(String[] args) {
         try (Engine engine = new Engine()) {
-            engine.pubAddPolicy(
+            engine.addPolicy(
                 "hello.rego",
                 "package test\nmessage = concat(\", \", [input.message, data.message])"
             );
-            engine.pubAddDataJson("{\"message\":\"World!\"}");
-            engine.pubSetInputJson("{\"message\":\"Hello\"}");
-            String resJson = engine.pubEvalQuery("data.test.message");
+            engine.addDataJson("{\"message\":\"World!\"}");
+            engine.setInputJson("{\"message\":\"Hello\"}");
+            String resJson = engine.evalQuery("data.test.message");
 
             System.out.println(resJson);
         }
     }
 }
 ```
 
-and run it with:
+And you can see the following output once you run it:
 ```shell
-$ java -cp target/regorus-java-0.0.1.jar:target/regorus-java-0.0.1-osx-aarch_64.jar Test.java
 {"result":[{"expressions":[{"value":"Hello, World!","text":"data.test.message","location":{"row":1,"col":1}}]}]}
-```
+```
+
+## Building
+
+In order to build Regorus Java for a target platform, you need to install Rust target
+for that target platform first:
+
+```bash
+$ rustup target add aarch64-apple-darwin
+```
+
+Afterwards, you can build native library for that target using:
+```bash
+$ cargo build --release --target aarch64-apple-darwin
+```
+
+You will then have a native library at `../../target/aarch64-apple-darwin/release/libregorus_java.dylib` depending on your target.
+
+You can then build a JAR from source using:
+```bash
+$ mvn package
+```
+
+And you will have a JAR at `./target/regorus-java-0.0.1.jar`.
+
+You need to make sure both of the artifacts in Java's classpath.
+For example with `java` CLI:
+```bash
+$ java -Djava.library.path=../../target/aarch64-apple-darwin/release/ -cp target/regorus-java-0.0.1.jar Test.java
+```
+