Skip to content

Getting Started

Jump to bottom
Volker Berlin edited this page May 9, 2022 · 11 revisions

Getting Started with JWebAssembly

Requirements

You does not need to install or compile JWebAssembly. You use your preferred Java IDE like Eclipse, Idea or Netbeans with Gradle support. Read the documentation of your IDE how you enable Gradle support in your IDE. Maven support will follow in the future.

Create a new project with your IDE in your preferred JVM language like Java, Kotlin, Groovy, etc. In the current alpha stage only Java 8 is tested and supported.

Add Dependency to API

A special API is required to access the browser DOM and the API. To use this API, you need to add the references of the JWebAssembly API library to your Java project in your IDE. Alternatively, you can also download the library directly from the repository.

Latest release: de.inetsoftware:jwebassembly-api:+

Or Snapshot: com.github.i-net-software:jwebassembly-api:master-SNAPSHOT

For Gradle this can look like:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' } // for snapshot of the API
}
dependencies {
    compile 'com.github.i-net-software:jwebassembly-api:master-SNAPSHOT'
}

For Maven this can look like:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
<dependency>
    <groupId>com.github.i-net-software</groupId>
    <artifactId>jwebassembly-api</artifactId>
    <version>master-SNAPSHOT</version>
</dependency>

Tip: Until a stable version is available the snapshot version is the better choice.

Content of the API

The library jwebassembly-api contains:

  • some important annotations. We will see it use later.
  • Replacements for native Java methods.
  • API to access the DOM.

You can also write or use an alternative API. The compiler is independent of the API.

First Class (Hello World)

Create a first class and a first method with your IDE in your project and add the annotation @Export. The annotation mark this method as callable from JavaScript. You can use any method name for this first method. But it name will be used in JavaScript. The class name and package unimportant.

@Export
public static void main() {
    Document document = Window.document();
    HTMLElement div = document.createElement("div");
    Text text = document.createTextNode("Hello World, this text come from WebAssembly."); 
    div.appendChild( text );
    document.body().appendChild( div );
}

If your browser support it then you can see the running Hello World sample. The complete sample source code can you see in the github repository.

Compiler Output (Hello World)

If you have build the hello world sample with your build system (Build with Gradle) then you see that the compiler has create the follow files:

File Meaning
HelloWorld.java The java source file. After compiling only needed for debugging in the browser.
HelloWorld.wasm The WebAssembly file created from compiler.
HelloWorld.wasm.js The JavaScript API that the WebAssembly code is importing. Also created from compiler.
HelloWorld.wasm.map Optional source map file, only needed for debugging. Created if debugNames is true.
HelloWorld.html The main file to load the WebAssembly file. Currently it is not possible to load an assembly file directly.

HTML template

To run the *.wasm file in the browser we need a simple HTML page. A minimum page can look like:

<!DOCTYPE html>
<html>
  <head>
    <script src="HelloWorld.wasm.js"></script>
  </head>
<body>
  <script>
    WebAssembly.instantiateStreaming(fetch('HelloWorld.wasm'), wasmImports)
      .then(obj => {
        wasmImports.instance = obj.instance;
        obj.instance.exports.main();
      })
      .catch(err => document.write(err));
  </script>
</body>
</html>

In the head we see that the generated JavaScript is loaded. It declare the variable wasmImports. The name is ever the same in the generated script. Of course you can also inline the script. We load it for simplicity.

Later the file HelloWorld.wasm is loaded asynchronously and it create an instance of an WebAssembly module. Then it call the exported method main. The name of the method must be the name of one exported method (annotation @Export). If you have declared a method with parameters, you can also pass parameters here.

The template can contains any HTML elements or you create all via Java/WebAssembly code.

Clone this wiki locally