Request processing

How these parts work together, and why, is explained in What happens during a request.

Objects of a request

The static get() methods read a thread-local value that Wicket sets while it serves the request. Outside a request, for example in a background thread, RequestCycle.get() returns null and Application.get() throws a WicketRuntimeException. Application.exists() and Session.exists() tell you whether one is bound to the thread.

Servlet request and response

Request.getContainerRequest() and Response.getContainerResponse() return the objects of the servlet container:

var servletRequest = (HttpServletRequest) getRequest().getContainerRequest();
var servletResponse = (HttpServletResponse) getResponse().getContainerResponse();
String clientIp = servletRequest.getRemoteAddr();

Commonly used methods of the Wicket wrappers:

Steps of a request

WicketFilter receives every request mapped to it and asks the application for a request cycle. RequestCycle.processRequestAndDetach() then runs these steps:

RequestCycle methods

Override onBeginRequest(), onEndRequest() and onDetach() in a subclass to run code at those moments. Install the subclass with a provider, because createRequestCycle() is final:

@Override
protected void init() {
    super.init();
    setRequestCycleProvider(MyRequestCycle::new);
}

public class MyRequestCycle extends RequestCycle {
    public MyRequestCycle(RequestCycleContext context) {
        super(context);
    }

    @Override
    protected void onBeginRequest() {
        super.onBeginRequest();
        // ...
    }
}

IRequestCycleListener

All methods are default methods; implement the ones you need. Register a listener in Application.init() with getRequestCycleListeners().add(listener). One instance serves all requests at the same time, so it must be thread-safe.

public class RequestTimer implements IRequestCycleListener {
    @Override
    public void onEndRequest(RequestCycle cycle) {
        long millis = System.currentTimeMillis() - cycle.getStartTime();
        log.info("{} took {} ms", cycle.getRequest().getUrl(), millis);
    }
}

getRequestCycleListeners() returns a RequestCycleListenerCollection, which is itself an IRequestCycleListener, so you can group listeners.

Request handlers

IRequestHandler has two methods: respond(IRequestCycle) writes the response, and detach(IRequestCycle) (a default method) releases what it held. The handlers Wicket ships:

Exceptions that change the flow

Throw these from a constructor, a listener or a lifecycle hook to stop the current handler and run another:

Request mappers

IRequestMapper turns a request into a handler with mapRequest(Request) and a handler into a URL with mapHandler(IRequestHandler). getCompatibilityScore(Request) says how well the mapper fits a request; when several mappers can map it, the one with the highest score wins. The root mapper of an application is a SystemMapper that holds the built-in mappers and the ones you add with mount() and mountPage(). The mappers are listed in Request mappers.