- Notifications
You must be signed in to change notification settings - Fork8
Extism Java Host SDK enables Java programs to embed and run WebAssembly plugins.
License
extism/java-sdk
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Java SDK for theExtism WebAssembly Plugin-System.
For this library, you first need to install the Extism Runtime. You candownload the shared object directly from a release or use theExtism CLI to install it:
sudo extism lib install latest#=> Fetching https://github.com/extism/extism/releases/download/v0.5.2/libextism-aarch64-apple-darwin-v0.5.2.tar.gz#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib#=> Copying extism.h to /usr/local/include/extism.h
To use the Extism java-sdk you need to add theorg.extism.sdk dependency to your dependency management system.
To use the Extism java-sdk with maven you need to add the following dependency to yourpom.xml file:
<dependency> <groupId>org.extism.sdk</groupId> <artifactId>extism</artifactId> <version>1.1.0</version></dependency>
To use the Extism java-sdk with maven you need to add the following dependency to yourbuild.gradle file:
implementation 'org.extism.sdk:extism:1.1.0'This guide should walk you through some of the concepts in Extism and this java library.
The primary concept in Extism is theplug-in. You can think of a plug-in as a code module stored in a.wasm file.Since you may not have an Extism plug-in on hand to test, let's load a demo plug-in from the web:
importorg.extism.sdk.manifest.Manifest;importorg.extism.sdk.wasm.UrlWasmSource;importorg.extism.sdk.Plugin;varurl ="https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm";varmanifest =newManifest(List.of(UrlWasmSource.fromUrl(url)));varplugin =newPlugin(manifest,false,null);
Note: Seethe Manifest docs as it has a rich schema and a lot of options.
This plug-in was written in Rust and it does one thing, it counts vowels in a string. As such, it exposes one "export" function:count_vowels. We can call exports usingPlugin#call
varoutput =plugin.call("count_vowels","Hello, World!");System.out.println(output);// => "{"count": 3, "total": 3, "vowels": "aeiouAEIOU"}"
All exports have a simple interface of bytes-in and bytes-out.This plug-in happens to take a string and return a JSON encoded string with a report of results.
Plug-ins may be stateful or stateless. Plug-ins can maintain state b/w calls by the use of variables.Our count vowels plug-in remembers the total number of vowels it's ever counted in the "total" key in the result.You can see this by making subsequent calls to the export:
varoutput =plugin.call("count_vowels","Hello, World!");System.out.println(output);// => "{"count": 3, "total": 6, "vowels": "aeiouAEIOU"}"varoutput =plugin.call("count_vowels","Hello, World!");System.out.println(output);// => "{"count": 3, "total": 9, "vowels": "aeiouAEIOU"}"
These variables will persist until this plug-in is freed or you initialize a new one.
Plug-ins may optionally take a configuration object. This is a static way to configure the plug-in.Our count-vowels plugin takes an optional configuration to change out which characters are considered vowels. Example:
varplugin =newPlugin(manifest,false,null);varoutput =plugin.call("count_vowels","Yellow, World!");System.out.println(output);// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}// Let's change the vowels config it uses to determine what is a vowel:varconfig =Map.of("vowels","aeiouyAEIOUY");varmanifest2 =newManifest(List.of(UrlWasmSource.fromUrl(url)),null,config);varplugin =newPlugin(manifest2,false,null);varoutput =plugin.call("count_vowels","Yellow, World!");System.out.println(output);// => {"count": 4, "total": 4, "vowels": "aeiouyAEIOUY"}// ^ note count changed to 4 as we configured Y as a vowel this time
Let's extend our count-vowels example a little bit: Instead of storing thetotal in an ephemeral plug-in var,let's store it in a persistent key-value store!
Wasm can't use our app's KV store on its own. This is whereHost Functions come in.
Host functions allow us to grant new capabilities to our plug-ins from our application.They are simply some java methods you write which can be passed down and invoked from any language inside the plug-in.
Let's load the manifest like usual but load up thiscount_vowels_kvstore plug-in:
varurl ="https://github.com/extism/plugins/releases/latest/download/count_vowels_kvstore.wasm";varmanifest =newManifest(List.of(UrlWasmSource.fromUrl(url)));varplugin =newPlugin(manifest,false,null);
Note: The source code for this plug-in ishereand is written in rust, but it could be written in any of our PDK languages.
Unlike our previous plug-in, this plug-in expects you to provide host functions that satisfy its import interface for a KV store.We want to expose two functions to our plugin,kv_write(String key, Bytes value) which writes a bytes value to a key andBytes kv_read(String key) which reads the bytes at the givenkey.
// Our application KV store// Pretend this is redis or a database :)varkvStore =newHashMap<String,byte[]>();ExtismFunctionkvWrite = (plugin,params,returns,data) -> {System.out.println("Hello from kv_write Java Function!");varkey =plugin.inputString(params[0]);varvalue =plugin.inputBytes(params[1]);System.out.println("Writing to key " +key);kvStore.put(key,value);};ExtismFunctionkvRead = (plugin,params,returns,data) -> {System.out.println("Hello from kv_read Java Function!");varkey =plugin.inputString(params[0]);System.out.println("Reading from key " +key);varvalue =kvStore.get(key);if (value ==null) {// default to zeroed bytesvarzero =newbyte[]{0,0,0,0};plugin.returnBytes(returns[0],zero); }else {plugin.returnBytes(returns[0],value); }};HostFunctionkvWriteHostFn =newHostFunction<>("kv_write",newLibExtism.ExtismValType[]{LibExtism.ExtismValType.I64,LibExtism.ExtismValType.I64},newLibExtism.ExtismValType[0],kvWrite,Optional.empty());HostFunctionkvReadHostFn =newHostFunction<>("kv_read",newLibExtism.ExtismValType[]{LibExtism.ExtismValType.I64},newLibExtism.ExtismValType[]{LibExtism.ExtismValType.I64},kvRead,Optional.empty());
Note: In order to write host functions you should get familiar with the methods on theExtismCurrentPlugin class.The
pluginparameter is an instance of this class.
Now we just need to pass in these function references when creating the plugin:.
HostFunction[]functions = {kvWriteHostFn,kvReadHostFn};varplugin =newPlugin(manifest,false,functions);varoutput =plugin.call("count_vowels","Hello, World!");// => Hello from kv_read Java Function!// => Reading from key count-vowels// => Hello from kv_write Java Function!// => Writing to key count-vowelsSystem.out.println(output);// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
To build the Extism java-sdk run the following command:
mvn clean verifyAbout
Extism Java Host SDK enables Java programs to embed and run WebAssembly plugins.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors6
Uh oh!
There was an error while loading.Please reload this page.