JAVA WEB - Iniciando Com Web Service RESTful

Como construir um Web Service com arquitetura "RESTful" simples e fácil? Do que preciso?
Com a necessidade de desenvolver um simples Web Service que se utilizasse das facilidades da utilização da arquitetura "RESTful", fui em busca de tutoriais e percebendo que temos poucas opções de tutoriais para desenvolvimento simples com esta ferramenta em português, resolvi criar esse passo-a-passo para auxiliar quem tem a necessidade de desenvolver algo simples, rápido e fácil com REST.

Sem mais enrolação, vamos ao passo-a-passo!!


PRÉ-REQUISITOS:

* Para este tutorial faça o download da IDE Eclipse para desenvolvedores JAVA EE.

* Também iremos utilizar o framework Jersey/JAX-RS que, de forma resumida, é uma especificação API JAVA para implementação de Web Services REST utilizando anotações (annotations). Faça o download da distribuição Jersey AQUI.

* Precisamos também de qualquer "Web Container" para gerenciamento de nossa aplicação. Você pode utilizar qualquer um disponível no mercado como Apache TomCat, JBoss ou até mesmo o Google App Engine. Neste tutorial utilizarei o JBoss AS 7 que além de ser um dos mais "poderosos" é totalmente free. Você pode baixar o JBoss Aplication Server 7 AQUI.

* Certifique-se de ter o JAVA instalado em sua máquina. Caso não o tenha, baixe e instale o JAVA Development Kit 7 (JDK).


INICIANDO:

1) Na IDE Eclipse, Clique em "File", posicione o mouse sobre "New" e selecione "Dynamic Web Project":

2) Na tela que se segue, dê um nome para seu projeto. No meu caso, como estou aproveitando a necessidade de criar um Web Service para uma de minhas aplicações Android que se chama ZapZap Commedy (lançada em breve rsrs) para criar o tutorial, juntarei o útil ao agradável e na medida que vou desenvolvendo, vou incrementando o tutorial. Sendo assim, nomearei o meu projeto como ZapZap-WS. As demais configurações, siga a imagem abaixo:

3) Clique em "Next" por duas vezes e na última tela de "setup" do projeto marque a opção "Generate web.xml deployment descriptor" para que o arquivo "web.xml" referente à descrição e configuração de nosso projeto seja criado automaticamente e clique em "Finish":

4) Copie todos os arquivos ".jar" das pastas "jaxrs-ri/api, jaxrs-ri/ext e jaxrs-ri/lib" referentes ao Jersey/JAX-RS ao qual foi disponibilizado o link para download na sessão de "pré-requisitos" deste tutorial, para a pasta "WebContent/WEB-INF/lib":

5) Defina o pacote principal de sua aplicação clicando na pasta "src" de seu projeto com o botão direito do mouse, posicione o mouse na opção "new" e selecione "package". Lembre-se que no padrão WEB, o pacote principal de uma aplicação deve ser composto de "com.empresa.projeto", porém como nem todas as pessoas que decidem construir um Web Service tem uma empresa, sugiro utilizar seu nome ou sobrenome. No meu caso ficará assim:

6) Dentro do pacote principal de seu projeto, crie uma classe simples chamada "HelloWorld.java" a qual utilizaremos para exemplificar as chamadas a serviços REST. Para entender melhor o que faremos nessa classe, precisamos relembrar o que significa cada "Annotation" (anotação) do Jersey que utilizaremos neste tutorial. Para isso, segue abaixo o código fonte da classe implementada comentado com explicações do que cada "Annotation" significa:

 import javax.ws.rs.GET;  
 import javax.ws.rs.Path;  
 import javax.ws.rs.Produces;  
 import javax.ws.rs.core.MediaType;  

 /**  
  * @author jonathan.s.santos  
  *  
  * @version 03/10/2014  
  * @project ZapZap-WS  
  */  
 //Assim como todo link é formado por "schema://host/path" (http://www.abobrinha.com/path)   
 //com a anotação "@path" definimos o "path" (caminho) que será incluso após o host   
 //para acessar esta classe.  
 @Path("/helloworld")  
 public class HelloWorld{  
        
      //Este método será acessado via método "GET". Lembre-se, em protocolo HTTP o método  
      //"GET" é utilizado para buscar coisas, o "PUT" para incluir, o "POST" para editar   
      //e "DELETE" para excluir.  
      @GET  
      //Indica que este método, ao ser chamado, retornará um texto comum.  
      @Produces(MediaType.TEXT_PLAIN)  
      public String helloWordTexto() {  
       return "Hello Word!! (texto)";  
      }  
   
      //Este método será acessado via método "GET".  
      @GET  
      //Indica que este método, ao ser chamado, retornará um XML.  
      @Produces(MediaType.TEXT_XML)  
      public String helloWordXML() {  
       return "<?xml version=\"1.0\"?> "  
                 + "<hello> Hello Word!! (xml) </hello>";  
      }  
   
      //Este método será acessado via método "GET".  
      @GET  
      //Indica que este método, ao ser chamado, retornará um HTML.  
      @Produces(MediaType.TEXT_HTML)  
      public String helloWordHTML() {  
       return "<html>"  
                      + "<title>Hello Word</title> "  
                      + "<body>"  
                           + "<h1>Hello Word (html)</h1>"  
                      + "</body>"  
                 + "</html> ";  
      }  
 }  
   

7) Estamos quase lá. Precisamos agora registrar nosso "Servlet" Jersey que tratará as requisições REST ao nosso Web Service. Para isso, abra o arquivo "WebContent/WEB-INF/web.xml" de seu projeto e adicione o seguinte código:

 <?xml version="1.0" encoding="UTF-8"?>  
 <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
      xmlns="http://java.sun.com/xml/ns/javaee"   
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"   
      id="WebApp_ID" version="3.0">  
    
  <!-- NOME DO PROJETO A SER EXIBIDO -->  
  <display-name>ZapZap-WS</display-name>  
    
  <!-- DECLARAÇÃO DO SERVLET -->  
  <servlet>  
       <!-- NOME DO SERVLET -->  
   <servlet-name>Web Service REST</servlet-name>  
   <!-- CLASSE JERSEY RESPONSAVEL POR GERENCIAR AS REQUISIÇÕES -->  
   <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>  
   <!-- REGISTRO DE PACOTE PADRÃO DA APLICAÇÃO -->  
   <init-param>  
     <param-name>jersey.config.server.provider.packages</param-name>  
     <param-value>com.jonathan.zapzapws</param-value>  
   </init-param>  
   <!-- ORDEM DE CARREGAMENTO DOS RECURSOS -->  
   <load-on-startup>1</load-on-startup>  
  </servlet>  
    
  <!-- MAPEAMENTO DE REQUISIÇÕES, OU SEJA, DIZEMOS AQUI QUE TUDO  
  QUE FOR REQUISITADO COM O PREFIXO "/res/" SERÁ TRATADO PELO  
  MEU SERVLET DE NOME "Web Service REST" DEFINIFO ACIMA -->  
  <servlet-mapping>  
   <servlet-name>Web Service REST</servlet-name>  
   <url-pattern>/rest/*</url-pattern>  
  </servlet-mapping>  
 </web-app>  

8) Agora devemos apenas adicionar nosso "Application Server" (nesse caso o JBoss AS 7) como gerenciador de contêineres de nossa aplicação. Para isso, primeiramente tornaremos visível a aba de servidores de nossa aplicação selecionando a opção "Window -> Show View -> Servers" no Eclipse como mostra a imagem abaixo:

9) Na aba de servidores aberta, clique dentro com o botão direito do mouse e selecione "New -> Server":

10) Se a opção para adicionar o server JBoss AS 7.1 não estiver disponível, você precisará instalar o JBoss Tools Plugin em seu Eclipse. Se a opção apareceu, passe para o passo 11) deste tutorial. Para instalar o JBoss Tools Plugin em seu Eclipse, selecione "Help -> Eclipse Markeplace..." como mostra a figura abaixo:

Pesquise por "JBoss" e clique na opção "Install" referente ao Eclipse que esteja utilizando. No caso deste tutorial, estamos utilizando o Eclipse Luna.

Após instalar tudo, reinicie seu Eclipse e volte para o passo 9) deste tutorial.

11) Selecione a opção JBoss AS 7.1:

12) Clique em "Next" duas vezes até abrir a tela seguinte. Na tela que se segue, clique em "Browser" e indique o caminho onde você descompactou o arquivo baixado referente ao "JBoss AS 7.1". Selecione a opção "Alternate JRE" e selecione a opção "jre7" se estiver disponível, senão, apenas deixa a opção "Execution Environment" e clique em "Next".

13) Adicione seu projeto ao gerenciador e clique em "Finish":

14) O JBoss AS 7.1 por sua vez, já vem pré-configurado para utilizar os serviços RESTeasy, isso pra quem vai desenvolver Web Services REST com estrutura EASY é ótimo! Porém pra nós, além de desnecessário, causa conflitos de bibliotecas. Para resolver tais conflitos de bibliotecas, devemos configurar nosso JBoss AS 7.1 para não utilizar tais bibliotecas próprias e sim utilizar as bibliotecas do Jersey que incluímos no nosso projeto anteriormente. Para fazer isso, exclua ou comente as seguintes linhas dos seguintes arquivos (número das linhas para mais fácil identificação) em seu JBoss:

Arquivo "jboss-as-7.1.1.Final/modules/javax/ws/rs/api/main/module.xml"

 27 <resource-root path="jboss-jaxrs-api_1.1_spec-1.0.0.Final.jar"/>  

Arquivo "jboss-as-7.1.1.Final/domain/configuration/domain.xml"

 13 <extension module="org.jboss.as.jaxr"/>  
   
 14 <extension module="org.jboss.as.jaxrs"/>  
   
 149 <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>  
   
 405 <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>  
   
 679 <subsystem xmlns="urn:jboss:domain:jaxr:1.1">  
 680 <connection-factory jndi-name="java:jboss/jaxr/ConnectionFactory"/>  
 681 </subsystem>  
 682 <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>  
   
 1029 <subsystem xmlns="urn:jboss:domain:jaxr:1.1">  
 1030 <connection-factory jndi-name="java:jboss/jaxr/ConnectionFactory"/>  
 1031 </subsystem>  
 1032 <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>  

Arquivo "jboss-as-7.1.1.Final/standalone/configuration/standalone.xml"

 Tudo relacionado à "jaxr" e "jaxrs".  

15) Vamos testar se tudo está funcionando? Clique com o botão direito do mouse em cima do Servidor de Aplicação que acabamos de adicionar e selecione "Start":

15) Aguarde o servidor inicializar. Quando a seguinte instrução aparecer no "console" é porque seu servidor está pronto para ser acessado! (caso não esteja visualizando o console, clique em "Window -> Show View -> Console" para abri-lo.

16) Agora chegou a hora da verdade!! Depois que o servidor já estiver sido inicializado, abra seu navegador de internet e vamos acessar seu WebService. O link de acesso à sua aplicação é composto por "schema://host/path" (já vimos isso anteriormente). Nosso "schema" padrão para protocolo HTTP (utilizado em serviços REST) é o prório "http". O nosso "host", como não hospedamos ainda nosso servidor ele está sendo executado localmente em nossa máquina, por isso o mesmo é "localhost" e a porta de rede ao qual o mesmo deverá está sendo executado é a 8080. O nosso "path" é composto pelo nome do projeto, indice de requisição que definimos no arquivo "web.xml" e o "path" que definimos na nossa classe "HelloWord.java" via anotação. Seguindo essas diretivas, acessamos nosso Web Service pelo link
http://localhost:8080/ZapZap-WS/rest/helloworld:

É isso aí!! Se tudo ocorreu bem e você seguiu todo o passo-a-passo, certamente terá em mãos um Web Service construído com arquitetura REST utilizando as bibliotecas Jersey/JAX-RS!!

Faça o download do código fonte da aplicação AQUI.