Usecases I: Basics

This chapter assumes you understand basic http and HttpMaid concepts, especially the mechanics of marshalling and unmarshalling.

So far, we introduced you how to handling requests in a very low-level fashion using the HttpHandler interface in the examples. This way, you can directly access request and response features like headers and query parameters. In real projects, you would call domain logic from the handlers in order to do something productively and keep an architectural boundary between infrastructure code (HttpMaid) and business / domain logic. Depending on which design “philosophy” you follow, you might call the entry points into your domain logic services, usecases, or even something else. In order to maintain consistency, throughout HttpMaid we will call this concept a usecase.

Let’s design a simple usecase:

public final class PingUseCase {

    public void ping() {

As you can see, the PingUseCase is a POJO class with a single public method ping(). Note how the class does not contain a single dependency on any infrastructure (read: HttpMaid) code. If we want to serve this usecase via HttpMaid using the constructs we know so far, we will probably end up with something like this:

final HttpMaid httpMaid = anHttpMaid()
        .get("/ping", (request, response) -> {
            final PingUseCase pingUseCase = new PingUseCase();

We registered a handler that instantiates the usecase and then calls it. Since more complex projects might contain hundreds of usecases, registering usecases to HttpMaid this way leads to a lot of boilerplate code and heavily violates the Don’t repeat yourself design principle.

Serving usecases directly

HttpMaid mitigates these problems by offering to directly serve usecases. Instead of calling the domain logic from handlers, you register the usecase classes directly to HttpMaid.

In order to do this, you need to add the httpmaid-usecases dependency to your project:


HttpMaid will automatically discover the dependency and support usecases. Afterwards, you can change the configuration and shrink it down significantly:

final HttpMaid httpMaid = anHttpMaid()
        .get("/ping", PingUseCase.class)

HttpMaid will now direct POST requests on the /ping route to the ping() usecase method. You can try this by running your application. Once you browse to http://localhost:1337/ping, you should see the Ping! message pop up on the console.