GeezerVison

import io.jooby.Jooby;

public class App extends Jooby {
  {
    get("/", ctx -> "Hello Jooby!");
  }

  public static void main(String[] args) {
    runApp(args, App::new);
  }
}

import io.jooby.kt.Kooby
import io.jooby.kt.runApp

class App : Kooby({
  get("/") { "Hello Jooby!" }
})

fun main(args: Array<String>) {
  runApp(args, ::App)
}

import io.jooby.Jooby;

public class App {
  public static void main(String[] args) {
    Jooby.runApp(args, app -> {
      app.get("/", ctx -> "Hello Jooby!");
    });
  }
}

import io.jooby.kt.runApp

fun main(args: Array<String>) {
  runApp(args) {
    get("/") { "Hello Jooby!" }
  }
}

import io.jooby.annotation.*;

public class MyController {
  @GET
  public String sayHi() {
    return "Hello Jooby!";
  }
}

public class App {
  public static void main(String[] args) {
    Jooby.runApp(args, app -> {
      app.use(new MyController_());
    });
  }
}

import io.jooby.annotation.*

class MyController {
  @GET
  fun sayHi(): String {
    return "Hello Jooby!"
  }
}

fun main(args: Array<String>) {
  runApp(args) {
    use(MyController_())
  }
}

jooby set -w ~/Source

jooby> help create
Usage: jooby create [-dgikms] [--server=<server>] <name>
Creates a new application
      <name>              Application name or coordinates (groupId:artifactId:version)
  -d, --docker            Generates a Dockerfile
  -g, --gradle            Generates a Gradle project
  -i                      Start interactive mode
  -k, --kotlin            Generates a Kotlin application
  -m, --mvc               Generates an MVC application
  -s, --stork             Add Stork Maven plugin to build (Maven only)
      --server=<server>   Choose a server: jetty, netty, or undertow

jooby> create myapp

jooby> create myapp --kotlin

jooby> create myapp --gradle
jooby> create myapp --gradle --kotlin

jooby> create myapp --mvc

jooby> create myapp --server undertow

jooby> create myapp --docker --stork

jooby> create myapp -i

{
  get("/", ctx -> "Snippet");
}

{
  get("/") { "Snippet" }
}

{
 // (1) (2)
  get("/foo", ctx -> {
    return "foo"; // (3)
  });

  // Get example with path variable
  get("/foo/{id}", ctx -> {
    return ctx.path("id").value();
  });

  // Post example
  post("/", ctx -> {
    return ctx.body().value();
  });
}

{
 // (1) (2)
  get("/foo") {
    "foo" // (3)
  }

  // Get example with path variable
  get("/foo/{id}") {
    ctx.path("id").value()
  }

  // Post example
  post("/") {
    ctx.body().value()
  }
}

Attributes allow you to annotate a route at application bootstrap time. They function as static metadata available at runtime:

An attribute consists of a name and a value. Values can be any object. Attributes can be accessed during the request/response cycle. For example, a security module might check for a role attribute.

In MVC routes, you can set attributes via annotations:

The previous example prints admin. You can retrieve all attributes of a route by calling ctx.getRoute().getAttributes().

Any runtime annotation is automatically added as a route attribute following these rules:

• If the annotation has a value method, the annotation’s name becomes the attribute name.

• Otherwise, the method name is used as the attribute name.

1. Defines a path variable id.

2. Retrieves the variable id as an int.

1. Defines two path variables: file and ext.

2. Retrieves the string variable file.

3. Retrieves the string variable ext.

1. Defines an optional path variable id. The trailing ? makes it optional.

2. Retrieves the variable id as a String if present, or uses the default value: self.

The trailing ? makes the path variable optional. The route matches both:

• /profile

• /profile/eespina

1. Defines a path variable id. The regex expression is everything after the first : (e.g., [0-9]+).

2. Retrieves the int value.

The optional syntax is also supported for regex path variables (e.g., /user/{id:[0-9]+}?). This matches:

• /user

• /user/123

1. The trailing * defines a catchall pattern.

2. We access the catchall value using the * character.

3. In this example, we named the catchall pattern and access it using the path variable name.

{
  get("/user/{id}", ctx -> ctx.path("id").value());  // (1)

  get("/user/me", ctx -> "my profile");              // (2)

  get("/users", ctx -> "users");                     // (3)

  get("/users", ctx -> "new users");                 // (4)
}

{
  get("/user/{id}") { ctx.path("id").value() }  // (1)

  get("/user/me") { "my profile" }              // (2)

  get("/users") { "users" }                     // (3)

  get("/users") { "new users" }                 // (4)
}

Cross-cutting concerns such as response modification, verification, security, and tracing are available via Route.Filter.

A filter takes the next handler in the pipeline and produces a new handler:

1. Saves the start time.

2. Proceeds with execution (the pipeline).

3. Computes and prints latency.

4. Returns a response.

The before filter runs before a handler.

A before filter takes a context as an argument and does not produce a response. It is expected to operate via side effects (usually modifying the HTTP request/response).

The after filter runs after a handler.

An after filter takes three arguments. The first is the HTTP context, the second is the result from a functional handler (or null for a side-effect handler), and the third is any exception generated by the handler.

It is expected to operate via side effects, usually modifying the HTTP response (if possible) or cleaning up/tracing execution.

1. Prints Jooby.

2. Adds a response header (modifies the HTTP response).

If the target handler is a functional handler, modifying the HTTP response is allowed.

For side-effect handlers, the after filter is invoked with a null result and is not allowed to modify the HTTP response.

1. Prints null (no value).

2. Produces an error/exception.

An exception occurs here because the response was already started, and it is impossible to alter it. Side-effect handlers are those that use the send methods, responseOutputStream, or responseWriter.

You can check whether you can modify the response by checking the state of isResponseStarted():

The next examples demonstrate some use cases for dealing with errored responses. Keep in mind that an after handler is not a mechanism for handling and reporting exceptions; that is the task of an Error Handler.

Here, the exception is still propagated, giving the Error Handler a chance to jump in.

1. Recovers and produces an alternative output.

Here, the exception won’t be propagated because we produce a response, meaning the error handler will not execute.

If the after handler produces a new exception, that exception will be added to the original exception as a suppressed exception.

1. Will be OriginalException.

2. Will be AnotherException.

The complete listener runs at the completion of a request/response cycle (i.e., when the request has been completely read and the response fully written).

At this point, it is too late to modify the exchange. They are attached to a running context (unlike before/after filters).

1. Attaches a completion listener.

2. Runs after the response has been fully written.

Completion listeners are invoked in reverse order.

{
  // Increment +1
  use(next -> ctx -> {
    Number n = (Number) next.apply(ctx);
    return 1 + n.intValue();
  });

  // Increment +1
  use(next -> ctx -> {
    Number n = (Number) next.apply(ctx);
    return 1 + n.intValue();
  });

  get("/1", ctx -> 1); // (1)

  get("/2", ctx -> 2); // (2)
}

{
  // Increment +1
  use {
    val n = next.apply(ctx) as Int
    1 + n
  }

  // Increment +1
  use {
    val n = next.apply(ctx) as Int
    1 + n
  }

  get("/1") { 1 } // (1)

  get("/2") { 2 } // (2)
}

{
  // Increment +1
  var increment = use(next -> ctx -> {
    Number n = (Number) next.apply(ctx);
    return 1 + n.intValue();
  });

  Handler one = ctx -> 1;

  Handler two = ctx -> 2;

  Handler handler1 = increment.then(increment).then(one);
  Handler handler2 = increment.then(increment).then(two);

  get("/1", handler1);

  get("/2", handler2);
}

Order follows a what you see is what you get approach. Routes are stacked in the order they are defined.

Output:

1. /1 ⇒ 2

2. /2 ⇒ 4

The routes(Runnable) and path(String,Runnable) operators group one or more routes.

A scoped filter looks like this:

Output:

1. Introduces a new scope via the routes operator.

2. /4 ⇒ 9

3. /1 ⇒ 2

It functions as a normal filter inside a group operator.

{
  routes(() -> {
    get("/", ctx -> "Hello");
  });
}

{
  routes {
    get("/") {
      "Hello"
    }
  }
}

{
   path("/api/user", () -> {    // (1)
     get("/{id}", ctx -> ...);  // (2)
     get("/", ctx -> ...);      // (3)
     post("/", ctx -> ...);     // (4)
     // ...
   });
}

{
   path("/api/user") {     // (1)
     get("/{id}") { ...}   // (2)
     get("/") { ...}       // (3)
     post("/") { ...}      // (4)
     // ...
   });
}

Composition is a technique for building modular applications. You can compose one or more routers into a new one using the mount(Router) operator:

1. Imports all routes from Foo. Output: /foo ⇒ /foo

2. Imports all routes from Bar. Output: /bar ⇒ /bar

3. Adds more routes. Output: /app ⇒ /app

1. Now all routes from Foo will be prefixed with /prefix. Output: /prefix/foo ⇒ /prefix/foo

The mount operator only imports routes. Services and callbacks are not imported. The main application is responsible for assembling all resources and services required by the imported applications.

Alternatively, you can install a standalone application into another one using the install(Supplier) operator:

1. Imports all routes, services, callbacks, etc. from Foo. Output: /foo ⇒ /foo

2. Imports all routes, services, callbacks, etc. from Bar. Output: /bar ⇒ /bar

This operator lets you, for example, deploy Foo as a standalone application or integrate it into a main application.

The install operator shares the state of the main application, so lazy initialization (and therefore instantiation) of any child applications is mandatory.

For example, this won’t work:

The Foo application must be lazily initialized:

public class V1 extends Jooby {
  {
    get("/api", ctx -> "v1");
  }
}

public class V2 extends Jooby {
  {
    get("/api", ctx -> "v2");
  }
}

public class App extends Jooby {
  {
    mount(ctx -> ctx.header("version").value().equals("v1"), new V1()); // (1)
    mount(ctx -> ctx.header("version").value().equals("v2"), new V2()); // (2)
  }
}

class V1: Kooby({
  get("/api") { "v1" }
})

class V2: Kooby({
  get("/api") { "v2" }
})

class App: Kooby({
  mount(ctx -> ctx.header("version").value().equals("v1"), V1()); // (1)
  mount(ctx -> ctx.header("version").value().equals("v2"), V2()); // (2)
})

public class Foo extends Jooby {
  {
    setContextPath("/foo");
    get("/hello", ctx -> ...);
  }
}

public class Bar extends Jooby {
  {
    setContextPath("/bar");
    get("/hello", ctx -> ...);
  }
}

import static io.jooby.Jooby.runApp;

public class MultiApp {
  public static void main(String[] args) {
    runApp(args, List.of(Foo::new, Bar::new));
  }
}

import io.jooby.kt.Kooby.runApp

fun main(args: Array<String>) {
  runApp(args, ::Foo, ::Bar)
}

The setRouterOptions(RouterOptions) method controls routing behavior.

The setHiddenMethod(String) option allows clients to override the HTTP method. This is especially useful for HTML forms, which natively only support GET and POST.

1. Configures the router to look for a form field named _method.

2. Executes the PUT handler for /form instead of the standard POST.

(Note: I fixed a small bug in your Kotlin snippet where you were using Java lambda syntax inside the put route).

The default implementation looks for the specified hidden field in POST forms or multipart requests. Alternatively, you can provide a custom strategy, such as reading an HTTP header:

1. Overrides the HTTP method by extracting it from the X-HTTP-Method-Override request header.

HTTP headers allow the client and server to pass additional information.

1. Retrieves the header token.

2. Retrieves all headers as a Value.

3. Retrieves all headers as a Map.

Request cookies are sent to the server via the Cookie header. Jooby provides simple key/value access:

1. Retrieves the cookie named token.

2. Retrieves all cookies as a Map.

Path parameters are part of the URI. Use the {identifier} notation to define a path variable.

1. Standard path variable id.

2. Path variable id prefixed with @.

3. Multiple variables: name and ext.

4. Unnamed catchall path variable.

5. Path variable strictly matching a regular expression.

1. Access the raw path string (e.g., /a b returns /a%20b).

2. Path as a Value object (decoded).

3. Path as a Map<String, String> (decoded).

4. Specific path variable name as a String (decoded).

The query string is the part of the URI that starts after the ? character.

1. Access the raw query string (e.g., ?q=a%20b).

2. Query string as a QueryString object (e.g., {q=a b}).

3. Query string as a multi-value map (e.g., {q=[a b]}).

4. Access decoded variable q. Throws a 400 Bad Request if missing.

5. Binds the query string directly to a SearchQuery object.

Form data is sent in the HTTP body (or as part of the URI for GET requests) and is encoded as application/x-www-form-urlencoded.

1. Form as Formdata.

2. Form as a multi-value map.

3. Specific form variable id.

4. Specific form variable pass.

5. Form automatically bound to a User object.

Multipart data is sent in the HTTP body and encoded as multipart/form-data. It is required for file uploads.

1. Form as Multipart.

2. Form as a multi-value map.

3. Specific multipart text variable id.

4. Specific multipart text variable pass.

5. Single file upload named pic.

6. Multipart form bound to a User object (including the file).

Session parameters are available via session() or sessionOrNull(). (See the full Session Chapter for details).

1. Finds an existing Session or creates a new one.

2. Gets a specific session attribute.

Flash parameters transport success/error messages between requests. They are similar to a session, but their lifecycle is shorter: data is kept for only one request.

1. Sets a flash attribute: success.

2. Redirects to the home page.

3. Displays the flash attribute success (if it exists) or defaults to Welcome!.

Flash attributes are implemented using an HTTP Cookie. To customize the cookie (the default name is jooby.flash), use setFlashCookie(Cookie).

You can search for parameters across multiple sources with an explicitly defined priority using lookup().

If a request is made to /bar?foo=baz, the result will be foo is: baz because the query parameter takes precedence over the path parameter.

If mutual TLS is enabled, you can access the client’s certificates from the context. The first certificate in the list is the peer certificate, followed by the CA certificates in the chain.

1. Get all certificates presented by the client during the SSL handshake.

2. Get only the peer certificate.

Single values are retrieved via the value() or [type]Value() functions:

The value() family of methods always expects a value to exist. If the value is missing or cannot be converted to the requested type, a 400 Bad Request response is generated. Therefore, single-value parameters are implicitly required:

1. Access parameter name as String:

   • /?name=foo ⇒ foo

   • / ⇒ Bad Request(400): Missing value: "name"

2. Access parameter score as float:

   • /?score=1 ⇒ 1.0

   • /?score=string ⇒ Bad Request(400) (Type mismatch)

   • / ⇒ Bad Request(400)

3. Access parameter enabled as boolean:

   • /?enabled=true ⇒ true

   • /?enabled=string ⇒ Bad Request(400)

   • / ⇒ Bad Request(400)

4. Access parameter decimal and convert it to a custom type (BigDecimal):

   • /?decimal=2.3 ⇒ 2.3

   • /?decimal=string ⇒ Bad Request(400)

   • / ⇒ Bad Request(400)

You can handle optional parameters by providing a default value or requesting an Optional object:

1. Retrieve variable q as a String with a fallback default value of :.

   • /search?q=foo ⇒ foo

   • /search ⇒ :

2. Retrieve variable q wrapped in an Optional<String>:

   • /search?q=foo ⇒ Optional[foo]

   • /search ⇒ Optional.empty

Multiple values for a single parameter key can be retrieved as Collections:

• toList(): Returns a java.util.List

• toSet(): Returns a java.util.Set

1. Parameter q as List<String>:

   • / ⇒ []

   • /?q=foo ⇒ [foo]

   • /?q=foo&q=bar ⇒ [foo, bar]

2. Parameter n as List<Integer>:

   • / ⇒ []

   • /?n=1&n=2 ⇒ [1, 2]

3. Parameter d mapped to List<BigDecimal>:

   • / ⇒ []

   • /?d=1.5&d=2.0 ⇒ [1.5, 2.0]

The Value API allows you to traverse and parse deeply nested structured data from a request.

Given the query: /?user.name=root&user.pass=pass

1. Retrieves the user node.

2. Extracts name from the user node.

3. Extracts pass from the user node.

4. Safely extracts email with a fallback default.

The get(String) method takes a path and returns a nested Value node, which may or may not exist.

Syntax

?member.firstname=Pedro&member.lastname=Picapiedra

?member[firstname]=Pedro&member[lastname]=Picapiedra

?members[0]firstname=Pedro&members[0]lastname=Picapiedra

POJO Binding

class Member {
  public final String firstname;
  public final String lastname;

  public Member(String firstname, String lastname) {
    this.firstname = firstname;
    this.lastname = lastname;
  }
}

class Group {
  public final String id;
  public final List<Member> members;

  public Group(String id, List<Member> members) {
    this.id = id;
    this.members = members;
  }
}

class Member(val firstname: String, val lastname: String)

class Group(val id: String, val members: List<Member>)

{
  get("/", ctx -> {
    Member member = ctx.query(Member.class);
    // ...
  });
}

{
  get("/") {
    val member = ctx.query<Member>()
    // ...
  }
}

{
  get("/", ctx -> {
    Member member = ctx.query("member").to(Member.class);
    // ...
  });
}

{
  get("/") {
    val member = ctx.query("member").to<Member>()
    // ...
  }
}

{
  get("/", ctx -> {
    List<Member> members = ctx.query().toList(Member.class);
    // ...
  });
}

{
  get("/") {
    val members = ctx.query<List<Member>>()
    // ...
  }
}

{
  get("/", ctx -> {
    Group group = ctx.query(Group.class);
    // ...
  });
}

{
  get("/") {
    val group = ctx.query<Group>()
    // ...
  }
}

class Member {
  public final String firstname;
  public final String lastname;

  public Member(@Named("first-name") String firstname, @Named("last-name") String lastname) {
    this.firstname = firstname;
    this.lastname = lastname;
  }
}

class Member(@Named("first-name") val firstname: String, @Named("last-name") val lastname: String)

The ValueFactory allows you to register new type conversions or override existing ones globally.

{
  post("/string", ctx -> {
    String body = ctx.body().value();        // (1)
    // ...
  });

  post("/bytes", ctx -> {
    byte[] body = ctx.body().bytes();        // (2)
    // ...
  });

  post("/stream", ctx -> {
    InputStream body = ctx.body().stream();  // (3)
    // ...
  });
}

{
  post("/string") {
    val body = ctx.body().value()   // (1)
    // ...
  }

  post("/bytes") {
    val body = ctx.body().bytes()   // (2)
    // ...
  }

  post("/stream") {
    val body = ctx.body().stream()  // (3)
    // ...
  }
}

Request body parsing (converting the raw body into a specific object) is handled by the MessageDecoder functional interface.

The MessageDecoder has a single decode method that takes the request context and the target type, returning the parsed result.

1. Initialize your favorite JSON library.

2. Register the decoder to trigger when the Content-Type header matches application/json.

3. Read the raw body as a byte[].

4. Parse the payload into the requested type.

5. Inside the route, calling ctx.body(Type) automatically triggers the registered decoder.

{
  get("/", ctx -> {
    ctx.setResponseCode(200);                   // (1)
    ctx.setResponseType(MediaType.text);        // (2)
    ctx.setResponseHeader("Date", new Date());  // (3)

    return "Response";                          // (4)
  });
}

{
  get("/") {
    ctx.responseCode = 200                 // (1)
    ctx.responseType = MediaType.text      // (2)
    ctx.setResponseHeader("Date", Date())  // (3)

    "Response"                             // (4)
  }
}

Response encoding (converting an object into a raw HTTP response) is handled by the MessageEncoder functional interface.

The MessageEncoder has a single encode method that accepts the context and the value returned by the handler, producing an output. (Internally, Output works like a java.nio.ByteBuffer for performance reasons).

1. Initialize your favorite JSON library.

2. Register the encoder to trigger when the client’s Accept header matches application/json.

3. Convert the route’s result into JSON.

4. Set the Content-Type header to application/json.

5. Return the encoded JSON payload.

6. The route handler returns a user-defined POJO, which is automatically intercepted and encoded.

{
  get("/json", ctx -> {
    ctx.setContentType(MediaType.json);
    return "{\"message\": \"Hello Raw Response\"}";
  });
}

{
  get("/json") {
    ctx.contentType = MediaType.json
    """
      "message": "Hello Raw Response"
    """
  }
}

To enable a projection, you wrap your response object using the Projected.wrap utility. The projection syntax is parsed and applied to the underlying object or collection.

If you have used Jackson’s @JsonView, you will find Projections far more capable:

• Dynamic: Unlike @JsonView, which requires static class markers defined at compile-time, Projections are defined at runtime.

• Ad-hoc: You can create any combination of fields on the fly without adding new Java interfaces or classes.

• Deep Nesting: Projections easily handle deeply nested object graphs, whereas @JsonView can become difficult to manage with complex relationships.

The include method accepts a string using a simple, nested syntax:

• Field Selection: (id, name) returns only those two fields.

• Nested Selection: (id, address(city, country)) selects the id and specific fields from the nested address object.

• Wildcards: (id, address(*)) selects the id and all available fields within the address object.

• Deep Nesting: (id, orders(id, items(name, price))) allows for recursion into the object graph.

By default, the projection engine does not validate that requested fields exist on the target class (failOnMissingProperty is false). This allows for maximum flexibility, especially when working with polymorphic types or dynamic data where certain fields may only exist on specific subclasses.

If you prefer strict enforcement to prevent API consumers from requesting non-existent fields, you can enable validation:

Support for Projections extends beyond core scripting to include high-level annotations and documentation generation.

• MVC Support: Projections can be applied to controller methods using the @Project annotation. See the MVC documentation for details.

• OpenAPI Support: Jooby automatically generates pruned schemas for your Swagger documentation. See the OpenAPI documentation for details.

{
  get("/chunk", ctx -> {
    try(Writer writer = ctx.responseWriter()) { // (1)
      writer.write("chunk1");                   // (2)
      // ...
      writer.write("chunkN");
    }

    return ctx;                                 // (3)
  });
}

{
  get("/chunk") {
    ctx.responseWriter().use {                  // (1)
      writer.write("chunk1")                    // (2)
      // ...
      writer.write("chunkN")
    }
    ctx                                         // (3)
  }
}

{
  get("/chunk", ctx -> {
    return ctx.responseWriter(writer -> { // (1)
      writer.write("chunk1");             // (2)
      // ...
      writer.write("chunkN");
    });
  });
}

{
  get("/chunk") {
    ctx.responseWriter {                  // (1)
      writer.write("chunk1")              // (2)
      // ...
      writer.write("chunkN")
    }
  }
}

{
  get("/download-file", ctx -> {
    Path source = Paths.get("logo.png");
    return new AttachedFile(source);             // (1)
  });

  get("/view-stream", ctx -> {
    InputStream source = ...;
    return new InlineFile("myfile.txt", source); // (2)
  });
}

{
  get("/download-file") {
    val source = Paths.get("logo.png")
    AttachedFile(source)                // (1)
  }

  get("/view-stream") {
    val source = ...
    InlineFile("myfile.txt", source)    // (2)
  }
}

FileDownload.Builder produceDownload(Context ctx) {
  return FileDownload.build(...);
}

{
  get("/view", ctx -> produceDownload(ctx).inline());

  get("/download", ctx -> produceDownload(ctx).attachment());
}

fun produceDownload(ctx: Context) = FileDownload.build(...)

{
  get("/view") {
    produceDownload(it).inline()
  }

  get("/download") {
    produceDownload(it).attachment()
  }
}

{
  mode(EVENT_LOOP);                  // (1)
  use(ReactiveSupport.concurrent()); // (2)

  get("/non-blocking", ctx -> {
    return CompletableFuture         // (3)
        .supplyAsync(() -> {
          // ...                     // (4)
        });
  });
}

{
  mode(EVENT_LOOP)                   // (1)
  use(ReactiveSupport.concurrent())  // (2)

  get("/non-blocking") {
    CompletableFuture                // (3)
        .supplyAsync {
          // ...                     // (4)
        }
  }
}

{
  mode(WORKER);                      // (1)
  use(ReactiveSupport.concurrent()); // (2)

  get("/blocking", ctx -> {
    return CompletableFuture         // (3)
        .supplyAsync(() -> {
          // ...                     // (4)
        });
  });
}

{
  mode(WORKER)                       // (1)
  use(ReactiveSupport.concurrent())  // (2)

  get("/blocking") {
    CompletableFuture                // (3)
        .supplyAsync {
          // ...                     // (4)
        }
  }
}

{
  mode(DEFAULT);                     // (1)
  use(ReactiveSupport.concurrent()); // (2)

  get("/non-blocking", ctx -> {
    return CompletableFuture         // (3)
        .supplyAsync(() -> {
          // ...                     // (4)
        });
  });
}

{
  mode(DEFAULT)                     // (1)

  get("/non-blocking") {
    // ...                          // (2)
    CompletableFuture               // (3)
        .supplyAsync {
          // ...                    // (4)
        }
  }
}

CompletableFuture is a non-blocking type that produces a single result:

1) Add the SmallRye Mutiny dependency:

For Multi, Jooby automatically builds a chunked response. Each item in the stream is sent to the client as a new HTTP chunk.

1) Add the RxJava dependency:

For Flowable, Jooby builds a chunked response, sending each item as a separate chunk.

1) Add the Reactor dependency:

For Flux, Jooby builds a chunked response, sending each item as a separate chunk.

(Note: Coroutines are exclusive to Kotlin, so there is no Java equivalent for this section).

1. Call a suspending function.

2. Send the response to the client.

1. Call an extension suspending function.

2. Safely perform a suspending or blocking call.

3. Send the response to the client.

Coroutines work like any other non-blocking type. If you start Jooby using the event loop or default mode, Jooby creates a coroutine context to execute it.

Jooby uses the worker executor to create a coroutine context. This executor is provided by the web server implementation, unless you provide a custom one:

1. Statement runs in the worker executor (cached thread pool).

2. Calls a suspending function.

3. Produces a response.

By default, Coroutines always run in the worker executor. However, Jooby provides an experimental API where coroutines run in the caller thread (the event loop) until a suspending function is found. You can enable this by setting the coroutineStart option:

1. Statement runs in the event loop (caller thread).

2. Calls a suspending function and dispatches to the worker executor.

3. Produces a response from the worker executor.

You can also extend the CoroutineContext in which the routes run:

1. The launchContext lambda runs before launching each coroutine. It allows you to customize the CoroutineContext for the request (e.g., to store/restore MDC, transactions, or other request-scoped data).

{
  get("/", ctx -> {
    return ctx.send("Hello World!");
  });
}

{
  get("/") {
    ctx.send("Hello World!")
  }
}

import io.jooby.handler.AccessLogHandler;

{
  use(new AccessLogHandler()); // (1)

  get("/", ctx -> "Logging...");
}

import io.jooby.handler.AccessLogHandler

{
  use(AccessLogHandler())      // (1)

  get("/") { "Logging..." }
}

127.0.0.1 - - [04/Oct/2016:17:51:42 +0000] "GET / HTTP/1.1" 200 2 3

You can append specific request or response headers to the log entry using the following methods:

• requestHeader(String…​): Appends request headers to the log line.

• responseHeader(String…​): Appends response headers to the log line.

import io.jooby.handler.CorsHandler;

{
  use(new CorsHandler()); // (1)

  path("/api", () -> {
    // API methods
  });
}

import io.jooby.handler.CorsHandler

{
  use(CorsHandler())      // (1)

  path("/api") {
    // API methods
  }
}

To customize these settings, use the Cors class:

1. Specify the allowed HTTP methods.

2. Pass the custom configuration to the CorsHandler.

You can also define your CORS settings directly in your application.conf file:

Then, load the configuration into the handler:

1. Loads the CORS options defined in the cors namespace of your configuration file.

<form method="POST" action="/update-profile">
    <input name="csrf" value="{{csrf}}" type="hidden" />
    <button type="submit">Update</button>
</form>

CSRF protection requires an active Session Store to be configured first.

By default, the handler looks for a token named csrf in the following order:

1. HTTP Header: X-CSRF-Token or csrf

2. Cookie: csrf

3. Form Parameter: csrf

You can customize the behavior of the handler using the following methods:

• setTokenGenerator(Function): Customize how tokens are generated (defaults to a random UUID).

• setRequestFilter(Predicate): Define which requests should be validated. By default, it validates POST, PUT, PATCH, and DELETE requests.

import io.jooby.GracefulShutdown;

{
  install(new GracefulShutdown()); // (1)

  get("/", ctx -> "Hello!");
}

import io.jooby.GracefulShutdown

{
  install(GracefulShutdown())      // (1)

  get("/") { "Hello!" }
}

By default, the extension waits for all requests to finish. You can optionally specify a maximum duration to wait before forcing the application to stop:

import io.jooby.handler.HeadHandler;

{
  use(new HeadHandler()); // (1)

  get("/", ctx -> "Full response body");
}

import io.jooby.handler.HeadHandler

{
  use(HeadHandler())      // (1)

  get("/") { "Full response body" }
}

<dependency>
  <groupId>com.bucket4j</groupId>
  <artifactId>bucket4j_jdk17-core</artifactId>
  <version>8.21.0</version>
</dependency>

implementation 'com.bucket4j:bucket4j_jdk17-core:8.21.0'

The simplest configuration applies a global limit to all incoming requests.

1. Create a bucket with the desired capacity and refill rate.

2. Install the RateLimitHandler as a before filter.

Often, you want to limit requests per user, API key, or IP address rather than globally.

If you are running multiple Jooby instances, you can use a distributed bucket using Bucket4j’s ProxyManager. This allows the rate limit state to be shared across the cluster via a backend like Redis or Hazelcast.

For more details on setting up backends like Redis, Hazelcast, or Infinispan, refer to the Bucket4j documentation.

import io.jooby.handler.SSLHandler;

{
  before(new SSLHandler()); // (1)

  get("/", ctx -> "You are on: " + ctx.getScheme());
}

import io.jooby.handler.SSLHandler

{
  before(SSLHandler())      // (1)

  get("/") { "You are on: ${ctx.scheme}" }
}

By default, the handler redirects to the host provided in the request. You can explicitly specify a destination host if needed:

import io.jooby.handler.TraceHandler;

{
  use(new TraceHandler()); // (1)

  get("/", ctx -> "Hello World");
}

import io.jooby.handler.TraceHandler

{
  use(TraceHandler())      // (1)

  get("/") { "Hello World" }
}

{
  error((ctx, cause, statusCode) -> {                                      // (1)
    Router router = ctx.getRouter();
    router.getLog().error("Found {} error", statusCode.value(), cause);    // (2)

    ctx.setResponseCode(statusCode);
    ctx.send("Encountered a " + statusCode.value() + " error");            // (3)
  });
}

{
  error { ctx, cause, statusCode ->                                        // (1)
    val router = ctx.router
    router.log.error("Found {} error", statusCode.value(), cause)          // (2)

    ctx.responseCode = statusCode
    ctx.send("Encountered a ${statusCode.value()} error")                  // (3)
  }
}

import static io.jooby.MediaType.json;

{
  install(new MyTemplateEngineModule());                      // (1)
  install(new MyJsonModule());                                // (2)

  error((ctx, cause, statusCode) -> {
    ctx.getRouter().getLog().error("Error: {}", statusCode.value(), cause);

    Map<String, Object> errorData = Map.of("message", cause.getMessage());

    if (ctx.accept(json)) {                                   // (3)
      ctx.render(errorData);                                  // (4)
    } else {
      ctx.render(new ModelAndView("error.template", errorData)); // (5)
    }
  });
}

import io.jooby.MediaType.json

{
  install(MyTemplateEngineModule())                           // (1)
  install(MyJsonModule())                                     // (2)

  error { ctx, cause, statusCode ->
    ctx.router.log.error("Error: {}", statusCode.value(), cause)

    val errorData = mapOf("message" to cause.message)

    if (ctx.accept(json)) {                                   // (3)
      ctx.render(errorData)                                   // (4)
    } else {
      ctx.render(ModelAndView("error.template", errorData))   // (5)
    }
  }
}

In addition to the global error handler, you can register handlers for specific HTTP status codes:

1. Send a silent 404 response to the client.

In this example, we silence all 404 responses by bypassing the logging system and sending an empty response body.

You can also register handlers for specific exception types. This is useful for intercepting business-logic exceptions before they hit the global handler:

To enable Problem Details, simply add the following line to your configuration:

This minimal configuration enables a global error handler that catches all exceptions, transforms them into the Problem Details format, and renders the response based on the Accept header. It also sets the appropriate content type (e.g., application/problem+json).

You can customize the behavior using these additional properties:

1. By default, only server errors (5xx) are logged. You can enable logging for client errors (4xx) as well. (If your logger is set to DEBUG, the log will also include the stack trace).

2. Mute logging entirely for specific HTTP status codes.

3. Mute logging entirely for specific Exception classes.

The HttpProblem class represents the RFC 7807 model. Because it extends RuntimeException, you can throw it naturally just like any other exception.

Static Helpers

import io.jooby.problem.HttpProblem;
import io.jooby.StatusCode;

{
  get("/users/{userId}", ctx -> {
    String userId = ctx.path("userId").value();
    User user = userRepository.findUser(userId);

    if (user == null) {
      throw HttpProblem.valueOf(
        StatusCode.NOT_FOUND,
        "User Not Found",
        "User with ID " + userId + " was not found in the system."
      );
    }
    // ...
  });
}

import io.jooby.problem.HttpProblem
import io.jooby.StatusCode

{
  get("/users/{userId}") { ctx ->
    val userId = ctx.path("userId").value()
    val user = userRepository.findUser(userId)

    if (user == null) {
      throw HttpProblem.valueOf(
        StatusCode.NOT_FOUND,
        "User Not Found",
        "User with ID $userId was not found in the system."
      )
    }
    // ...
  }
}

{
    "timestamp": "2024-10-05T14:10:41.648933100Z",
    "type": "about:blank",
    "title": "User Not Found",
    "status": 404,
    "detail": "User with ID 123 was not found in the system.",
    "instance": null
}

Builder

throw HttpProblem.builder()
  .type(URI.create("http://example.com/invalid-params"))
  .title("Invalid input parameters")
  .status(StatusCode.UNPROCESSABLE_ENTITY)
  .detail("'Name' may not be empty")
  .instance(URI.create("http://example.com/invalid-params/3325"))
  .build();

throw HttpProblem.builder()
  .type(URI.create("http://example.com/invalid-params"))
  .title("Invalid input parameters")
  .status(StatusCode.UNPROCESSABLE_ENTITY)
  .detail("'Name' may not be empty")
  .instance(URI.create("http://example.com/invalid-params/3325"))
  .build()

Extra Parameters

throw HttpProblem.builder()
  .title("Order not found")
  .status(StatusCode.NOT_FOUND)
  .detail("Order with ID " + orderId + " could not be processed.")
  .param("reason", "Order ID format incorrect or order does not exist.")
  .param("suggestion", "Please check the order ID and try again.")
  .param("supportReference", "/support")
  .build();

throw HttpProblem.builder()
  .title("Order not found")
  .status(StatusCode.NOT_FOUND)
  .detail("Order with ID $orderId could not be processed.")
  .param("reason", "Order ID format incorrect or order does not exist.")
  .param("suggestion", "Please check the order ID and try again.")
  .param("supportReference", "/support")
  .build()

{
  "title": "Order not found",
  "status": 404,
  "detail": "Order with ID 123 could not be processed.",
  "parameters": {
    "reason": "Order ID format incorrect or order does not exist.",
    "suggestion": "Please check the order ID and try again.",
    "supportReference": "/support"
  }
}

Custom Headers

throw HttpProblem.builder()
  .title("Invalid input parameters")
  .status(StatusCode.UNPROCESSABLE_ENTITY)
  .header("my-string-header", "string-value")
  .header("my-int-header", 100)
  .build();

throw HttpProblem.builder()
  .title("Invalid input parameters")
  .status(StatusCode.UNPROCESSABLE_ENTITY)
  .header("my-string-header", "string-value")
  .header("my-int-header", 100)
  .build()

Error Details (RFC 9457)

throw HttpProblem.builder()
  .title("Validation Failed")
  .status(StatusCode.BAD_REQUEST)
  .error(new HttpProblem.Error("First name cannot be blank", "/firstName"))
  .error(new HttpProblem.Error("Last name is required", "/lastName"))
  .build();

throw HttpProblem.builder()
  .title("Validation Failed")
  .status(StatusCode.BAD_REQUEST)
  .error(HttpProblem.Error("First name cannot be blank", "/firstName"))
  .error(HttpProblem.Error("Last name is required", "/lastName"))
  .build()

{
  "title": "Validation Failed",
  "status": 400,
  "errors": [
    {
      "detail": "First name cannot be blank",
      "pointer": "/firstName"
    },
    {
      "detail": "Last name is required",
      "pointer": "/lastName"
    }
  ]
}

Mapping Custom Exceptions

import io.jooby.problem.HttpProblemMappable;

public class MyBusinessException extends RuntimeException implements HttpProblemMappable {

  @Override
  public HttpProblem toHttpProblem() {
    return HttpProblem.builder()
      .title("Business Logic Violation")
      .status(StatusCode.CONFLICT)
      .detail(this.getMessage())
      .build();
  }
}

import io.jooby.problem.HttpProblemMappable

class MyBusinessException(message: String) : RuntimeException(message), HttpProblemMappable {

  override fun toHttpProblem(): HttpProblem {
    return HttpProblem.builder()
      .title("Business Logic Violation")
      .status(StatusCode.CONFLICT)
      .detail(this.message)
      .build()
  }
}

Custom Problem Types

public class OutOfStockProblem extends HttpProblem {

  private static final URI TYPE = URI.create("https://example.org/out-of-stock");

  public OutOfStockProblem(String product) {
    super(builder()
      .type(TYPE)
      .title("Out of Stock")
      .status(StatusCode.BAD_REQUEST)
      .detail("The product '" + product + "' is no longer available.")
      .param("suggestions", List.of("Grinder MX-17", "Grinder MX-25"))
      .build()
    );
  }
}

import java.net.URI

class OutOfStockProblem(product: String) : HttpProblem(
  builder()
    .type(URI.create("https://example.org/out-of-stock"))
    .title("Out of Stock")
    .status(StatusCode.BAD_REQUEST)
    .detail("The product '$product' is no longer available.")
    .param("suggestions", listOf("Grinder MX-17", "Grinder MX-25"))
    .build()
)

Custom Exception Handlers

{
  error(MyCustomException.class, (ctx, cause, code) -> {
    MyCustomException ex = (MyCustomException) cause;

    HttpProblem problem = HttpProblem.valueOf(code, ex.getMessage());  // (1)

    ctx.getRouter().getErrorHandler().apply(ctx, problem, code);       // (2)
  });
}

{
  error(MyCustomException::class) { ctx, cause, code ->
    val ex = cause as MyCustomException

    val problem = HttpProblem.valueOf(code, ex.message)                // (1)

    ctx.router.errorHandler.apply(ctx, problem, code)                  // (2)
  }
}

The EVENT_LOOP mode allows you to run route handlers directly on the event loop (a.k.a. non-blocking mode).

The EVENT_LOOP mode is an advanced execution model that requires careful application design, because BLOCKING IS STRICTLY FORBIDDEN on the event loop thread.

What if you need to block?

The dispatch(Runnable) operator shifts execution to a worker executor, which safely allows blocking calls (like database queries or remote service calls):

By default, the dispatch operator moves execution to the default worker executor provided by the underlying web server.

However, you can provide your own custom worker executor at the application level or specifically for a single dispatch block:

The WORKER mode allows you to make blocking calls from any route handler (a.k.a. blocking mode). You can write code sequentially without worrying about blocking the server.

Just like in EVENT_LOOP mode, you can override the default server worker and provide your own custom executor:

The DEFAULT execution mode is a smart hybrid between the WORKER and EVENT_LOOP modes. As the name implies, this is the default execution mode in Jooby.

Jooby analyzes the return type of your route handler to determine which execution mode fits best. If the response type is non-blocking, it executes on the event loop. Otherwise, it dispatches to the worker executor.

A response type is considered non-blocking if the route handler produces:

• A CompletableFuture

• An RxJava type (e.g., Single, Flowable)

• A Reactor type (e.g., Mono, Flux)

• A Kotlin Coroutine

1. CompletableFuture is a non-blocking type; this route executes directly on the event loop.

2. String is a blocking type; this route is dispatched to the worker executor.

workerThreads = Math.max(Runtime.getRuntime().availableProcessors(), 2) * 8

workerThreads = Runtime.getRuntime().availableProcessors() * 8

{
  configureServer(server -> {
    server.setWorkerThreads(100);
  });
}

{
  configureServer { server ->
    server.setWorkerThreads(100)
  }
}

{
  Path docs = Paths.get("docs"); // (1)
  assets("/docs/?*", docs);      // (2)
}

{
  val docs = Paths.get("docs")   // (1)
  assets("/docs/?*", docs)       // (2)
}

{
  AssetSource buildDir = AssetSource.create(Paths.get("build")); // (1)
  assets("/?*", new AssetHandler("index.html", buildDir));       // (2)
}

{
  val buildDir = AssetSource.create(Paths.get("build"))          // (1)
  assets("/?*", AssetHandler("index.html", buildDir))            // (2)
}

{
  assets("/static/*", Paths.get("www"))
    .setLastModified(false)
    .setEtag(false);
}

{
  assets("/static/*", Paths.get("www"))
    .setLastModified(false)
    .setEtag(false)
}

{
  assets("/static/*", Paths.get("www"))
    .setMaxAge(Duration.ofDays(365));
}

{
  assets("/static/*", Paths.get("www"))
    .setMaxAge(Duration.ofDays(365))
}

{
  assets("/static/*", Paths.get("www"))
      .cacheControl(path -> {
        if (path.endsWith("dont-cache-me.html")) {
          return CacheControl.noCache(); // Disable caching
        } else if (path.equals("foo.js")) {
          return CacheControl.defaults()
              .setETag(false)
              .setMaxAge(Duration.ofDays(365));
        } else {
          return CacheControl.defaults(); // Use default AssetHandler caching
        }
      });
}

{
  assets("/static/*", Paths.get("www"))
      .cacheControl { path ->
        when {
          path.endsWith("dont-cache-me.html") -> CacheControl.noCache() // Disable caching
          path == "foo.js" -> CacheControl.defaults()
              .setETag(false)
              .setMaxAge(Duration.ofDays(365))
          else -> CacheControl.defaults() // Use default AssetHandler caching
        }
      }
}

{
  assets("/static/*", Paths.get("www"))
      .notFound(ctx -> {
        throw new MyAssetException();
      });

  error(MyAssetException.class, (ctx, cause, code) -> {
    // Render MyAssetException the way you want
  });
}

{
  assets("/static/*", Paths.get("www"))
    .notFound { _ ->
        throw MyAssetException()
    }

  error(MyAssetException::class) { ctx, cause, code ->
    // Render MyAssetException the way you want
  }
}

jooby create myapp --mvc

public class App extends Jooby {
  {
    mvc(new MyController_());
  }

  public static void main(String[] args) {
    runApp(args, App::new);
  }
}

import io.jooby.kt.runApp

fun main(args: Array<String>) {
  runApp(args) {
    mvc(MyController_())
  }
}

Extract headers using the HeaderParam annotation:

1. Accesses the HTTP header named token.

Unlike JAX-RS, specifying the parameter name inside the annotation is optional. Jooby infers it from the variable name. However, you must provide the name explicitly if the HTTP header is not a valid Java identifier:

Extract cookies using the CookieParam annotation:

1. Accesses the cookie named token.

As with headers, provide the explicit name if the cookie key contains dashes or invalid Java characters (e.g., @CookieParam("token-id") String tokenId).

Extract path variables using the PathParam annotation:

Extract query string variables using the QueryParam annotation:

Extract form-data or multipart parameters using the FormParam annotation:

The HTTP request body does not require an explicit annotation. Simply define the POJO in the method signature:

The BindParam annotation allows for custom data binding from the HTTP request directly into an object.

How @BindParam works:

• It looks for a public method/function on the target class that accepts a Context and returns the target type.

• By default, it looks for this factory method on the parameter type itself (MyBean), but will fall back to searching the Controller class.

Alternatively, you can specify a distinct factory class and/or method name:

Extract flash attributes using the FlashParam annotation:

1. Accesses the flash attribute named success.

Extract specific session attributes using the SessionParam annotation:

1. Accesses the session attribute named userId.

You can also request the entire Session object:

1. If no session exists yet, a new session will be created. To avoid this and only retrieve an existing session, use Optional<Session> as the parameter type.

Extract specific context attributes using the ContextParam annotation:

1. Accesses the context attribute named userId.

You can also request all attributes at once:

1. To retrieve all context attributes, the parameter must be typed as a Map<String, Object> (or Map<String, Any> in Kotlin).

Use the Param annotation to search for a parameter across multiple sources with an explicitly defined fallback order:

If a request is made to /bar?foo=baz, the result will be foo is: baz because the QUERY parameter takes precedence over the PATH parameter in the annotation array.

The MVC module provides first-class support for Projections via annotations. This allows you to define the response view declaratively, keeping your controller logic clean and focused on data retrieval.

Usage

@GET
@Project("(id, name)")
public List<User> listUsers() {
  return service.findUsers();
}

@GET(value = "/users", projection = "(id, name, email)")
public List<User> listUsers() {
  return service.findUsers();
}

Automatic Wrapping

@GET
public Projected<User> getUser(String id) {
  User user = service.findById(id);
  return Projected.wrap(user)
      .failOnMissingProperty(true)
      .include("(id, status)");
}

The default HTTP status code returned by an MVC route is 200 OK, except for void methods annotated with @DELETE, which automatically return 204 No Content.

If you need to return a different status code, you have two options: 1. Inject the Context into your method and call setResponseCode(StatusCode). 2. Return a StatusCode instance directly from the method.

Any MVC method returning a non-blocking type (CompletableFuture, Single, Maybe, Flowable, Mono, Flux) is automatically handled as a non-blocking route.

Kotlin suspend functions are also supported natively:

A non-blocking route runs on the event loop by default, where blocking is NOT allowed. For more details, see the NonBlocking Responses section.

public class MyController {

  @GET("/blocking")
  @Dispatch              // (1)
  public String blocking() {
    return "I'm blocking";
  }
}

import io.jooby.annotation.*

class MyController {

  @GET("/blocking")
  @Dispatch              // (1)
  fun blocking(): String {
    return "I'm blocking"
  }
}

public class MyController {

  @GET("/blocking")
  @Dispatch("single")         // (1)
  public String blocking() {
    return "I'm blocking";
  }
}

import io.jooby.annotation.*

class MyController {

  @GET("/blocking")
  @Dispatch("single")         // (1)
  fun blocking(): String {
    return "I'm blocking"
  }
}

{
  executor("single", Executors.newSingleThreadExecutor());

  mvc(new MyController_());
}

{
  executor("single", Executors.newSingleThreadExecutor())

  mvc(MyController_())
}

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/jaxrs")
public class Resource {

  @GET
  public String getIt() {
    return "Got it!";
  }
}

import javax.ws.rs.GET
import javax.ws.rs.Path

@Path("/jaxrs")
class Resource {

  @GET
  fun getIt(): String {
    return "Got it!"
  }
}

{
  var routes = mvc(new MyController_());
  routes.forEach(route -> {
    // Modify or inspect the route
  });
}

{
  install(new HandlebarsModule());                 // (1)
  install(new FreemarkerModule());                 // (2)

  get("/first", ctx -> {
    return new ModelAndView("index.hbs", model);   // (3)
  });

  get("/second", ctx -> {
    return new ModelAndView("index.ftl", model);   // (4)
  });
}

{
  install(HandlebarsModule())                       // (1)
  install(FreemarkerModule())                       // (2)

  get("/first") { ctx ->
    ModelAndView("index.hbs", model)                // (3)
  }

  get("/second") { ctx ->
    ModelAndView("index.ftl", model)                // (4)
  }
}

{
  setSessionStore(SessionStore.memory(Cookie.session("myappid")));

  get("/", ctx -> {
    Session session = ctx.session();   // (1)
    session.put("foo", "bar");         // (2)

    return session.get("foo").value(); // (3)
  });
}

{
  sessionStore = SessionStore.memory(Cookie.session("myappid"))

  get("/") {
    val session = ctx.session()        // (1)
    session.put("foo", "bar")          // (2)

    session.get("foo").value()         // (3)
  }
}

{
  setSessionStore(SessionStore.memory(new Cookie("SESSION")));    // (1)

  get("/", ctx -> {
    Session session = ctx.session();
    session.put("foo", "bar");

    return session.get("foo").value();
  });
}

{
  sessionStore = SessionStore.memory(Cookie("SESSION"))           // (1)

  get("/") {
    val session = ctx.session()
    session.put("foo", "bar")

    session.get("foo").value()
  }
}

{
  setSessionStore(SessionStore.memory(SessionToken.header("TOKEN")));    // (1)

  get("/", ctx -> {
    Session session = ctx.session();
    session.put("foo", "bar");

    return session.get("foo").value();
  });
}

{
  sessionStore = SessionStore.memory(SessionToken.header("TOKEN"))       // (1)

  get("/") {
    val session = ctx.session()
    session.put("foo", "bar")

    session.get("foo").value()
  }
}

{
  setSessionStore(SessionStore.memory(
      SessionToken.combine(SessionToken.cookie("SESSION"), SessionToken.header("TOKEN")) // (1)
  ));

  get("/", ctx -> {
    Session session = ctx.session();
    session.put("foo", "bar");

    return session.get("foo").value();
  });
}

{
  sessionStore = SessionStore.memory(
      SessionToken.combine(SessionToken.cookie("SESSION"), SessionToken.header("TOKEN")) // (1)
  )

  get("/") {
    val session = ctx.session()
    session.put("foo", "bar")

    session.get("foo").value()
  }
}

{
  String secret = "super-secret-key-must-be-32-bytes";                        // (1)
  setSessionStore(SessionStore.signed(Cookie.session("myappid"), secret));    // (2)

  get("/", ctx -> {
    Session session = ctx.session();
    session.put("foo", "bar");

    return session.get("foo").value();
  });
}

{
  val secret = "super-secret-key-must-be-32-bytes"                           // (1)
  sessionStore = SessionStore.signed(Cookie.session("myappid"), secret)      // (2)

  get("/") {
    val session = ctx.session()
    session.put("foo", "bar")

    session.get("foo").value()
  }
}

{
  String secret = "super-secret-key-must-be-32-bytes";                           // (1)
  setSessionStore(SessionStore.signed(SessionToken.header("TOKEN"), secret));    // (2)

  get("/", ctx -> {
    Session session = ctx.session();
    session.put("foo", "bar");

    return session.get("foo").value();
  });
}

{
  val secret = "super-secret-key-must-be-32-bytes"                               // (1)
  sessionStore = SessionStore.signed(SessionToken.header("TOKEN"), secret)       // (2)

  get("/") {
    val session = ctx.session()
    session.put("foo", "bar")

    session.get("foo").value()
  }
}

import io.jooby.ServerSentEmitter;
import io.jooby.annotation.SSE;

public class Events {
  @SSE("/sse")
  public void sse(ServerSentEmitter emitter) {
    emitter.send("Welcome");
    emitter.onClose(() -> {
      // Clean up resources.
    });
    emitter.close();
  }
}

import io.jooby.ServerSentEmitter
import io.jooby.annotation.SSE

class Events {
  @SSE("/sse")
  fun sse(emitter: ServerSentEmitter) {
    emitter.send("Welcome")
    emitter.onClose {
      // Clean up resources.
    }
    emitter.close()
  }
}

{
  sse("/sse", sse -> {
    sse.send(
        new ServerSentMessage("...")
            .setEvent("myevent")
            .setId("myId")
            .setRetry(1000)
    );
  });
}

{
  sse("/sse") {
    sse.send(ServerSentMessage("...").apply {
        event = "myevent"
        id = "myId"
        retry = 1000
    })
  }
}

{
  sse("/sse", sse -> {
    sse.onClose(() -> {
      // Clean up resources
    });
  });
}

{
  sse("/sse") {
    sse.onClose {
      // Clean up resources
    }
  }
}

{
  sse("/sse", sse -> {
    sse.keepAlive(15, TimeUnit.SECONDS);
  });
}

{
  sse("/sse") {
    sse.keepAlive(15, TimeUnit.SECONDS)
  }
}

import io.jooby.jackson.Jackson2Module;

{
  install(new Jackson2Module());                        // (1)

  ws("/ws", (ctx, configurer) -> {
    configurer.onMessage((ws, message) -> {
      MyObject myobject = message.to(MyObject.class);  // (2)
      ws.render(myobject);                             // (3)
    });
  });
}

import io.jooby.jackson.Jackson2Module

{
  install(Jackson2Module())                             // (1)

  ws("/ws") { ctx, configurer ->
    configurer.onMessage { ws, message ->
      val myobject = message.to<MyObject>()            // (2)
      ws.render(myobject)                              // (3)
    }
  }
}

import io.jooby.jackson.Jackson2Module;

{
  install(new Jackson2Module());                        // (1)

  ws("/ws", (ctx, configurer) -> {
    configurer.onMessage((ws, message) -> {
      MyObject myobject = message.to(MyObject.class);  // (2)
      ws.render(myobject);                             // (3)
    });
  })
  .consumes(MediaType.json)
  .produces(MediaType.json);
}

import io.jooby.jackson.Jackson2Module

{
  install(Jackson2Module())                             // (1)

  ws("/ws") { ctx, configurer ->
    configurer.onMessage { ws, message ->
      val myobject = message.to<MyObject>()            // (2)
      ws.render(myobject)                              // (3)
    }
  }.consumes(MediaType.json)
   .produces(MediaType.json)
}

@Path("/chat/{room}")                                        // (1)
public class ChatSocket {

  @OnConnect
  public String onConnect(WebSocket ws, Context ctx) {       // (2)
    return "welcome";
  }

  @OnMessage
  public Map<String, String> onMessage(WebSocket ws, Context ctx, WebSocketMessage message) { // (3)
    return Map.of("echo", message.value());
    // ws.send(message.value());                             // (4)
  }

  @OnClose
  public void onClose(WebSocket ws, Context ctx, WebSocketCloseStatus status) {}

  @OnError
  public void onError(WebSocket ws, Context ctx, Throwable cause) {}
}

// Application startup:
{
  ws(new ChatSocketWs_());                                   // (5)
}

@Path("/chat/{room}")                                        // (1)
class ChatSocket {

  @OnConnect
  fun onConnect(ws: WebSocket, ctx: Context): String {       // (2)
    return "welcome"
  }

  @OnMessage
  fun onMessage(ws: WebSocket, ctx: Context, message: WebSocketMessage): Map<String, String> { // (3)
    return mapOf("echo" to message.value())
    // ws.send(message.value())                              // (4)
  }

  @OnClose
  fun onClose(ws: WebSocket, ctx: Context, status: WebSocketCloseStatus) {}

  @OnError
  fun onError(ws: WebSocket, ctx: Context, cause: Throwable) {}
}

// Application startup:
{
  ws(ChatSocketWs_())                                         // (5)
}

@Path("/chat/{room}")
public class ChatSocket {

  record ChatMessage(String username, String message, String type) {}

  @OnMessage
  public Map<String, ChatMessage> onMessage(ChatMessage message) { // (1)
    return Map.of("echo", message);
  }

  ...
}

@Path("/chat/{room}")
class ChatSocket {

  data class ChatMessage(
      val username: String,
      val message: String,
      val type: String
  )

  @OnMessage
  fun onMessage(message: ChatMessage): Map<String, ChatMessage> { // (1)
    return mapOf("echo" to message)
  }

  ...
}

Jooby automatically times out idle connections that have no activity after 5 minutes. You can control this behavior by setting the websocket.idleTimeout property in your configuration file:

See the Typesafe Config documentation for the supported duration format.

The maximum message size is set to 128K by default. You can override it using the websocket.maxSize property:

See the Typesafe Config documentation for the supported size in bytes format.

import io.jooby.Reified;

{
  // 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;
  });
}

import io.jooby.Reified

{
  // Add to a List
  services.listOf(Animal::class.java).add(Cat())
  services.listOf(Animal::class.java).add(Dog())

  // Add to a Map
  services.mapOf(String::class.java, Animal::class.java).put("cat", Cat())

  get("/list") { ctx ->
    // Retrieve the List using the Reified type helper
    val animals = ctx.require(Reified.list(Animal::class.java))
    animals
  }
}

import io.jooby.Extension;
import io.jooby.Jooby;

public class MyExtension implements Extension {
   @Override
   public void install(Jooby app) {
      DataSource dataSource = createDataSource();         // (1)

      app.getServices().put(DataSource.class, dataSource);// (2)

      app.onStop(dataSource::close);                      // (3)
   }

   private DataSource createDataSource() {
       // Initialization logic
   }
}

import io.jooby.Extension
import io.jooby.Jooby

class MyExtension : Extension {
  override fun install(app: Jooby) {
    val dataSource = createDataSource()                  // (1)

    app.services.put(DataSource::class.java, dataSource) // (2)

    app.onStop(dataSource::close)                        // (3)
  }

  private fun createDataSource(): DataSource {
      // Initialization logic
  }
}

public class App extends Jooby {
   {
     install(new MyExtension());                      // (1)

     get("/", ctx -> {
       DataSource ds = require(DataSource.class);     // (2)
       // Use the datasource...
       return "Success";
     });
   }
}

class App : Kooby({
  install(MyExtension())                              // (1)

  get("/") {
    val ds = require(DataSource::class.java)          // (2)
    // Use the datasource...
    "Success"
  }
})

{
  Environment env = getEnvironment();
}

{
  val env = environment
}

{
  Environment env = getEnvironment();         // (1)
  Config conf = env.getConfig();              // (2)
  System.out.println(conf.getString("foo"));  // (3)
}

{
  val env = environment                       // (1)
  val conf = env.config                       // (2)
  println(conf.getString("foo"))              // (3)
}

└── application.conf      (foo = "default", bar = "base")
└── application.prod.conf (foo = "production")

{
  setEnvironmentOptions(new EnvironmentOptions().setFilename("myapp.conf")); // (1)
}

{
  environmentOptions {
    filename = "myapp.conf" // (1)
  }
}

{
  Config conf = ConfigFactory.load("custom.conf");           // (1)
  Environment env = new Environment(getClassLoader(), conf); // (2)
  setEnvironment(env);                                       // (3)
}

{
  val conf = ConfigFactory.load("custom.conf")               // (1)
  val env = Environment(classLoader, conf)                   // (2)
  environment = env                                          // (3)
}

1. Add Dependency: logback-classic.

2. Configure: Place logback.xml in your conf directory or classpath root.

1. Add Dependencies: log4j-slf4j-impl and log4j-core.

2. Configure: Place log4j2.xml in your conf directory or classpath root.

Logging is also environment-aware. Jooby will look for logback.[env].xml or log4j2.[env].xml and favor them over the default files.

<plugins>
  <plugin>
    <groupId>io.jooby</groupId>
    <artifactId>jooby-maven-plugin</artifactId>
    <version>4.6.0</version>
  </plugin>
</plugins>

plugins {
  id "application"
  id "io.jooby.run" version "4.6.0"
}

<properties>
  <application.class>myapp.App</application.class>
</properties>

mainClassName = "myapp.App"

mvn jooby:run

./gradlew joobyRun

<configuration>
  <mainClass>${application.class}</mainClass>
  <restartExtensions>conf,properties,class</restartExtensions>
  <compileExtensions>java,kt</compileExtensions>
  <port>8080</port>
  <waitTimeBeforeRestart>500</waitTimeBeforeRestart>
  <useSingleClassLoader>false</useSingleClassLoader>
</configuration>

joobyRun {
  mainClassName = "${mainClassName}"                               // (1)
  restartExtensions = ["conf", "properties", "class"]              // (2)
  compileExtensions = ["java", "kt"]                               // (3)
  port = 8080                                                      // (4)
  waitTimeBeforeRestart = 500                                      // (5)
  useSingleClassLoader = false                                     // (6)
}

<dependency>
  <groupId>io.jooby</groupId>
  <artifactId>jooby-test</artifactId>
  <version>4.6.0</version>
</dependency>

implementation 'io.jooby:jooby-test:4.6.0'

public class App extends Jooby {
  {
    get("/", ctx -> "Easy unit testing!");
  }
}

class App : Kooby({
  get("/") { "Easy unit testing!" }
})

import io.jooby.test.MockRouter;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class TestApp {
  @Test
  public void test() {
    MockRouter router = new MockRouter(new App());
    assertEquals("Easy unit testing!", router.get("/").value());
  }
}

import io.jooby.test.MockRouter
import org.junit.jupiter.api.Assertions.assertEquals

class TestApp {
  @Test
  fun test() {
    val router = MockRouter(App())
    assertEquals("Easy unit testing!", router.get("/").value())
  }
}

If your route modifies the context (like setting status codes or headers), you can verify the metadata using a callback:

For complex routes that interact with forms, bodies, or headers, you can provide a MockContext or a mock object from a library like Mockito.

import io.jooby.test.JoobyTest;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

@JoobyTest(App.class) // (1)
public class IntegrationTest {

  static OkHttpClient client = new OkHttpClient();

  @Test
  public void testApp() throws IOException {
    Request request = new Request.Builder()
        .url("http://localhost:8911") // (2)
        .build();

    try (Response response = client.newCall(request).execute()) {
      assertEquals("Easy testing!", response.body().string());
    }
  }
}

import io.jooby.test.JoobyTest
import okhttp3.OkHttpClient
import okhttp3.Request

@JoobyTest(App::class) // (1)
class IntegrationTest {

  companion object {
    val client = OkHttpClient()
  }

  @Test
  fun testApp() {
    val request = Request.Builder()
        .url("http://localhost:8911") // (2)
        .build()

    client.newCall(request).execute().use { response ->
      assertEquals("Easy testing!", response.body?.string())
    }
  }
}