Fork me on GitHub

Another approach to handling a request and producing a response is using Controllers. After routing has determined what controller to use, an action method will be invoked. In Pippo, controllers are instances of Controller.

How to use

Defining a new controller is simple:

public class ContactsController extends Controller {

    private ContactService contactService;

    public ContactsController() {
        contactService = new InMemoryContactService();

//    @Produces(Produces.HTML)
    public void index() {
        // inject "user" attribute in session
        getRouteContext().setSession("user", "decebal");

        // send a template with name "contacts" as response
            .bind("contacts", contactService.getContacts())

    @GET("/uriFor/{id: [0-9]+}")
    public String uriFor(@Param int id, @Header String host, @Session String user) {
        System.out.println("id = " + id);
        System.out.println("host = " + host);
        System.out.println("user = " + user);

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("id", id);

        String uri = getApplication().getRouter().uriFor("api.get", parameters);

        return "id = " + id + "; uri = " + uri;

    public List<Contact> getAll() {
        return contactService.getContacts();

    @GET("/api/{id: [0-9]+}")
    public Contact get(@Param int id) {
        return contactService.getContact(id);

public class FilesController extends Controller {

    public void index() {
        // send a template with name "files" as response

    public File download() {
        // send a file as response
        return new File("pom.xml");

    public String upload(FileItem file) {
        // send a text (the info about uploaded file) as response
//        return file.toString();
        return new StringBuilder()


Methods attached to the controller (for example index from above snippet) are known as action methods. When Pippo receives a request, it will create a new instance of the controller and call the appropriate action method. You can register a controller’s action in application with a simple line:

public class MyApplication extends ControllerApplication {

    protected void onInit() {
        // add controller(s)
        addControllers(ContactsController.class); // one instance for EACH request
        // or
        addControllers(new ContactsController()); // one instance for ALL requests

public class ControllerDemo {

    public static void main(String[] args) {
        Pippo pippo = new Pippo(new MyApplication());


DON’T forget to add pippo-controller module as dependency in your project. If you use Maven, your pom.xml must contains above lines:



With few words a method parameter extractor create a method parameter value from the RouteContext and the MethodParameter (an useful wrapper over Parameter class from Java).

For example, see the controller route defined with method:

void uriFor(@Param int id, @Param String action, @Header String host, @Session String user);

When a request comes for the above route, Pippo uses extractors to extract values for the method’s parameters: id, action, host and user.

Pippo comes with some builtin extractors that extract values from multiple locations:

  • Param extracts value from the request parameter (similar with request.getParamater())
  • Header extracts value from the request header
  • Session extracts value from a session’s attribute
  • Body extract value from the request body cia a Content Type Engine (e.g. JSON, XML)

They are also other builtin extractors that are not presented in this post. The beauty of Pippo here is that you can define any extractor you want/need with no effort.

All you must to do is to implement MethodParameterExtractor interface:

public interface MethodParameterExtractor {

     * Returns true if this extractor is applicable to the given {@link MethodParameter}.
    boolean isApplicable(MethodParameter parameter);

     * Extract a value from a {@link MethodParameter} for a specified {@link RouteContext}.
    Object extract(MethodParameter parameter, RouteContext routeContext);


Example, BeanExtractor that create a bean from the request parameters:

public class BeanExtractor implements MethodParameterExtractor {

    public boolean isApplicable(MethodParameter parameter) {
        return parameter.isAnnotationPresent(Bean.class);

    public Object extract(MethodParameter parameter, RouteContext routeContext) {
        Class<?> parameterType = parameter.getParameterType();

        return routeContext.createEntityFromParameters(parameterType);


After you create the new extractor you should add it to Pippo:

  • automatically (annotate your extractor with @MetaInfServices)
  • manually (via ControllerApplication.addExtractors(extractor) method)

You are not forced to create an Extractor using only annotation (it’s not annotation driven).

Below, I present you a new extractor, FileItemExtractor that does’t use annotation (it looks after parameter type).

public class FileItemExtractor implements MethodParameterExtractor {

    public boolean isApplicable(MethodParameter parameter) {
        return FileItem.class == parameter.getParameterType();

    public Object extract(MethodParameter parameter, RouteContext routeContext) {
        String name = parameter.getParameterName();

        return routeContext.getRequest().getFile(name);


The signature for a possible controller’s route that uses a FileItemExtractor can might be:

void upload(FileItem file);

Parameter name

The Controller module may depend on the -parameters flag of the Java 8 javac compiler. This flag embeds the names of method parameters in the generated .class files.

By default Java 8 does not compile with this flag set so you must specify javac compiler arguments for Maven and your IDE.


So, if you you compile with -parameters flag you can define the controller method like:

void invoice(@Param orderId) { ... }

instead of:

void invoice(@Param("orderId") orderId) { ... }

If you use the first variant without -parameters flag on compile, you will receive an exception like:

ro.pippo.core.PippoRuntimeException: Method 'acme.controller.MyController::invoice' parameter 0 does not specify a name!
	at ro.pippo.controller.extractor.ParamExtractor.getParameterName(
	at ro.pippo.controller.extractor.ParamExtractor.extract(
	at ro.pippo.controller.ControllerRouteHandler.prepareMethodParameters(
	at ro.pippo.controller.ControllerRouteHandler.handle(
	at ro.pippo.core.route.DefaultRouteContext.handleRoute(
	at ro.pippo.core.route.RouteDispatcher.onRouteDispatch(
	at ro.pippo.core.route.RouteDispatcher.dispatch(
	at ro.pippo.core.PippoFilter.processRequest(

Implementation details

Advanced features (Extractor, Interceptor, …) and technical aspects are presented in details here.

You can see a demo here