[DOC] update docs (#9)
* [DOC] update docs
* [DOC] init RELEASE-NOTES.md
* update apple-m3 dylib
* pass mvn package
diff --git a/README.md b/README.md
index 8e3b3a5..0c4a4ea 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,71 @@
# shenyu-wasm
-This repository is forked from [wasmer-java](https://github.com/wasmerio/wasmer-java), if you find anything unreasonable, please contact `zhangzicheng@apache.org`.
+This repository is forked from [wasmer-java](https://github.com/wasmerio/wasmer-java), which simplifies usage by directly packing the dylib into the jar, and decompressing and loading the dylib at runtime, ready to use out of the box.
+
+If you find anything unreasonable, please send email `dev@shenyu.apache.org` or `zhangzicheng@apache.org`.
+
+## Note: Only 64-bit CPU architecture is supported now !
+If shenyu-wasm does not support your CPU architecture or system, you need to build dylib yourself, check `Build dylib on my own` below.
+
+## How to use this library ?
+### step1 add dependency
+maven
+```xml
+<dependency>
+ <groupId>org.apache.shenyu</groupId>
+ <artifactId>shenyu-wasm-runtime</artifactId>
+ <version>${x.y.z}</version>
+</dependency>
+```
+gradle
+```groovy
+compile "org.apache.shenyu:shenyu-wasm-runtime:${x.y.z}"
+```
+### step2 write native source code
+Below is a example of rust(any other language that compiles to WebAssembly can be used here):
+```rust
+#[no_mangle]
+pub extern fn sum(x: i32, y: i32) -> i32 {
+ x + y
+}
+```
+### step3 compile source code to a wasm file
+
+### step4 execute wasm in java
+```java
+class Example {
+ public static void main(String[] args) {
+ // `simple.wasm` is located at `tests/resources/`.
+ Path wasmPath = Paths.get(Example.class.getClassLoader().getResource("simple.wasm").getPath());
+ // Reads the WebAssembly module as bytes.
+ byte[] wasmBytes = Files.readAllBytes(wasmPath);
+ // Instantiates the WebAssembly module.
+ Instance instance = new Instance(wasmBytes);
+ // Calls an exported function, and returns an object array.
+ Object[] results = instance.exports.getFunction("sum").apply(5, 37);
+ System.out.println(results[0]); // 42
+ // Drops an instance object pointer which is stored in Rust.
+ instance.close();
+ }
+}
+```
+
+## Build dylib on my own
+### step1 install rust
+### step2 build dylib
+```shell
+cd ~
+git clone https://github.com/apache/shenyu-wasm.git
+cd shenyu-wasm/shenyu-wasm-build/
+cargo build --release
+```
+In macos, you will get the `dylib` in `~/shenyu-wasm/shenyu-wasm-build/target/libshenyu_wasm.dylib`;
+
+In linux, you will get the `so` in `~/shenyu-wasm/shenyu-wasm-build/target/libshenyu_wasm.so`;
+
+In windows, you will get the `dll` in `~/shenyu-wasm/shenyu-wasm-build/target/libshenyu_wasm.dll`;
+
+### step3 use dylib
+Renaming the dylib we built in the previous step, with a naming format of `libshenyu_wasm_$(architecture).$(os_cdylib_suffix)`(e.g. libshenyu_wasm_x86_64.dylib), then put it in your own project module(the full path should like `${your_java_project_name}/${your_module_name}/src/main/resources/libshenyu_wasm_$(architecture).$(os_cdylib_suffix)`).
+
+Finally, at runtime, `native-lib-loader` will load it.
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
new file mode 100644
index 0000000..2099d6c
--- /dev/null
+++ b/RELEASE-NOTES.md
@@ -0,0 +1,10 @@
+## 1.0.0
+
+### New Features
+
+1. Simplify usage
+2. Support the use of user-defined dynamic link libraries
+
+### Refactor
+
+1. Refactor repository from [wasmer-java](https://github.com/wasmerio/wasmer-java).
diff --git a/script/shenyu_wasm_code_style.xml b/script/shenyu_wasm_code_style.xml
new file mode 100644
index 0000000..e2fbbdc
--- /dev/null
+++ b/script/shenyu_wasm_code_style.xml
@@ -0,0 +1,11 @@
+<code_scheme name="Default" version="173">
+ <JavaCodeStyleSettings>
+ <option name="CLASS_COUNT_TO_USE_IMPORT_ON_DEMAND" value="99999" />
+ <option name="NAMES_COUNT_TO_USE_IMPORT_ON_DEMAND" value="9999" />
+ </JavaCodeStyleSettings>
+ <codeStyleSettings language="JAVA">
+ <indentOptions>
+ <option name="KEEP_INDENTS_ON_EMPTY_LINES" value="true" />
+ </indentOptions>
+ </codeStyleSettings>
+</code_scheme>
\ No newline at end of file
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Exports.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Exports.java
index dfe36a9..136f639 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Exports.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Exports.java
@@ -19,8 +19,10 @@
import java.util.HashMap;
import java.util.Map;
+import java.util.function.Function;
+
import org.apache.shenyu.wasm.exports.Export;
-import org.apache.shenyu.wasm.exports.Function;
+import org.apache.shenyu.wasm.exports.NativeFunction;
/**
* `Exports` is a Java class that represents the set of WebAssembly exports.
@@ -48,9 +50,9 @@
* Lambda expression for currying. This takes a function name and returns the function to call WebAssembly
* function.
*/
- private final java.util.function.Function<String, Function> functionWrapperGenerator =
- functionName -> arguments -> this.instance.nativeCallExportedFunction(
- this.instance.getInstancePointer(), functionName, arguments);
+ private final Function<String, NativeFunction> functionWrapperGenerator
+ = functionName -> arguments -> this.instance.nativeCallExportedFunction(
+ this.instance.getInstancePointer(), functionName, arguments);
/**
* The constructor instantiates new exported functions.
@@ -79,8 +81,8 @@
* @return the exported function
* @throws ClassCastException if class cast failed
*/
- public Function getFunction(final String name) throws ClassCastException {
- return (Function) this.inner.get(name);
+ public NativeFunction getFunction(final String name) throws ClassCastException {
+ return (NativeFunction) this.inner.get(name);
}
/**
@@ -111,7 +113,7 @@
/**
* Generate the exported function wrapper.
*/
- private Function generateFunctionWrapper(final String functionName) {
+ private NativeFunction generateFunctionWrapper(final String functionName) {
return this.functionWrapperGenerator.apply(functionName);
}
}
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Instance.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Instance.java
index 91302cb..1ffa3f1 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Instance.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Instance.java
@@ -17,7 +17,7 @@
package org.apache.shenyu.wasm;
-import org.apache.shenyu.wasm.exports.Function;
+import org.apache.shenyu.wasm.exports.NativeFunction;
/**
* `Instance` is a Java class that represents a WebAssembly instance.
@@ -56,6 +56,9 @@
nativeInitializeExportedMemories(instancePointer);
}
+ /**
+ * The constructor instantiates a new WebAssembly instance.
+ */
protected Instance() {
this.exports = new Exports(this);
}
@@ -74,6 +77,7 @@
* Delete an instance object pointer, which is called by the garbage collector before an object is removed from the
* memory.
*/
+ @SuppressWarnings("removal")
@Override
protected void finalize() throws Throwable {
this.close();
@@ -105,7 +109,7 @@
* @return the exported function
* @throws ClassCastException if class cast failed
*/
- public Function getFunction(final String name) throws ClassCastException {
+ public NativeFunction getFunction(final String name) throws ClassCastException {
return this.exports.getFunction(name);
}
@@ -122,12 +126,35 @@
private native long nativeInstantiate(Instance self, byte[] moduleBytes);
+ /**
+ * Clean native resources.
+ *
+ * @param instancePointer pointer.
+ */
private native void nativeDrop(long instancePointer);
+ /**
+ * Export native call as java functions.
+ *
+ * @param instancePointer pointer.
+ * @param exportName name.
+ * @param arguments args.
+ * @return java functions.
+ */
protected native Object[] nativeCallExportedFunction(long instancePointer, String exportName, Object[] arguments);
+ /**
+ * nativeInitializeExportedFunctions.
+ *
+ * @param instancePointer pointer.
+ */
protected static native void nativeInitializeExportedFunctions(long instancePointer);
+ /**
+ * nativeInitializeExportedMemories.
+ *
+ * @param instancePointer pointer.
+ */
protected static native void nativeInitializeExportedMemories(long instancePointer);
}
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Memory.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Memory.java
index 7226f8b..ba5c120 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Memory.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Memory.java
@@ -19,6 +19,7 @@
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
+
import org.apache.shenyu.wasm.exports.Export;
/**
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Module.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Module.java
index 0b9f7ee..588c781 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Module.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Module.java
@@ -53,7 +53,6 @@
* Create an original Module object from a byte array.
*
* @param serializedBytes serialized bytes
- *
* @return Module object.
*/
public static Module deserialize(final byte[] serializedBytes) {
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Native.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Native.java
index e7224d1..65dc41b 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Native.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/Native.java
@@ -19,6 +19,7 @@
import java.io.File;
import java.util.concurrent.atomic.AtomicBoolean;
+
import org.scijava.nativelib.JniExtractor;
import org.scijava.nativelib.NativeLoader;
@@ -26,12 +27,15 @@
* Code reduced and simplified from zmq integration in Java. See
* https://github.com/zeromq/jzmq/blob/3384ea1c04876426215fe76b5d1aabc58c099ca0/jzmq-jni/src/main/java/org/zeromq/EmbeddedLibraryTools.java.
*/
-public class Native {
+public abstract class Native {
private static final AtomicBoolean INITED = new AtomicBoolean();
private static final AtomicBoolean SUCCESS = new AtomicBoolean();
+ private Native() {
+ }
+
/**
* load the native library.
*/
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/NativeUtils.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/NativeUtils.java
index 54232ee..cc4c690 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/NativeUtils.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/NativeUtils.java
@@ -22,7 +22,7 @@
/**
* The type NativeUtils.
*/
-public class NativeUtils {
+public abstract class NativeUtils {
private static final String OPERATING_SYSTEM_NAME = System.getProperty("os.name").toLowerCase(Locale.ENGLISH);
@@ -42,6 +42,9 @@
}
}
+ private NativeUtils() {
+ }
+
/**
* detect native library name.
*
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/ShenyuWasmInitException.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/ShenyuWasmInitException.java
index 458429e..933b4f2 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/ShenyuWasmInitException.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/ShenyuWasmInitException.java
@@ -26,7 +26,8 @@
private static final long serialVersionUID = -2853315010514908541L;
- /** Constructs a new exception with {@code null} as its
+ /**
+ * Constructs a new exception with {@code null} as its
* detail message. The cause is not initialized, and may subsequently be
* initialized by a call to {@link #initCause}.
*/
@@ -55,11 +56,11 @@
* this exception's detail message.
*
* @param message the detail message (which is saved for later retrieval
- * by the {@link #getMessage()} method).
- * @param cause the cause (which is saved for later retrieval by the
- * {@link #getCause()} method). (A <tt>null</tt> value is
- * permitted, and indicates that the cause is nonexistent or
- * unknown.)
+ * by the {@link #getMessage()} method).
+ * @param cause the cause (which is saved for later retrieval by the
+ * {@link #getCause()} method). (A null value is
+ * permitted, and indicates that the cause is nonexistent or
+ * unknown.)
*/
public ShenyuWasmInitException(final String message, final Throwable cause) {
super(message, cause);
@@ -67,15 +68,15 @@
/**
* Constructs a new exception with the specified cause and a
- * detail message of <tt>(cause==null ? null : cause.toString())</tt>
+ * detail message of (cause==null ? null : cause.toString())
* (which typically contains the class and detail message of
- * <tt>cause</tt>). This constructor is useful for exceptions
+ * cause). This constructor is useful for exceptions
* that are little more than wrappers for other throwables.
*
* @param cause the cause (which is saved for later retrieval by the
- * {@link #getCause()} method). (A <tt>null</tt> value is
- * permitted, and indicates that the cause is nonexistent or
- * unknown.)
+ * {@link #getCause()} method). (A null value is
+ * permitted, and indicates that the cause is nonexistent or
+ * unknown.)
*/
public ShenyuWasmInitException(final Throwable cause) {
super(cause);
diff --git a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/exports/Function.java b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/exports/NativeFunction.java
similarity index 96%
rename from shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/exports/Function.java
rename to shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/exports/NativeFunction.java
index e71dc30..cd7af0f 100644
--- a/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/exports/Function.java
+++ b/shenyu-wasm-runtime/src/main/java/org/apache/shenyu/wasm/exports/NativeFunction.java
@@ -24,7 +24,7 @@
* <p>The apply method takes an arbitrary number of arguments and returns an output.
*/
@FunctionalInterface
-public interface Function extends Export {
+public interface NativeFunction extends Export {
/**
* call the function from WASM.
diff --git a/shenyu-wasm-runtime/src/main/resources/libshenyu_wasm_aarch64.dylib b/shenyu-wasm-runtime/src/main/resources/libshenyu_wasm_aarch64.dylib
new file mode 100755
index 0000000..72bbf00
--- /dev/null
+++ b/shenyu-wasm-runtime/src/main/resources/libshenyu_wasm_aarch64.dylib
Binary files differ
diff --git a/shenyu-wasm-runtime/src/test/java/org/apache/shenyu/wasm/InstanceTest.java b/shenyu-wasm-runtime/src/test/java/org/apache/shenyu/wasm/InstanceTest.java
index 17dfcd0..7771d86 100644
--- a/shenyu-wasm-runtime/src/test/java/org/apache/shenyu/wasm/InstanceTest.java
+++ b/shenyu-wasm-runtime/src/test/java/org/apache/shenyu/wasm/InstanceTest.java
@@ -26,7 +26,7 @@
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Objects;
-import org.apache.shenyu.wasm.exports.Function;
+import org.apache.shenyu.wasm.exports.NativeFunction;
import org.junit.jupiter.api.Test;
class InstanceTest {
@@ -40,7 +40,7 @@
@Test
void sum() throws Exception {
Instance instance = new Instance(getBytes());
- Function sum = instance.getFunction("sum");
+ NativeFunction sum = instance.getFunction("sum");
assertEquals(3, sum.apply(1, 2)[0]);
