From a8557612d8ab57e2f3baacfd4a518898b083b39a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cassund=C3=A9?= Date: Sat, 7 Jul 2018 20:13:29 -0300 Subject: [PATCH 1/2] added new informations about controller-rest-pt --- .../content/pt/docs/controllers-rest.html | 156 +++++++++--------- 1 file changed, 79 insertions(+), 77 deletions(-) diff --git a/vraptor-site/content/pt/docs/controllers-rest.html b/vraptor-site/content/pt/docs/controllers-rest.html index fe99c0fa9..98678c8f4 100644 --- a/vraptor-site/content/pt/docs/controllers-rest.html +++ b/vraptor-site/content/pt/docs/controllers-rest.html @@ -2,15 +2,15 @@ title: Controllers REST --- -#O que são Controllers? +#O que são Controllers Rest? -Um controller é uma classe que disponibiliza recursos a nossos clientes. No +Um controller Rest é uma classe que disponibiliza recursos a nossos clientes. No caso de uma aplicação Web baseada no VRaptor, um controller deve ser anotado com a anotação `@Controller`. Assim que o programador insere tal anotação em seu código, todos os métodos públicos desse recurso se tornam acessíveis através de chamadas do tipo GET ou POST a URIs específicas. -O exemplo a seguir mostra um recurso chamado `ClienteController` que possui métodos para diversas funcionalidades ligadas a um cliente. Simplesmente criar essa classe e os métodos faz com que as URLs `/cliente/adiciona`, `/cliente/lista`, `/cliente/visualiza`, `/cliente/remove` e `/cliente/atualiza` sejam disponibilizadas, cada uma invocando o respectivo método em sua classe. +O exemplo a seguir mostra um recurso chamado `ClienteController` que possui métodos para diversas funcionalidades ligadas a um cliente. Simplesmente ao anotar a classe com `@Controller` e os métodos com `@Get` ou `@Post` por exemplo, faz com que as URLs `/cliente/adiciona`, `/cliente/lista`, `/cliente/visualiza`, `/cliente/remove` e `/cliente/atualiza` sejam disponibilizadas, cada uma invocando o respectivo método em sua classe. ~~~ #!java @@ -33,6 +33,76 @@ } ~~~ +##Métodos HTTP + +Desenvolvendo sua aplicação com recursos REST, o ideal é aproveitar a semântica +de cada método HTTP. Portanto às vezes precisamos usar métodos como `GET`, +`POST`, `PUT` etc para acessar uma mesma URI. Para atingir esse objetivo, +utilizamos as anotações `@Get`, `@Post`, `@Delete`, etc que também permitem +configurar uma URI diferente da URI padrão, da mesma forma que a anotação +`@Path`. O exemplo a seguir altera os padrões de URI do `ClienteController` +para utilizar duas URIs distintas, com diversos métodos HTTP: + +~~~ +#!java +@Controller +public class ClienteController { + + @Post("/cliente") + public void adiciona(Cliente cliente) {...} + + @Path("/") + public List lista() { + return ... + } + + @Get("/cliente") + public Cliente visualiza(Cliente cliente) { + return ... + } + + @Delete("/cliente") + public void remove(Cliente cliente) { ... } + + @Put("/cliente") + public void atualiza(Cliente cliente) { ... } +} +~~~ + +Como você pode notar, utilizamos os métodos HTTP + uma URI específica para identificar cada um dos métodos da nossa classe Java. + +**Obs:** + +No momento de criar os links e formulários HTML devemos tomar um cuidado **muito importante** pois os browsers só dão suporte aos métodos `POST` e `GET` por meio de formulários hoje em dia. Por isso, você deverá criar as requisições para métodos do tipo `DELETE`, `PUT` etc usando JavaScript ou passando um parâmetro extra, chamado `_method`. O último só funciona em requisições `POST`. Esse parâmetro sobrescreverá o método HTTP real sendo invocado. + +O exemplo a seguir mostra um link para o método `visualiza` da classe `ClienteController`: + +~~~ +#!jsp +ver cliente 5 +~~~ + +Agora um exemplo de como invocar o método de adicionar um cliente: + +~~~ +#!jsp +
+ + +
+~~~ + +E, note que para permitir a remoção pelo método `DELETE`, temos que usar o parâmetro `_method`, uma vez que o browser ainda não suporta tais requisições: + +~~~ +#!jsp +
+ + +
+~~~ + + ##Parâmetros dos métodos Você pode receber parâmetros nos métodos dos seus controllers, e se o objeto usar a convenção de java beans (getters e setters para os atributos da classe), você pode usar pontos para navegar entre os atributos. Por exemplo, no método: @@ -70,13 +140,13 @@ Por vezes você deseja compartilhar um componente entre todos os usuários, entre todas as requisições de um mesmo usuário ou a cada requisição de um usuário. -Para definir em que escopo o seu componente vive, basta utilizar as anotações -`@ApplicationScoped`, `@SessionScoped`, `@RequestScoped`, `@Dependent` e -`@Conversation`. Caso nenhuma anotação seja utilizada, o VRaptor assume que seu -componente ficará com escopo dependent, isto é, você terá um novo componente a -cada ponto de injeção. -Esses escopos estão definidos na especificação do CDI. Para mais informações +Para definir um escopo ao seu componente, basta utilizar as anotações +`@ApplicationScoped`, `@SessionScoped`, `@RequestScoped`, `@Dependent` e `@Conversation`. Caso nenhuma anotação seja utilizada, o VRaptor assume que seu componente ficará com escopo dependent, isto é, você terá um novo componente a cada ponto de injeção. + +Um dos princípios da Arquitetura REST e que seus `recursos` sejam `stateless` ou seja não podem guardar estado, com isso todos os `@Controllers` por padrão serão do tipo `@ResquestScoped` + +Na especificação CDI. existe vários outros escopos, para mais informações veja a página sobre componentes. ##@Path @@ -119,74 +189,6 @@ |void listaTudo() | URI: /clientes/todosOsClientes {: .content-table} -##Métodos HTTP - -Desenvolvendo sua aplicação com recursos REST, o ideal é aproveitar a semântica -de cada método HTTP. Portanto às vezes precisamos usar métodos como `GET`, -`POST`, `PUT` etc para acessar uma mesma URI. Para atingir esse objetivo, -utilizamos as anotações `@Get`, `@Post`, `@Delete`, etc que também permitem -configurar uma URI diferente da URI padrão, da mesma forma que a anotação -`@Path`. O exemplo a seguir altera os padrões de URI do `ClienteController` -para utilizar duas URIs distintas, com diversos métodos HTTP: - -~~~ -#!java -@Controller -public class ClienteController { - - @Post("/cliente") - public void adiciona(Cliente cliente) {...} - - @Path("/") - public List lista() { - return ... - } - - @Get("/cliente") - public Cliente visualiza(Cliente cliente) { - return ... - } - - @Delete("/cliente") - public void remove(Cliente cliente) { ... } - - @Put("/cliente") - public void atualiza(Cliente cliente) { ... } -} -~~~ - -Como você pode notar, utilizamos os métodos HTTP + uma URI específica para identificar cada um dos métodos da nossa classe Java. - -No momento de criar os links e formulários HTML devemos tomar um cuidado **muito importante** pois os browsers só dão suporte aos métodos `POST` e `GET` por meio de formulários hoje em dia. Por isso, você deverá criar as requisições para métodos do tipo `DELETE`, `PUT` etc usando JavaScript ou passando um parâmetro extra, chamado `_method`. O último só funciona em requisições `POST`. Esse parâmetro sobrescreverá o método HTTP real sendo invocado. - -O exemplo a seguir mostra um link para o método visualiza de cliente: - -~~~ -#!jsp -ver cliente 5 -~~~ - -Agora um exemplo de como invocar o método de adicionar um cliente: - -~~~ -#!jsp -
- - -
-~~~ - -E, note que para permitir a remoção pelo método `DELETE`, temos que usar o parâmetro `_method`, uma vez que o browser ainda não suporta tais requisições: - -~~~ -#!jsp -
- - -
-~~~ - - ##Path com injeção de variáveis Em diversos casos, desejamos que a URI que identifica nosso recurso tenha como parte de seu valor, por exemplo, o identificador único do nosso recurso. From b34d6a3a5429464e6950517ca1f562b2a2177b47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cassund=C3=A9?= Date: Sun, 8 Jul 2018 15:03:00 -0300 Subject: [PATCH 2/2] changed controller-rest page - change first topic - change position of topic "http method" --- .../content/en/docs/controllers-rest.html | 158 +++++++++--------- 1 file changed, 81 insertions(+), 77 deletions(-) diff --git a/vraptor-site/content/en/docs/controllers-rest.html b/vraptor-site/content/en/docs/controllers-rest.html index 248565999..212e2b2a5 100644 --- a/vraptor-site/content/en/docs/controllers-rest.html +++ b/vraptor-site/content/en/docs/controllers-rest.html @@ -2,7 +2,7 @@ title: REST Controllers --- -#What are Controllers? +#What are REST Controllers? A controller is a class that can provide resources to be accessed by your clients. With VRaptor, a controller must be annotated with `@Controller`. All @@ -10,8 +10,7 @@ specific URIs. The following example shows a controller named `CustomerController`, which -provides several operations over customers. Creating the class below with all -its methods instantly make the URIs `/customer/add`, `/customer/list`, +provides several operations over customers. When annotating the class with `@Controller` and methods with `@Get` or `@Post` for example, make the URIs `/customer/add`, `/customer/list`, `/customer/show`, `/customer/remove` and `/customer/update` available, each one invoking the respective method. @@ -37,6 +36,82 @@ } ~~~ +##HTTP methods + +The best practice when designing REST resources is to use the sematincs of each +HTTP method. Therefore, eventually we need to use methods like `GET`, `POST`, +`PUT` etc, for the same URI. In order to accomplish that, we use annotations +`@Get`, `@Post`, `@Delete` etc, which also allows us to configure a custom URI +in the same way as `@Path`. The following example changes the default URIs for +`CustomerController`. Now we specify two different URIs for different HTTP +methods: + +~~~ +#!java +@Controller +public class CustomerController { + @Post("/") + public void add(Customer customer) { } + + @Path("/") + public List list() + return ... + } + + @Get("/customer") + public Customer show(Customer customer) { + return ... + } + + @Delete("/customer") + public void remove(Customer customer) { ... } + + @Put("/customer") + public void update(Customer customer) { ... } + +} +~~~ + +As you can see, we used HTTP methods + a specific URI to identify each method +in our Java class. + +**Obs:** + +We must be **very careful** when creating hyperlinks and HTML forms, because web +browsers currently support only `POST` and `GET` methods. For that reason, requests +for methods `DELETE`, `PUT` etc should be performed through JavaScript, or by adding +an extra parameter called `_method`. The latter one only works on `POST` requests. +This parameter will overwrite the real HTTP method being invoked. + +The following example creates a link to show one customer's data: + +~~~ +#!jsp +show customer 5 +~~~ + +Now an example on how to invoke the method to add a customer: + +~~~ +#!jsp +
+ + +
+~~~ + +Notice that if we want to remove a customer using the `DELETE` HTTP method, we +have to use the `_method` parameter, since browsers still don't support that kind +of requests: + +~~~ +#!jsp +
+ + +
+~~~ + ##Method parameters You can receive parameters on your controller methods, and if those parameters @@ -86,9 +161,11 @@ assumes the dependent scope, meaning a fresh instance will be created for each time it needs to be injected. +A principle of Rest Architecture explains that a controller must be `stateless`, ie, a controller only live *one* request. + Those scopes are from CDI specification, see the [Java EE 7 documentation](http://docs.oracle.com/javaee/7/tutorial/partcdi.htm) -for more information. +for more information and visit this page components. ##@Path @@ -133,79 +210,6 @@ |void listAll() | URI: /customers/allCustomers| {: .content-table} -##HTTP methods - -The best practice when designing REST resources is to use the sematincs of each -HTTP method. Therefore, eventually we need to use methods like `GET`, `POST`, -`PUT` etc, for the same URI. In order to accomplish that, we use annotations -`@Get`, `@Post`, `@Delete` etc, which also allows us to configure a custom URI -in the same way as `@Path`. The following example changes the default URIs for -`CustomerController`. Now we specify two different URIs for different HTTP -methods: - -~~~ -#!java -@Controller -public class CustomerController { - @Post("/") - public void add(Customer customer) { } - - @Path("/") - public List list() - return ... - } - - @Get("/customer") - public Customer show(Customer customer) { - return ... - } - - @Delete("/customer") - public void remove(Customer customer) { ... } - - @Put("/customer") - public void update(Customer customer) { ... } - -} -~~~ - -As you can see, we used HTTP methods + a specific URI to identify each method -in our Java class. - -We must be **very careful** when creating hyperlinks and HTML forms, because web -browsers currently support only `POST` and `GET` methods. For that reason, requests -for methods `DELETE`, `PUT` etc should be performed through JavaScript, or by adding -an extra parameter called `_method`. The latter one only works on `POST` requests. -This parameter will overwrite the real HTTP method being invoked. - -The following example creates a link to show one customer's data: - -~~~ -#!jsp -show customer 5 -~~~ - -Now an example on how to invoke the method to add a customer: - -~~~ -#!jsp -
- - -
-~~~ - -Notice that if we want to remove a customer using the `DELETE` HTTP method, we -have to use the `_method` parameter, since browsers still don't support that kind -of requests: - -~~~ -#!jsp -
- - -
-~~~ ##Path with variable injection