Introdução aos serviços Web RESTful no Tomcat

REST (REpresentational State Transfer) é um estilo de arquitetura para sistemas de hipermídia distribuídos, como a World Wide Web. O conceito dos recursos identificados por identificadores de recursos universais (URIs) é central para a arquitetura RESTful. Esses recursos podem ser manipulados usando uma interface padrão, tal como HTTP, e as informações são trocadas usando representações desses recursos.

No tutorial Introdução aos serviços Web RESTful no GlassFish, você primeiro aprendeu um pouco sobre o REST e depois viu como o NetBeans IDE 6.0 dá suporte a esse estilo de arquitetura. Para simplificar, esse tutorial é especificamente para o servidor da aplicação GlassFish. Para executar os serviços Web RESTful em um servidor Tomcat, você precisa realizar inúmeras tarefas de configuração adicionais. Este tutorial usa os mesmos códigos-fonte que Introdução aos serviços Web RESTful no GlassFish e mostra como implantá-los em um servidor da aplicação Tomcat.

Conteúdo

• Introdução
• Copiando as bibliotecas para o Tomcat
• Gerando classes de entidade de um banco de dados
• Adicionando a biblioteca do link superior ao projeto
• Gerando serviços Web RESTful a partir de classes de entidade
• Configurando o arquivo de persistência
• Testando os serviços Web RESTful
• Adicionando um recurso Google Map

Para seguir este tutorial, você precisa dos seguintes recursos e softwares.

O Tomcat pode ser instalado, opcionalmente, com a distribuição Web e Java EE do NetBeans IDE. Como alternativa, você pode visitar a página de downloads do Apache Tomcat .

Este tutorial também requer o plug-in Serviços Web RESTful. No IDE, vá para o gerenciador de plug-ins, no menu Ferramentas, e verifique se o plug-in Serviços Web RESTful está instalado, na guia Instalado. Caso não esteja, instale-o a partir da aba Plug-ins disponíveis, como mostrado abaixo:

Introdução

Os serviços Web RESTful são serviços construídos com o estilo de arquitetura RESTful. A construção de serviços Web com a abordagem RESTful está surgindo como uma alternativa popular ao uso de tecnologias baseadas em SOAP para implantação de serviços na Internet, por ser mais leve e possuir a capacidade de transmitir dados diretamente através de HTTP.

O IDE oferece suporte ao rápido desenvolvimento de serviços Web RESTful usando a JSR 311 - API de Java para serviços Web RESTful (JAX-RS) e Jersey, a implementação de referência para JAX-RS.

Para obter informações detalhadas, consulte:

• JSR 311: JAX-RS: A API Java dos serviços Web RESTful
• Jersey, a implementação de referência JAX-RS (JSR 311) de código-fonte aberto para construir serviços Web RESTful

Além de construir serviços Web RESTful, o IDE também oferece suporte ao teste e à construção de aplicações cliente que acessem serviços Web RESTful e à criação de código para chamar serviços Web (baseados tanto em RESTful quanto em SOAP).

Veja uma lista dos recursos RESTful fornecidos pelo IDE:

1. Criação rápida de serviços Web RESTful a partir de padrões e classes de entidade JPA.
2. Geração rápida de código para chamar serviços Web como o Google Maps, a pesquisa de notícias do Yahoo e o StrikeIron, arrastando e soltando componentes da paleta de componentes RESTful.
3. Geração de stubs de cliente JavaScript de serviços Web RESTful para construir aplicações cliente RESTful.
4. Geração de cliente de teste para testar serviços Web RESTful.
5. Visualização lógica para navegação fácil de classes de implementação do serviço Web RESTful no seu projeto.

Antes de usar este tutorial, você deve usar Introdução aos serviços Web RESTful no GlassFish, que mostra como o IDE ajuda você a gerar, implementar e testar serviços Web RESTful. Este tutorial demonstra o mesmo serviço mas com etapas de configuração adicionais que você precisa para executá-lo em um servidor da aplicação Tomcat 6.0+.

Copiando as bibliotecas para o Tomcat

O Tomcat precisa de um conjunto de APIs toplink, derby e javax a fim de dar suporte aos serviços Web RESTful. Essas bibliotecas não são úteis somente para este tutorial, mas permitem que você execute serviços RESTful no Tomcat no futuro.

Na tabela seguinte, NB_HOME se refere ao diretório de instalação do Netbeans, TOMCAT_HOME ao diretório de instalação do Apache Tomcat 6.x e GLASSFISH_HOME ao diretório de instalação do Glassfish v2.

Depois de copiar essas bibliotecas, reinicie seu computador.

toplink-essentials.jar
                    toplink-essentials-agent.jar

derbynet.jar
                    derbyclient.jar

Gerando classes de entidade de um banco de dados

O objetivo deste exercício é criar um projeto e gerar classes de entidade a partir de um banco de dados.

Para criar classes de entidade a partir de um banco de dados:

1. Escolha Arquivo > Novo projeto. Em Categorias, selecione Web. Em Projetos, selecione Aplicação Web e clique em Próximo.
2. Em Nome do projeto, indique CustomerDB-Tomcat.
3. Em Servidor, selecione Apache Tomcat 6.0.x. Clique em Terminar.
4. Clique com o botão direito do mouse em CustomerDB-Tomcat e escolha Novo -> Classes de entidade do banco de dados. O assistente para Novas classes de entidade de banco de dados se abre no painel Tabelas de banco de dados.
5. No painel Tabelas do banco de dados, selecione Nova fonte de dados no campo suspenso Fonte de dados. A caixa de diálogo Criar fonte de dados se abre.
6. Digite jdbc/sample no campo Nome JNDI. No campo suspenso Conexão do banco de dados, selecione jdbc:derby://hostname:1527/sample [app on APP], como mostrado abaixo. Clique em OK. A caixa de diálogo fecha e você retorna ao painel Tabelas de banco de dados.
   
7. Em Tabelas disponíveis, selecione CUSTOMER e, em seguida, clique em Adicionar. A tabela DISCOUNT_CODE, que possui um relacionamento com a tabela CUSTOMER, também é adicionada automaticamente à lista Tabelas selecionadas. Agora você deve ver o seguinte:
   
8. Clique em Próximo. O painel Classes de entidade se abre.
9. Em Pacote, digite customer.db.tomcat.
10. Clique em Criar unidade de persistência. A caixa de diálogo Criar unidade de persistência se abre. Aceite todos os padrões e clique em Criar. Retorne ao painel Classes de entidade. Clique em Terminar.
11. Observe a janela Projetos. Agora você deve ver o seguinte:
    

Adicionando a biblioteca do link superior ao projeto

Embora você tenha adicionado arquivos Toplink ao Tomcat (consulte Copiando bibliotecas para Tomcat), você ainda precisa adicionar as bibliotecas TopLink Essentials ao seu projeto a fim de evitar exceções de conversão de classe. Você deve adicionar essa biblioteca acima das bibliotecas do REST.

1. Clique com o botão direito do mouse no nó do projeto e escolha Propriedades no menu de contexto. A caixa de diálogo Propriedades do projeto é aberta.
2. Na visualização Categorias, escolha Bibliotecas. É aberta uma aba mostrando as bibliotecas de tempo de compilação do projeto.
3. Clique em Adicionar biblioteca. A caixa de diálogo Adicionar biblioteca se abre, mostrando uma lista de bibliotecas disponíveis.
4. Role as bibliotecas em busca da biblioteca Top Link Essentials. Selecione essa biblioteca e clique em Adicionar biblioteca.
   
5. Você agora deve estar de volta à caixa de diálogo Propriedades do projeto. TopLink Essentials deve estar listada nas Bibliotecas do tempo de compilação. Certifique-se de que a caixa Pacote esteja selecionada. Selecione Bibliotecas TopLink e mova-a para o início da lista de bibliotecas, clicando em Mover para cima. Sua lista de bibliotecas do tempo de compilação deve ser parecida com a seguinte:
   
6. Clique em OK. O IDE adiciona as TopLink Essentials à parte superior das bibliotecas do projeto. Para verificar se a biblioteca TopLink Essentials está aqui, expanda o nó Bibliotecas do seu projeto. A lista de bibliotecas deve ser semelhante ao seguinte:
   
7. Reinice o IDE para que as suas alterações tenham efeito. Depois que o IDE se reinicia, reinicie o servidor do banco de dados Derby (Ferramentas > Banco de dados Java DB > Iniciar servidor).

Configurando o arquivo de persistência

Em Gerando classes de entidade a partir de um banco de dados, você criou uma unidade de persistência. A configuração dessa unidade de persistência é armazenada no arquivo persistence.xml. Na visualização Projetos, você pode encontrar persistence.xml no projeto, no nó Arquivos de configuração.

Você precisa alterar esse arquivo de persistência para usar um tipo de transação diferente, para não identificar a fonte de dados e para passar as propriedades necessárias para o provedor de persistência. Abra persistence.xml no IDE. Abra a aba XML. Edite o arquivo de forma que ele coincida com o trecho de código seguinte (as partes que você adiciona ou altera estão em negrito):

<persistence-unit name="CustomerDB-TomcatPU" transaction-type="RESOURCE_LOCAL">
    <provider>oracle.toplink.essentials.PersistenceProvider</provider>

    <!-- <jta-data-source>jdbc/sample</jta-data-source> --> 

    <properties>
      <property name="toplink.jdbc.user" value="app"/>
      <property name="toplink.jdbc.password" value="app"/>
      <property name="toplink.jdbc.url" value="jdbc:derby://localhost:1527/sample"/>
      <property name="toplink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
    </properties>
        </persistence-unit>

Gerando serviços Web RESTful a partir de classes de entidade

O objetivo deste exercício é gerar serviços Web RESTful a partir das classes de entidade que geramos anteriormente (consulte Gerando classes de entidade a partir de um banco de dados).

1. Clique com o botão direito do mouse no pacote que contém as classes de entidade e escolha Novo > Serviços Web RESTful a partir de classes de entidade. O assistente para Novos serviços Web RESTful de classes de entidade se abre.
   
2. No campo Classes de entidade disponíveis, você deve ver duas classes Customer e DiscountCode. Clique em Adicionar tudo e vá para Classes de entidade selecionadas.
3. Clique em Próximo e o painel Classes geradas se abre.
   

   Aqui você pode ver tudo que o IDE irá gerar para você. O IDE usa o padrão item de contêiner para gerar as classes do recurso. Por exemplo, para a classe de entidade Customer, o IDE gera um recurso de contêiner chamado CustomersResource e um recurso de item chamado CustomerResource. Além disso, para cada classe de recurso, o IDE gera uma classe de conversor usada para gerar a representação da instância de entidade correspondente, tal como CustomersConverter e CustomerConverter. Além disso, existe uma classe de conversor adicional chamada conversor de referência, tal como CustomerRefConverter, para representar relacionamentos.

   Aceite os padrões e clique em Terminar.

4. Observe a janela Projetos. Agora você deve ver o seguinte:
   

O nó Serviços Web RESTful na janela Projetos exibe todos os serviços Web RESTful de seu projeto. O valor entre colchetes, tal como [/customers/], é o valor do modelo da URI. Você também pode navegar para o arquivo de código-fonte, clicando duas vezes nesse nó. Essa visualização também existe todos os métodos HTTP e métodos de localizador de sub-recurso. Novamente, você pode navegar para os métodos, clicando duas vezes nos nós.

Agora que nossas classes de entidade e serviços Web RESTful foram gerados, vamos testar a nossa aplicação. O IDE fornece um utilitário prático para testar serviços Web RESTful. Usaremos o mesmo na próxima seção.

Testando os serviços Web RESTful

O objetivo deste exercício é testar a nossa aplicação.

1. Clique com o botão direito do mouse no nó do projeto e escolha Testar serviços Web RESTful.

   O servidor se inicia e a aplicação é implantada. Finalmente, o navegador deve exibir sua aplicação, com um link para cada um dos serviços Web:
   

À esquerda está o conjunto de recursos raiz, aqui eles são chamados de customers e discountCodes.

2. Primeiro selecione o recurso raiz de customers. Clique na lista suspensa Métodos para selecionar GET(application/xml) ou GET(application/json). Clique em Testar. O resultado é exibido na seção Saída do teste:
   
   

Existem 4 abas na seção Saída do teste. A visualização Tabular é uma visualização plana que exibe todas as URIs no documento resultante, para o qual você pode navegar, clicando nos links. A visualização Bruto exibe os dados reais retornados. Dependendo do tipo de mime selecionado (application/xml ou application/json), os dados exibidos estarão no formato XML ou JSON, respectivamente. A aba Cabeçalhos exibe as informações do cabeçalho HTTP. Também existe uma aba chamada Monitor de HTTP, que exibe solicitações e respostas HTTP reais enviadas e recebidas.

3. Saia do navegador e retorne ao IDE.

Adicionando um recurso Google Map

O objetivo deste exercício é adicionar a funcionalidade Google Map aos nossos serviços Web RESTful.

1. Abra a classe CustomerResource no editor, como mostrado abaixo. No menu Ferramentas, escolha Paleta. Observe que aparece uma paleta no lado direito do editor, contendo fragmentos de código:
   
2. Inscreva-se para obter uma chave do Google Map em http://www.google.com/apis/maps/signup.html. A caixa de diálogo Solicitação de chave do Google Map possui um campo para a URL do seu site. Digite http://localhost:8080 nesse campo.
3. Na categoria Google, arraste o item Mapa e solte-o em qualquer lugar na classe. A caixa de diálogo Personalizar GoogleMap se abre. Indique a chave Google Map no campo "apiKey", como mostrado aqui:
   

   Clique em OK. O IDE cria a classe GoogleMapResource. A classe CustomerResource acessa-a por meio deste método, que o IDE também criou:

       /**
        * Returns GoogleMapResource sub-resource.
        */
       @Path("googleMap/")
       public GoogleMapResource getGoogleMap() {
           try {
               customer.db.tomcat.Customer entity = getEntity();
               String apiKey = null;
               String address = entity.getAddressline1();
               Integer zoom = null;
               return new GoogleMapResource(apiKey, address, zoom);
           } finally {
               PersistenceService.getInstance().close();
           }
       }

4. Clique com o botão direito do mouse no nó do projeto e escolha Testar serviços Web RESTful novamente e, quando o navegador se abrir de novo, clique em googleMap. Você deve ver o seguinte, com apiKey preenchido:
   
5. Clique no botão Testar. Observe que o Google Map se abre na aba da visualização Bruto:

   Importante: No Firefox 2, o cliente de teste congela tentando produzir a imagem. Clique na URL http:.../googleMap/ em Recurso: e a imagem do mapa aparecerá em uma nova aba do navegador.

   
   

Veja também

Para obter mais informações sobre o uso do NetBeans IDE 6.0 para desenvolver aplicações Java EE, consulte os seguintes recursos:

• Desenvolvendo clientes de serviço Web JAX-WS
• Introdução aos serviços Web JAX-WS
• Introdução aos serviços Web RESTful no GlassFish
• Criando stubs de cliente de serviço Web RESTful
• Interoperabilidade avançada do serviço Web
• Trilha do aprendizado das aplicações de serviço Web e EJB

Para enviar comentários e sugestões, obter suporte e se manter informado sobre os mais recentes desenvolvimentos dos recursos de desenvolvimento de Java EE do NetBeans IDE, inscreva-se na lista de endereçamento de .