avaje / avaje-nima

Convenience library for using Avaje with Helidon SE

avaje-nima

Convenience Library to make using the various avaje libraries with helidon easier.

Along with Helidon SE, It transitively brings in the following avaje libraries:

• config
• http-api
• http-client
• inject
• jsonb
• validator

The generator module transitively brings in the following avaje services and annotation processors (which will not be included into your final jar):

• http-client-generator
• http-helidon-generator
• inject-generator
• jsonb-generator
• record-builder
• spi-service
• validator-generator

How to use

Step 1 - Add dependencies

Add the avaje-nima dependency.

<dependency>
    <groupId>io.avaje</groupId>
    <artifactId>avaje-nima</artifactId>
    <version>${version}</version>
</dependency>

Add the avaje-nima-test as a test dependency. This is to support testing the application by starting the web server on a random port for tests.

<dependency>
    <groupId>io.avaje</groupId>
    <artifactId>avaje-nima-test</artifactId>
    <version>${version}</version>
    <scope>test</scope>
</dependency>

And add avaje-nima-generator as an annotation processor. This will transitively include all the avaje processors.

<dependency>
    <groupId>io.avaje</groupId>
    <artifactId>avaje-nima-generator</artifactId>
    <version>${version}</version>
    <optional>true</optional>
    <scope>provided</scop>
</dependency>

JDK 22+

In JDK 22+, annotation processors are disabled by default, you will need to add a flag in maven to re-enable.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <compilerArgument>-proc:full</compilerArgument>
  </configuration>
</plugin>

Step 2 - Create a controller

import io.avaje.http.api.*;

@Controller
@Path("/")
class HelloController {

    @Produces("text/plain")
    @Get
    String hello() {
        return "hello world";
    }
}

On compilation, a HelloController$Route will be generated into generated-sources. This will have Helidon SE adapter code for the HelloController registering the path and handling the request and response.

On compilation, a HelloController$DI and HelloController$Route$DI will be generated to handle dependency injection for the controller and the route adapter.

Step 3 - Use the Nima Class to start the application

The Nima class will start a BeanScope, register generated controller routes, and start the helidon webserver.

The Nima class will search your BeanScope for a WebServerConfig.Builder, if you provide one in your BeanScope it will be used to configure the webserver.

  void main() {

    var webServer = Nima.builder()
      .port(8080)
      .build();

    webServer.start();
  }

Step 4 - Run and curl test

Run the application and use curl to test

curl localhost:8080

Step 5 - Create a unit test

Create a unit test that will start the application on a random port, and make a call to the controller method and assert the response is as expected.

package org.example;

import io.avaje.http.client.HttpClient;
import io.avaje.inject.test.InjectTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;

import java.net.http.HttpResponse;

import static org.assertj.core.api.Assertions.assertThat;

@InjectTest
class HelloTest {

    // Injecting a HttpClient into a test means the test plugin will
    // automatically start the application on a random port
    // and inject a client with a base url pointing to the server (and shutdown the webserver after
    // the test has completed).
    @Inject
    static HttpClient httpClient;

    @Test
    void hello() {
        HttpResponse<String> res = httpClient.request()
          .GET()
          .asString();

      assertThat(res.statusCode()).isEqualTo(200);
      assertThat(res.body()).isEqualTo("hello world");
    }

}

Module use

The io.avaje.nima module transitively includes:

• io.avaje.config
• io.avaje.http.api
• io.avaje.inject
• io.avaje.jsonb
• io.avaje.jsonb.plugin
• io.helidon.webserver

module nima.example {

  requires io.avaje.nima;

  requires io.avaje.http.client; //if using avaje http client
  requires io.avaje.validation.http; //if using avaje validator
  requires static io.avaje.recordbuilder; //if using avaje record builder
  requires static io.avaje.spi; //if using avaje services
}

avaje-nima's Issues

[nima-test] Overrides Scope HttpClient

It seems the HttpClient configured by the test plugin totally overrides any HttpClient created in the beanScope. Can we make this only injected into the test?

Allow access to constructed BeanScope

Currently, it seems there is no way to retrieve the constructed Beanscope after using the Nima builder.

`@Mock` doesn't work when using nima test

Got an actual problem this time, when using @Mock and injecting an Http Client the client is injected into the test class but the
mocked bean does not replace the one in the scope.

What if we made this an Inject Plugin?

And provide a default Nima instance via the enhanced PostContruct. Something like this:

public final class DefaultNimaProvider implements io.avaje.inject.spi.Plugin {

  @Override
  public Class<?>[] provides() {
    return new Class<?>[] {WebServer.class};
  }

  @Override
  public void apply(BeanScopeBuilder builder) {

    final var nima = Nima.builder();
    builder.addPostConstruct(nima::configure);
    builder.propertyPlugin().get("server.port").map(Integer::valueOf).ifPresent(nima::port);
    builder.provideDefault(null, WebServer.class, nima::build);
  }
}