Jooby Web Framework Documentation

Jooby is a modular, high-performance web framework for Java and Kotlin with the following key capabilities:

• Flexible Routing: Supports both a fluent Script/Lambda API and MVC annotations (via Jooby or JAX-RS).
• Execution Models: Choose between an Event Loop or worker threads.
• Reactive Support: Native support for reactive responses using CompletableFuture, RxJava, Reactor, Mutiny, and Kotlin Coroutines.
• Server Agnostic: Can run on Jetty, Netty, Vert.x, or Undertow.
• Modern Tooling: Includes OpenAPI 3 support, hot-reload for development, and Model Context Protocol (MCP) for AI/LLM integration.
• Observability: Native OpenTelemetry support for distributed tracing, metrics, and log correlation.
• Extensibility: Highly modular architecture via extensions and modules.

A Context object allows you to interact with the current HTTP request and manipulate the HTTP response. In most cases, you access the Context as a parameter within your route handlers.

It also provides derived information like matching locales based on the Accept-Language header. To use language matching, you must define the supported languages for your application via application.lang in your configuration or programmatically using setLocales.

get("/", ctx -> {
  /* do important stuff with the 'ctx' variable */
});

When running behind a load balancer or reverse proxy (such as Nginx, HAProxy, or an AWS ALB) that terminates SSL, the SSLHandler relies on the X-Forwarded-Proto header to identify the client's original protocol.

To ensure the handler correctly identifies the client's original host and protocol, you must enable the setTrustProxy(true) option in your Jooby configuration.

The jooby-grpc module intercepts requests natively before they reach the standard Jooby router.

• Missing Methods: If a client calls a gRPC method that does not exist, the request falls through to the standard Jooby router, returning a 404 Not Found (which gRPC clients translate to Status 12 UNIMPLEMENTED).
• Misconfiguration: If you attempt to run gRPC over HTTP/1.1 (instead of HTTP/2), the fallback route will catch the request and throw an IllegalStateException to help you identify the configuration error.

Attributes allow you to attach static metadata to a route during application bootstrap. These are accessible during the request/response cycle via the Context.

In MVC-style applications, runtime annotations are automatically converted into route attributes. If an annotation has a value() method, the annotation's name becomes the attribute key; otherwise, the method name is used.

// Setting an attribute manually
get("/foo", ctx -> "Foo")
  .setAttribute("foo", "bar");

// Accessing attributes in a filter/middleware
use(next -> ctx -> {
  String role = ctx.getRoute().getAttribute("Role");
  if (user.hasRole(role)) {
    return next.apply(ctx);
  }
  throw new StatusCodeException(StatusCode.FORBIDDEN);
});

Modules in Jooby are built-in Extensions that bootstrap and configure third-party libraries (such as Jackson, Hibernate, or HikariCP) using Jooby's Extension API.

Key characteristics:

• No Abstraction Layers: Unlike many frameworks, Jooby modules do not wrap the underlying library in custom classes. They do not create new layers of abstraction.
• Direct Access: Modules expose the raw library components directly to your application via the Service Registry. This allows you to use the library's native API exactly as intended by its original creators.
• Distributed Dependencies: Modules are provided as separate dependencies, allowing you to include only what your application needs.

Authorizers allow you to add custom logic to determine if a user is authorized for a specific path. You can register authorizers in three ways:

1. Manual configuration: Create a org.pac4j.core.config.Config object, add the authorizer to it, and pass the Config to the Pac4jModule constructor.
2. Automatic configuration: Pass an instance of the authorizer directly to the .client() method.
3. Registry/DI integration: Pass the authorizer class to the .client() method, allowing the application registry (Dependency Injection) to provision the instance.

// Registry/DI integration example
install(
      new Pac4jModule()
          .client("/api/*", MyTestAuthorizer.class, conf -> {...});
  );

The TransactionalRequest filter manages the lifecycle of an EntityManager or StatelessSession per HTTP request. It automatically handles creating, binding, beginning, committing, rolling back, and closing the session/transaction. This prevents boilerplate code in your route handlers.

Note: The transaction does not extend to the rendering phase (JSON, HTML, etc.). Ensure all required data is loaded in the handler to avoid LazyInitializationException during rendering.

import io.jooby.hikari.HikariModule;
import io.jooby.hibernate.HibernateModule;
import io.jooby.hibernate.TransactionalRequest;

{
  install(new HikariModule());
  install(new HibernateModule());
  use(new TransactionalRequest());

  post("/create", ctx -> {
    EntityManager em = require(EntityManager.class);
    MyEntity e = ...;
    em.persist(e);
    return e;
  });
}

The ServiceRegistry allows you to group multiple services of the same type using Lists, Sets, or Maps. To retrieve these collections, use the Reified type helper to ensure type safety during retrieval.

• Use listOf(Class) to add to a List.
• Use mapOf(KeyClass, ValueClass) to add to a Map.
• Use ctx.require(Reified.list(Class)) to retrieve the collection.

import io.jooby.Reified;
import java.util.List;

{
  // Add to a List
  getServices().listOf(Animal.class).add(new Cat());
  getServices().listOf(Animal.class).add(new Dog());

  // Add to a Map
  getServices().mapOf(String.class, Animal.class).put("cat", new Cat());

  get("/list", ctx -> {
    // Retrieve the List using the Reified type helper
    List<Animal> animals = ctx.require(Reified.list(Animal.class));
    return animals;
  });
}