A complete and mature WebAssembly runtime for Java based on Wasmer.
Features:
- Easy to use: The
wasmerAPI mimics the standard WebAssembly API, - Fast: The Wasmer JNI executes the WebAssembly modules as fast as possible, close to native speed,
- Safe: All calls to WebAssembly will be fast, but more importantly, completely safe and sandboxed.
The Wasmer package is published in Bintray on the
wasmer/wasmer-jni
repository.
The JAR files are named as follows:
wasmer-jni-$(architecture)-$(os)-$(version).jar. Thus, to include
Wasmer JNI as a dependency, write for instance:
dependencies {
implementation "org.wasmer:wasmer-jni-amd64-linux:0.3.0"
}Note: It is also possible to download the Java JAR file from the Github releases page! If you need to produce a JAR for your own platform and architecture, see the Development Section to learn more.
There is a toy program in java/src/test/resources/simple.rs, written
in Rust (or any other language that compiles to WebAssembly):
#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
x + y
}After compilation to WebAssembly, the
tests/resources/simple.wasm
binary file is generated. (Download
it).
Then, we can execute it in Java:
class Example {
public static void main(String[] args) {
// `simple.wasm` is located at `tests/resources/`.
Path wasmPath = Paths.get(new Example().getClass().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((Integer) results[0]); // 42
// Drops an instance object pointer which is stored in Rust.
instance.close();
}
}There is more examples in the examples/ directory. Run them with the
Makefile, such as: make run-example EXAMPLE=Simple to run the
SimpleExample example.
The root namespace is org.wasmer.
The Instance constructor compiles and instantiates a WebAssembly
module. It is built upon bytes. From here, it is possible to call
exported functions, or exported memories. For example:
// Instantiates the WebAssembly module.
Instance instance = new Instance(wasmBytes);
// Calls an exported function.
Object[] results = instance.exports.getFunction("sum").apply(1, 2);
// Casts an object to an integer object because the result is an object array.
int result = (Integer) results[0];
System.out.println(result); // 3
// Drops an instance object pointer manually. Note that the garbage collector
// will call this method before an object is removed from the memory.
instance.close();All exports, like functions or memories, are accessible on the
Instance.exports field, which is of kind Exports (a read-only
wrapper around a map of kind Map<String, exports.Export>). The
Exports.get method returns an object of type Export. To
downcast it to an exported function or to an exported memory, you can
use the respective getFunction or getMemory methods. The following
sections describe each exports in details.
An exported function is a native Java closure (represented by the
exports.Function class), where all arguments are automatically
casted to WebAssembly values if possible, and all results are of type
Object, which can be typed to Integer or Float for instance.
Function sum = instance.exports.getFunction("sum");
Object[] results = sum.apply(1, 2);
System.out.println((Integer) results[0]); // 3An exported memory is a regular Memory class.
Memory memory = instance.exports.getMemory("memory_1");See the Memory class section for more information.
The Module.validate static method checks whether a sequence of bytes
represents a valid WebAssembly module:
// Checks that given bytes represent a valid WebAssembly module.
boolean isValid = Module.validate(wasmBytes);The Module constructor compiles a sequence of bytes into a
WebAssembly module. From here, it is possible to instantiate it:
// Compiles the bytes into a WebAssembly module.
Module module = new Module(wasmBytes);
// Instantiates the WebAssembly module.
Instance instance = module.instantiate();The Module.serialize method and its complementary
Module.deserialize static method help to respectively serialize and
deserialize a compiled WebAssembly module, thus saving the compilation
time for the next use:
// Compiles the bytes into a WebAssembly module.
Module module1 = new Module(wasmBytes);
// Serializes the module.
byte[] serializedModule = module1.serialize();
// Let's forget about the module for this example.
module1 = null;
// Deserializes the module.
Module module2 = Module.deserialize(serializedModule);
// Instantiates and uses it.
Object[] results = module2.instantiate().exports.getFunction("sum").apply(1, 2);
System.out.println((Integer) results[0]); // 3A WebAssembly instance has a linear memory, represented by the
Memory class. Let's see how to read it. Consider the following Rust
program:
#[no_mangle]
pub extern fn return_hello() -> *const u8 {
b"Hello, World!\0".as_ptr()
}The return_hello function returns a pointer to a string. This string
is stored in the WebAssembly memory. Let's read it.
Instance instance = new Instance(wasmBytes);
// Gets the memory by specifying its exported name.
Memory memory = instance.exports.getMemory("memory");
// Gets the pointer value as an integer.
int pointer = (Integer) instance.exports.getFunction("return_hello").apply()[0];
// Reads the data from the memory.
ByteBuffer memoryBuffer = memory.buffer();
byte[] stringBytes = new byte[13];
memoryBuffer.position(pointer);
memoryBuffer.get(stringBytes);
System.out.println(new String(stringBytes)); // Hello, World!
instance.close();The Memory.grow methods allows to grow the memory by a number of pages (of 64KiB each).
// Grows the memory by the specified number of pages, and returns the number of old pages.
int oldPageSize = memory.grow(1);The Wasmer JNI library is based on the Wasmer runtime, which is written in Rust, and is compiled to a shared library. For your convenience, we produce one JAR (Java Archive) per architecture and platform. By now, the following are supported, consistently tested, and pre-packaged:
amd64-darwin,amd64-linux,amd64-windows.
More architectures and more platforms will be added in a close future. If you need a specific one, feel free to ask!
If you want to build the extension you will need the following tools:
- Gradle, a package management tool,
- Rust, the Rust programming language,
- Java, because it's a Java project ;-).
$ git clone https://github.com/wasmerio/wasmer-java/
$ cd wasmer-javaTo build the entire project, run the following command:
$ make buildTo build the JAR package:
$ make packageThis will generate the file build/libs/wasmer-jni-$(architecture)-$(os)-0.3.0.jar.
It is possible to infer the archive appendix automatically, see how.
According the Gradle Jar
API,
the $(architecture)-$(os) part is called the archive prefix. To
infer that appendix automatically to configure your dependencies, you
can use the following inferWasmerJarAppendix function:
String inferWasmerJarAppendix() {
def nativePlatform = new org.gradle.nativeplatform.platform.internal.DefaultNativePlatform("current")
def arch = nativePlatform.architecture
def os = nativePlatform.operatingSystem
def arch_name
switch (arch.getName()) {
case ["x86_64", "x64", "x86-64"]:
arch_name = "amd64"
break;
default:
throw new RuntimeException("`wasmer-jni` has no pre-compiled archive for the architecture " + arch.getName())
}
def os_name
if (os.isMacOsX()) {
os_name = "darwin"
} else if (os.isLinux()) {
os_name = "linux"
} else if (os.isWindows()) {
os_name = "windows"
} else {
throw new RuntimeException("`wasmer-jni` has no pre-compiled archive for the platform " + os.getName())
}
return arch_name + "-" + os_name
}Finally, you can configure your dependencies such as:
dependencies {
implementation "org.wasmer:wasmer-jni-" + inferWasmerJarAppendix() + ":0.3.0"
}Run the following command:
$ make testNote: Testing automatically builds the project.
Run the following command:
$ make javadocThen open build/docs/javadoc/index.html.
Quoting the WebAssembly site:
WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable target for compilation of high-level languages like C/C++/Rust, enabling deployment on the web for client and server applications.
About speed:
WebAssembly aims to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms.
About safety:
WebAssembly describes a memory-safe, sandboxed execution environment […].
The entire project is under the MIT License. Please read the
LICENSE file.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent