HTTP Programming

Actions, Controllers and Results

What is an Action?

Most of the requests received by a Wisdom application are handled by an action. An action is basically a Java method that processes the received request parameters, and produces a Result to be sent to the client.

@Route(method = HttpMethod.POST, uri = "/")
public Result index() {
    return ok("Got request " + request() + "!");
}

An action returns a org.wisdom.api.http.Result value, representing the HTTP response to send to the web client. In this example ok constructs a OK (HTTP Code 200) response containing a text/plain response body.

Actions are declared with the org.wisdom.api.annotations.Route annotation (@Route) indicating the HTTP method and uri used to invoke the action.

Controllers

Controllers are Wisdom components containing the application logic. A controller is nothing more than a class annotated with the org.wisdom.api.annotations.Controller (@Controller) that groups several action methods.

include::{sourcedir}/controllers/Simple.java[tags=controller]

The simplest syntax for defining an action is a (non-static) method with no parameters that returns a Result value, as shown above.

An action method can also have parameters:

include::{sourcedir}/controllers/Name.java[tags=controller]

These parameters (indicated with the @Parameter annotation) will be resolved by Wisdom and will be filled with values from the request. The parameter values can be extracted from either the URL path or the URL query. The annotation value, "name" in the previous example, indicates the name of the parameter.

Results

Let’s start with basic results: an HTTP result with a status code, a set of HTTP headers and a body to be sent to the client. These results are defined by org.wisdom.api.http.Result, and the org.wisdom.api.http.Results class provides several helpers to produce standard HTTP results, such as the ok method we used in the previous examples:

include::{sourcedir}/controllers/Simple.java[tags=controller]

Here are several examples that create various results:

include::{sourcedir}/controllers/ResultExample.java[tags=results]

All of these helpers can be found in the org.wisdom.api.http.Results class.

Redirects are simple results too

Redirecting the browser to a new URL is just another kind of simple result. However, these result types don’t have a response body.

include::{sourcedir}/controllers/Redirect.java[tags=redirect]

The default is to use a 303 SEE_OTHER response type, but you can also specify a more specific status code:

include::{sourcedir}/controllers/Redirect.java[tags=temporary-redirect]