VRaptor

Um Controller simples

Chamaremos de Controller as classes contendo a lógica de negócio do seu sistema. São as classes que alguns frameworks podem vir a chamar de actions ou services, apesar de não significarem exatamente a mesma coisa.

Com o jar e dependências do VRaptor em seu projeto, basta criar os seus controllers para receber as requisições e começar a construir seu sistema.

Um controller simples seria:

@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);
    }
}

Dentro do método form() podemos inserir os códigos que carregam os dados para checkboxes, selects, etc

Anotando seu controller com @Controller, seus métodos públicos ficarão disponíveis para receber requisições web.

Você pode injetar as dependências da sua classe adicionando a anotação @Inject, e o VRaptor com CDI vai se encarregar de criar ou localizar essas dependências pra você. Outra alternativa é adicionar o @Inject no construtor de sua classe, para que isso funcione você precisará adicionar também um construtor default, por exemplo:

@Controller
public class ClientsController {

    private final ClientDao dao;

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

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

    // métodos do controller
}

Para a aplicação não há diferença usar a injeção via construtor ou no atributo da classe. Porém utilizando a injeção via construtor será útil para você escrever seus testes unitários, o que veremos mais adiante.

Todos os métodos públicos do seu controller estarão acessíveis pela web. Por exemplo, o método form pode ser acessado pela URI /clients/form e vai redirecionar para a jsp /WEB-INF/jsp/clients/form.jsp.

Você pode receber parâmetros no seu método e o VRaptor tentará popular os campos dos parâmetro de acordo com a requisição. Se houver na requisição:

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

Então os campos name e address do parâmetro Client que chamamos de custom no método add serão populados com Paulo Silveira e R.Vergueiro via setters ou construtor, utilizando parâmetros com os mesmos nomes dos atributos.

Um exemplo via setters seria:

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;
    }
}

Ou você pode preferir receber os valores pelo construtor. Isso também funciona desde que respeite a regra de usar os mesmos nomes dos parâmetros do request, por exemplo:

public class Client {

    private final String name;
    private final String address;

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

Com isso podemos receber o custom como parâmetro do método add e o VRaptor vai cuidar de instanciar seus atributos:

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

Para este caso a URL será /clients/add e a view /WEB-INF/jsp/clients/add.jsp.

O retorno dos métodos do controller são exportados para a view. No caso do nosso método list, como o retorno é uma lista de clientes, a variável acessível no jsp será ${clientList}.

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

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

Se o retorno for um tipo simples, o nome da variável exportada será o nome da classe com a primeira letra minúscula. Como o método view retorna um Client, a variável na jsp será ${client}. Outro ponto é que devemos ter um parâmetro da requisição id=5 por exemplo, e o VRaptor vai fazer a conversão do parâmetro em Long, e passar como parâmetro do método.

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

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

Repare como essa classe está completamente independente da API de javax.servlet. O código também está extremamente simples e fácil de ser testado como unidade. O VRaptor já faz várias associações para as URIs como default, por exemplo:

/client/form invoca form()
/client/add invoca add(client) populando o objeto client com os parâmetros da requisição
/clients/list invoca list() e devolve ${clientList} ao JSP
/clients/view?id=3 invoca view(3l) e devolve ${client} ao JSP

Mais para a frente veremos como é fácil trocar a URI /clients/view?id=3 por /clients/view/3, deixando a URI mais amigável e elegante. Além disso, existem alternativas como o vraptor-routes para que você defina suas rotas em um arquivo de configuração. Se quiser, pode ler mais sobre esse complemento em nossa página de plugins.

O ClientDao será injetado pelo VRaptor, como também veremos adiante. Você já pode passar para o Guia inicial de 10 minutos.

Dúvidas

Se durante a leitura da documentação você tiver dúvidas, procure ajuda no GUJ ou acesse nossa lista de discussão.

Você pode também ver tudo isso e muitos outros recursos de forma prática em nosso projeto de exemplo, o vraptor-music-jungle

Próximas etapas

Você pode ler um pouco mais sobre as dependências e pré requisitos.