Play’s Java APIs provide two ways of intercepting action calls. The first is called ActionCreator, which provides a createAction method that is used to create the initial action used in action composition. It handles calling the actual method for your action, which allows you to intercept requests.

The second way is to implement your own HttpRequestHandler, which is the primary entry point for all HTTP requests in Play. This includes requests from both Java and Scala actions.

createAction: Takes the request and the controller’s action method associated with the passed request. The action can either be the first or the last action depending on the configuration setting play.http.actionComposition.executeActionCreatorActionFirst.

wrapAction: Takes the action to be run and allows for a final global interceptor to be added to the action. This method is deprecated since the same can be achieved using createAction and the above setting.

Note: If you are implementing a custom ActionCreator because you need to apply a cross cutting concern to an action before it is executed, creating a filter is a more idiomatic way of achieving the same.

A custom action creator can be supplied by creating a class in the root package called ActionCreator that implements play.http.ActionCreator, for example:

If you don’t want to place this class in the root package, or if you want to be able to configure different action handlers for different environments, you can do this by configuring the play.http.actionCreator configuration property in application.conf:

play.http.actionCreator = "com.example.MyActionCreator"

Note: If you are also using action composition then the action returned by the createAction method is executed after the action composition ones by default. If you want to change this order set play.http.actionComposition.executeActionCreatorActionFirst = true in application.conf.

Sometimes an application will have more advanced needs that aren’t met by Play’s abstractions. When this is the case, applications can provide custom implementations of Play’s lowest level HTTP pipeline API, the HttpRequestHandler.

Providing a custom HttpRequestHandler should be a last course of action. Most custom needs can be met through implementing a custom router or a filter.

The HttpRequestHandler interface has one method to be implemented, handlerForRequest. This takes the request to get a handler for, and returns a HandlerForRequest instance containing a RequestHeader and a Handler.

The reason why a request header is returned is so that information, such as routing information, can be added to the request. In this way, the router is able to tag requests with routing information, such as which route matched the request, which can be useful for monitoring or even for injecting cross cutting functionality.

A very simple request handler that simply delegates to a router might look like this:

Note that we need to inject JavaHandlerComponents and call handler.withComponents for the Java handler. This is required for Java actions to work. This will also be handled for you automatically if you extend DefaultHttpRequestHandler and call super.handlerForRequest().

Note that HttpRequestHandler currently has two legacy methods with default implementations that have since been moved to ActionCreator.

A custom http handler can be supplied by creating a class in the root package called RequestHandler that implements HttpRequestHandler.

If you don’t want to place your request handler in the root package, or if you want to be able to configure different request handlers for different environments, you can do this by configuring the play.http.requestHandler configuration property in application.conf: