Controllers #

In order for this feature to work, you must compile your code with the -p argument.

As your application becomes more complex, using Express-style routing can become unwieldly. Controllers are a great way of organizing your code by grouping related endpoints into one class.

Controllers are classes that extend the Controller class, with methods annotated with annotations from the diego.web.annotations package. These annotated methods must return an instance of diego.web.Result.

First, declare a Controller:

package app.auth;

import diego.web.Controller;
import diego.web.Results;
import diego.web.annotations.GET;

public class AuthController extends Controller {
    @GET("/login")
    public Result login() {
        return Results.view("auth/login"); // Render the login form
    }
}

Then you add it to your main configuration:

package app;

import diego.mvc.WebMvcConfiguration;
import diego.mvc.WebMvcApplication;
import auth.AuthController;

public class MyApplication implements WebMvcConfiguration {
    
    public void configure(WebMvcApplication app) {
        app.addController("/auth", AuthController.class)
    }
}

Check out the Results class to see the different types of results that can be generated.

HTTP Verb Annotations #

To indicate which the type of request a method should handle, use one of the HTTP verb annotations: @GET, @POST, @PUT, @PATCH or @DELETE. For each annotation, you can provide a URL path template as you would have done with an Express-style route. If you do not provide a path template, a template will be generated based on an internal convention:

For example, the following method will be accessible via GET /customers/new:

class CustomersController extends Controller {
    
    @GET
    public Result newCustomer() {
        return Results.view("customers/new-customer-form");
    }
}

Accepting Parameters #

Just like with Express-style routes, your controller methods can accept the request Context as a parameter:

@GET
public Result edit(Context ctx) {
    Long id = Long.parseLong(ctx.pathParameter("id"));
    // Return a result
}

If your path template has path variables, you can make them parameters of your method. They will automatically be converted to the correct type from the HTTP request.

Since the controller action in the example above creates the path /:id/edit (according to the convention), you can rewrite it as follows:

@GET
public Result edit(Long id) {
    // Use the id
    // Return a result
}

The most common types will be automatically mapped:

• Long, long
• Boolean, boolean
• Double, double
• Float,float
• String
• Date
• LocalDate
• LocalDateTime
• BigDecimal

Note: Temporal types are expected to be in standard ISO 8601 format.

Parameter Annotations #

Diego provides some annotations that allow you to specify exactly where to find a value for a parameter in the current HTTP request context:

• @QueryParameter: Get a parameter from the request’s query string. It can be a single value or a List;
• @Cookie: Get a value from a cookie;
• @Attachment: Receive an uploaded file. This can only be applied to FileUpload parameters;
• @Form: Parse the request parameters (or the JSON body of the request) into a Java Bean and validate it (covered later);
• @Param: Get a form parameter; and
• @State: Get a value from the Context state.

It is expected that the parameter name matches the request parameter’s name. If this is not the case, some of these annotations allow you to specify the name of the request parameter, e.g. @QueryParameter("name") String customerName.

Using fields inside of controllers #

Only one instance of your Controller is created during configuration. This instance is reused across requests and across threads. This means that your Controller classes should be stateless (having no internal state) or make use of ThreadLocal variables to avoid concurrency issues.

Next: Serving Static Assets