Java Helidon

Java Helidon

Guide Helidon 4 code generation and review so SE and MP applications compile, keep business logic out of transport layers, use Java 21 idioms, bind data safely, and avoid common Helidon 3 API mistakes.

When to invoke

• "Write a Helidon 4 SE service."
• "Review this Helidon MP resource."
• "Fix Helidon DB Client code that does not compile."
• "Add Helidon tests without hardcoding a port."
• "Migrate Helidon 3 APIs to Helidon 4."

Helidon 3 to 4 API changes

Check generated code against this table before returning it. The left column commonly appears in older examples and does not compile or is wrong for Helidon 4.

Value.as(Class) returns OptionalValue<T>, not T; DbColumn.as(String.class) returns OptionalValue<String>, not String. This is the most common generated-code compile error in high-quality Helidon 4 work.

Migration tokens to verify explicitly: DbColumn.as(String.class), OptionalValue<String>, String.

Project setup and programming model

Use the project's secret-management system for production credentials.

Helidon SE patterns

SE route shape:

import io.helidon.http.Status;
import io.helidon.webserver.http.HttpRules;
import io.helidon.webserver.http.HttpService;
import io.helidon.webserver.http.ServerRequest;
import io.helidon.webserver.http.ServerResponse;

public final class CustomerHttpService implements HttpService {
    private final CustomerService customerService;

    public CustomerHttpService(CustomerService customerService) {
        this.customerService = customerService;
    }

    @Override
    public void routing(HttpRules rules) {
        rules.get("/{id}", this::findById);
    }

    private void findById(ServerRequest request, ServerResponse response) {
        var id = request.path().pathParameters().get("id");
        customerService.findById(id)
                .ifPresentOrElse(response::send, () -> response.status(Status.NOT_FOUND_404).send());
    }
}

Register with WebServer.builder().routing(routing -> routing.register("/customers", customerHttpService)).build().start();.

Helidon MP patterns

MP resource shape:

import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/customers")
@RequestScoped
@Produces(MediaType.APPLICATION_JSON)
public class CustomerResource {
    private final CustomerService customerService;

    protected CustomerResource() { this.customerService = null; }

    @Inject
    public CustomerResource(CustomerService customerService) { this.customerService = customerService; }

    @GET
    @Path("/{id}")
    public Response findById(@PathParam("id") String id) {
        return customerService.findById(id)
                .map(customer -> Response.ok(customer).build())
                .orElseGet(() -> Response.status(Response.Status.NOT_FOUND).build());
    }
}

Web and service layer rules

A service can throw IllegalArgumentException for blank IDs or invalid CreateCustomerRequest data, map CustomerEntity to Customer.fromEntity, and use @Transactional on methods that change persistent state.

Data layer rules

Helidon DB Client repository shape:

import io.helidon.dbclient.DbClient;

public final class DbCustomerRepository implements CustomerRepository {
    private static final String FIND_BY_ID = "SELECT id, name FROM customers WHERE id = :id";
    private static final String INSERT = "INSERT INTO customers (id, name) VALUES (:id, :name)";
    private final DbClient dbClient;

    public Optional<Customer> findById(String id) {
        return dbClient.execute()
                .createGet(FIND_BY_ID)
                .addParam("id", id)
                .execute()
                .map(row -> new Customer(row.column("id").getString(), row.column("name").getString()));
    }
}

For Helidon MP persistence, keep JpaCustomerRepository CDI-managed, inject EntityManager with @PersistenceContext, and return entities only inside the data layer.

Named statements may live in config:

db:
  source: "jdbc"
  connection:
    url: "jdbc:postgresql://localhost:5432/customers"
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  statements:
    find-customer-by-id: >
      SELECT id, name
      FROM customers
      WHERE id = :id

Reference named SQL with createNamedGet("find-customer-by-id") and bound parameters.

Observability, logging, testing, and security

Gotchas

• Value.as(Class) is not a direct value: unwrap OptionalValue<T> or use typed accessors.
• Helidon 4 is not the old reactive API: avoid Single, Multi, and CompletionStage patterns copied from Helidon 3.
• CDI proxy construction matters: normal-scoped MP beans with constructor injection need a non-private no-argument constructor.
• Testing ports must be dynamic: @ServerTest, @RoutingTest, and @HelidonTest manage server lifecycle; do not hardcode ports.

Output template

## Helidon result

**Status:** complete | needs changes | blocked
**Programming model:** SE | MP
**Files reviewed or generated:** <paths>

### Findings or changes
| Area | Evidence | Action |
| --- | --- | --- |
| API migration | `<old API>` | `<Helidon 4 replacement>` |
| Web layer | `<route/resource evidence>` | `<fix>` |
| Data layer | `<query or mapper evidence>` | `<fix>` |
| Tests | `<test evidence>` | `<fix>` |

### Validation
- Compile check: pass | fail | not run
- Tests: pass | fail | not run

Quality gate

• The output identifies Helidon SE or Helidon MP and does not mix models accidentally.
• No Helidon 3 APIs from the migration table remain in generated code.
• Java 21, aligned Helidon dependencies, and existing pom.xml or build.gradle conventions are respected.
• Route/resource classes validate inputs, return correct HTTP statuses, and delegate business logic.
• SQL uses bound parameters and safe typed accessors; nullable columns use optional-aware reads.
• Entities are separated from API DTOs or records.
• Configuration and secrets are externalized through application.yaml, application.properties, environment, or secret management.
• Tests use the correct Helidon testing artifact and dynamic server ports.
• Security, logging, metrics, CORS, OIDC, and TLS guidance is applied where relevant.