VRaptor

A simple controller

We will call a Controller classes that contain the business model of your application. Those are classes commonly called actions or even services by other frameworks, although they don’t mean exactly the same.

With VRaptor’s jar and its dependencies in your project, create our controllers in order to receive requests and start building your project.

A simple controller looks like this:

@Controller
public class ClientsController {

    @Inject
    private ClientDao dao;

    public void form() { ... }

    public void add(Client custom) {
        dao.save(custom);
    }

    public List<Client> list() {
        return dao.listAll():
    }

    public Client view(Long id) {
        return dao.load(id);
    }
}

Into the form() method you can put the code that loads data for checkboxes, selects, etc.

Use the @Controller annotation and your public methods will be available for web requests.

You can inject your class’ dependencies using the @Inject annotation. Then CDI and VRaptor will create or locate such instances for you. As an alternative, annotate the contructor with @Inject, but you would also need to have a default constructor for that approach to work, i.e:

@Controller
public class ClientsController {

    private final ClientDao dao;

    /**
     * @deprecated CDI eyes only
     */
    protected ClientsController(){
        this(null);
    }

    @Inject
    public ClientsController(ClientDao dao){
        this.dao = dao;
    }

    // controller methods
}

There are no differences using injection by construtor or by field. But using injection via constructor can be useful when you write your unit tests, that we can explain later.

All public methods at your controller are accessible from the web. For instance, the form method can be accessed through the URI /clients/form and will redirect to the jsp /WEB-INF/jsp/clients/form.jsp.

Method parameters will be populated accordingly to the request fields received, as long as they follow a simple convention:

custom.name=Paulo Silveira 
custom.address=Vergueiro St 

That will cause Client fields name and address of add method to be filled, respectively, with Paulo Silveira and Vergueiro St, via setters or constructor, using parameters with the same names of the attributes.

An example via setter would be:

public class Client {

    private String name;
    private String address;

    public void setName(String name) {
        this.name = name;
    }

    public Client setAddress(String address) {
        this.address = address;
    }
}

Or you may prefer receive the values via constructor. This also works as long as you respect the rule of using the same names of the request parameters, for example:

public class Client {

    private final String name;
    private final String address;

    public Client(String name, String address) {
        this.name = name;
        this.address = address;
    }
}

With this, we can receive the custom as a parameter of method add and the VRaptor will care to instantiate your attributes.

public void add(Client custom) {
    dao.save(custom);
}

In this case the URL will be /clients/add and the view /WEB-INF/jsp/clients/add.jsp.

The return of your controller’s methods will automatically be exported to the view. For our list method, as the return is a list of Client, the EL accessible variable will be ${clientList}.

public List<Client> list() {
    return dao.listAll():
}

URI: /clients/list and view: /WEB-INF/jsp/clients/list.jsp.

In case you return a simple type, the exported variable’s name will start lower case. In view method example, at the return type is Client, the EL accessible variable will be ${client}. VRaptor is in charge of needed conversions so that form fields are filled with their expected types.

public Client view(Long id) {
    return dao.load(id);
}

URI: /clients/view and view: /WEB-INF/jsp/clients/view.jsp.

Please note how API independent this class is. Code is also extremely simple and testable, even with unit tests. VRaptor makes a lot of associations by default, such as:

/client/form invokes form()
/client/add invokes add(client) populating the client object with request parameters
/clients/list invokes list() and return ${clientList} to the JSP
/clients/view?id=3 invokes view(3l) and return ${client} to the JSP

Later, you will learn how simple it is to change the URI from /clients/view?id=3 to /clients/view/3, making it more friendly and elegant. In addition, there are alternatives like vraptor-routes that allows setting your routes in a properties file. If you want, you can read more about this supplement in our plugins page.

VRaptor will also be able to inject the ClientDao on the controller. You are good to go! Learn more about at the 10 minute guide.

Questions

While studying VRaptor, should you have any doubts please refer to questions.vraptor.org, or visit our discussion list at discussion list.

You can see all this and many other features in a practical way in our sample project, the vraptor-music-jungle

Next steps

You can also read about dependencies and prerequisites.