The annotation processor generates host functions from annotated Java methods, and typed Java bindings from a Wasm module, so you do not write the `HostFunction` boilerplate by hand.

## Setup

Add the annotations dependency:

```xml
<dependency>
  <groupId>run.endive</groupId>
  <artifactId>annotations</artifactId>
  <version>${endive.version}</version>
</dependency>
```

and register `annotations-processor` as an annotation processor of the Java compiler, with Maven:

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>run.endive</groupId>
        <artifactId>annotations-processor</artifactId>
        <version>${endive.version}</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>
```

## Host modules

Annotate the methods of a class and the processor generates one host function per method:

```java
@HostModule("demo")
public final class Demo {
    private final Random random = new Random();

    @WasmExport
    public long add(int a, int b) {
        return a + b;
    }

    @WasmExport // the Wasm name is random_get
    public void randomGet(Memory memory, int ptr, int len) {
        byte[] data = new byte[len];
        random.nextBytes(data);
        memory.write(ptr, data);
    }

    public HostFunction[] toHostFunctions() {
        return Demo_ModuleFactory.toHostFunctions(this);
    }
}
```

The `@HostModule` annotation marks the class as a host module and specifies the module name for
all the host functions. The `@WasmExport` annotation marks a method as host function and optionally
specifies the name of the function. If the name is not specified, then the Java method name is
converted from camel case to snake case, as is a common convention in Wasm.

The `Demo_ModuleFactory` class in `toHostFunctions()` is generated by the annotation processor.

Host functions must be instance methods of the class. Static methods are not supported.
This is because host functions will typically interact with instance state in the host class.

To use the host module, you need to instantiate the host module and fetch the host functions:

```java
import run.endive.runtime.ImportValues;

var demo = new Demo();
var imports = ImportValues.builder().addFunction(demo.toHostFunctions()).build();
```

### Type conversions

Parameters and return values are converted as follows:

| Java type | Wasm type |
|-----------|-----------|
| `int`     | `i32`     |
| `long`    | `i64`     |
| `float`   | `f32`     |
| `double`  | `f64`     |

Parameters can also be a `String` annotated with `@Buffer` (passed as an `i32` pointer and an `i32` length) or `@CString` (an `i32` pointer to a NUL-terminated string), both read from the module's memory, and `Instance` or `Memory`, which receive the calling instance or its memory without a Wasm parameter.

## WasmModuleInterface

:::tip
If you are using the [build-time compiler](../execution/build-time-compiler.md), you can use the `moduleInterface` parameter in the Maven plugin instead of the annotation processor. This is simpler and avoids the setup described below. See [Generating Module Exports and Imports](../execution/build-time-compiler.md#generating-module-exports-and-imports).
:::

If you already have a Wasm module and want to generate scaffolded Java code to interact with it, you can use the `@WasmModuleInterface` annotation.

```java
@WasmModuleInterface("demo.wasm")
public final class Demo {}
```

The annotation accepts a single argument, which can be either:

- The location of the Wasm module on the current classpath (transitive references are not supported).
- An absolute URI pointing to the Wasm module, in the form of `file://....`

This annotation generates several things, depending on the provided module:

- `ModuleExports`: Represents the Wasm module's exported functions, mapped to typed Java parameters and return values.
- `ModuleImports`: Represents the module's imported host functions and includes a convenient `toImportValues()` method to obtain ImportValues after implementing the interfaces.

You can find examples of how to use the generated code in the [`annotations/it` folder of the repository](https://github.com/bytecodealliance/endive/tree/main/annotations/it).
