Refactor java-sdk (#136)

- Refactor Plugin
- Make `Plugin` and `Context` `AutoClosable` to automatically free
resources in TWR blocks
- Add missing javadoc
- Upgrade to Junit 5
- Reorganize packages
- Use more meaningful names
- Introduce `ExtismException`
- Make JSON serialization pluggable
- Lower required java version to Java 17

Improves #117

java/pom.xml

@@ -6,9 +6,9 @@
   <packaging>jar</packaging>
   <version>1.0-SNAPSHOT</version>
   <name>extism</name>
-  <url>http://maven.apache.org</url>
+  <url>https://github.com/extism/extism</url>
   <properties>
-    <java.version>19</java.version>
+    <java.version>17</java.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   </properties>
   <build>
@@ -18,8 +18,7 @@
         <artifactId>maven-compiler-plugin</artifactId>
         <version>3.10.1</version>
         <configuration>
-            <source>${java.version}</source>
-            <target>${java.version}</target>
+            <release>${java.version}</release>
         </configuration>
       </plugin>
       <plugin>
@@ -68,9 +67,15 @@
       <version>2.10</version>
     </dependency>
     <dependency>
-      <groupId>junit</groupId>
-      <artifactId>junit</artifactId>
-      <version>3.8.1</version>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <version>5.9.1</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <version>3.23.1</version>
       <scope>test</scope>
     </dependency>
   </dependencies>

java/src/main/java/org/extism/sdk/Context.java

@@ -1,19 +1,23 @@
 package org.extism.sdk;
 
-import org.extism.sdk.manifest.ManifestWasmData;
-import org.extism.sdk.manifest.ManifestWasm;
 import org.extism.sdk.manifest.Manifest;
 
 import com.sun.jna.Pointer;
 
-// ExtismContext is used to store and manage plugins
-public class Context {
+/**
+ * Extism Context is used to store and manage plugins.
+ */
+public class Context implements AutoCloseable {
 
-    // A pointer to the ExtismContext struct
-    private Pointer contextPointer;
+    /**
+     * Holds a pointer to the ExtismContext struct.
+     */
+    private final Pointer contextPointer;
 
     /**
-     * Create a new Context. A Context is used to manage Plugins
+     * Creates a new context.
+     * <p>
+     * A Context is used to manage Plugins
      * and make sure they are cleaned up when you are done with them.
      */
     public Context() {
@@ -50,21 +54,35 @@ public void reset() {
 
     /**
      * Get the version string of the linked Extism Runtime.
-     * 
-     * @return
+     *
+     * @return the version
      */
     public String getVersion() {
         return LibExtism.INSTANCE.extism_version();
     }
 
-    // Get the error associated with a context, if plugin is null then the context
-    // error will be returned
-    protected String error(Plugin plugin) {
+    /**
+     * Get the error associated with a context, if plugin is {@literal null} then the context error will be returned.
+     * @param plugin
+     * @return
+     */
+    public String error(Plugin plugin) {
         return LibExtism.INSTANCE.extism_error(this.contextPointer, plugin == null ? -1 : plugin.getIndex());
     }
 
-    protected Pointer getPointer() {
+    /**
+     * Return the raw pointer to this context.
+     * @return
+     */
+    public Pointer getPointer() {
         return this.contextPointer;
     }
 
+    /**
+     * Calls {@link #free()} if used in the context of a TWR block.
+     */
+    @Override
+    public void close() {
+        this.free();
+    }
 }

java/src/main/java/org/extism/sdk/ExtismException.java

@@ -0,0 +1,15 @@
+package org.extism.sdk;
+
+public class ExtismException extends RuntimeException {
+
+    public ExtismException() {
+    }
+
+    public ExtismException(String message) {
+        super(message);
+    }
+
+    public ExtismException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

java/src/main/java/org/extism/sdk/LibExtism.java

@@ -5,39 +5,131 @@
 import com.sun.jna.Pointer;
 import com.sun.jna.ptr.IntByReference;
 
+/**
+ * Wrapper around the Extism library.
+ */
 public interface LibExtism extends Library {
 
     /**
      * Holds the extism library instance.
-     *
      * Resolves the extism library based on the resolution algorithm defined in {@link com.sun.jna.NativeLibrary}.
      */
     LibExtism INSTANCE = Native.loadLibrary("extism", LibExtism.class);
 
+    /**
+     * Create a new context
+     */
     Pointer extism_context_new();
 
+    /**
+     * Free a context
+     */
     void extism_context_free(Pointer contextPointer);
 
+    /**
+     * Remove all plugins from the registry.
+     *
+     * @param contextPointer
+     */
     void extism_context_reset(Pointer contextPointer);
 
+    /**
+     * Returns the error associated with a @{@link Context} or @{@link Plugin}, if {@code pluginId} is {@literal -1} then the context error will be returned
+     *
+     * @param contextPointer
+     * @param pluginId
+     * @return
+     */
     String extism_error(Pointer contextPointer, int pluginId);
 
+    /**
+     * Create a new plugin.
+     *
+     * @param contextPointer pointer to the {@link Context}.
+     * @param wasm           is a WASM module (wat or wasm) or a JSON encoded manifest
+     * @param wasmSize       the length of the `wasm` parameter
+     * @param withWASI       enables/disables WASI
+     * @return id of the plugin
+     */
     int extism_plugin_new(long contextPointer, byte[] wasm, long wasmSize, boolean withWASI);
 
+    /**
+     * Returns the Extism version string
+     */
     String extism_version();
 
-    void extism_plugin_new(Pointer contextPointer, byte[] wasm, int length, boolean withWASI,
-            IntByReference pluginIndex);
+    /**
+     * Create a new plugin.
+     *
+     * @param contextPointer pointer to the {@link Context}.
+     * @param wasm           is a WASM module (wat or wasm) or a JSON encoded manifest
+     * @param length         the length of the `wasm` parameter
+     * @param withWASI       enables/disables WASI
+     * @param pluginIndex    output parameter for the plugin id.
+     * @see #extism_plugin_new(long, byte[], long, boolean)
+     */
+    void extism_plugin_new(Pointer contextPointer, byte[] wasm, int length, boolean withWASI, IntByReference pluginIndex);
 
-    int extism_plugin_call(Pointer contextPointer, int pluginIndex, String function_name, byte[] wasm, int length);
+    /**
+     * Calls a function from the @{@link Plugin} at the given {@code pluginIndex}.
+     *
+     * @param contextPointer
+     * @param pluginIndex
+     * @param function_name  is the function to call
+     * @param data           is the data input data
+     * @param dataLength     is the data input data length
+     * @return the result code of the plugin call.
+     */
+    int extism_plugin_call(Pointer contextPointer, int pluginIndex, String function_name, byte[] data, int dataLength);
 
+    /**
+     * Returns the length of a plugin's output data.
+     *
+     * @param contextPointer
+     * @param pluginIndex
+     * @return
+     */
     int extism_plugin_output_length(Pointer contextPointer, int pluginIndex);
 
+    /**
+     * Returns the plugin's output data.
+     *
+     * @param contextPointer
+     * @param pluginIndex
+     * @return
+     */
     Pointer extism_plugin_output_data(Pointer contextPointer, int pluginIndex);
 
+    /**
+     * Update a plugin, keeping the existing ID.
+     * Similar to {@link #extism_plugin_new(long, byte[], long, boolean)} but takes an {@code pluginIndex} argument to specify which plugin to update.
+     * Note: Memory for this plugin will be reset upon update.
+     *
+     * @param contextPointer
+     * @param pluginIndex
+     * @param wasm
+     * @param length
+     * @param withWASI
+     * @return
+     */
     boolean extism_plugin_update(Pointer contextPointer, int pluginIndex, byte[] wasm, int length, boolean withWASI);
 
+    /**
+     * Remove a plugin from the registry and free associated memory.
+     *
+     * @param contextPointer
+     * @param pluginIndex
+     */
     void extism_plugin_free(Pointer contextPointer, int pluginIndex);
 
+    /**
+     * Update plugin config values, this will merge with the existing values.
+     *
+     * @param contextPointer
+     * @param pluginIndex
+     * @param json
+     * @param jsonLength
+     * @return
+     */
     boolean extism_plugin_config(Pointer contextPointer, int pluginIndex, byte[] json, int jsonLength);
 }