Introdução aos serviços Web RESTful

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. Neste tutorial, você primeiro aprende um pouco sobre REST e, em seguida, como o NetBeans IDE 6.0 suporta esse estilo de arquitetura.

Conteúdo

• Introdução
• Gerando classes de entidade de um banco de dados
• Gerando serviços Web RESTful a partir de classes de entidade
• Testando os serviços Web RESTful
• Adicionando um recurso Google Map

Software necessário para o tutorial

Antes de começar, você deve baixar e instalar o seguinte software no seu computador:

• Web e Java EE do NetBeans IDE 6.0(download).
• Java Standard Development Kit (JDK) versão 5.0 ou acima (download)
• Servidor Web Glassfish V2 ou Tomcat, ambos podem ser selecionados no instalador que você usa para instalar o NetBeans IDE 6.0.
• No IDE, vá para o Gerenciador de plug-ins, no menu Ferramentas, e instale o plug-in Serviços Web RESTful, 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.

Neste tutorial, você aprenderá como o IDE o ajuda na geração, implementação e teste de serviços Web RESTful.

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.

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.
3. Em Servidor, selecione um servidor, tal como GlassFish. Clique em Terminar.
4. Clique com o botão direito do mouse no nó CustomerDB e escolha Novo > Classes de entidade de um banco de dados, como mostrado abaixo:

   

Como alternativa, você pode selecioná-la na categoria Persistência no assistente para Novo arquivo (Ctrl-N), como mostrado abaixo:



Clique em Próximo.

5. No painel Tabelas do banco de dados, selecione a fonte de dados jdbc/sample. Em seguida, 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:
   
   

   

   Clique em Próximo.

6. Em Pacote, digite customerdb. Agora você deve ver o seguinte:
   
   

   

7. Clique em Criar unidade de persistência. A caixa de diálogo seguinte é exibida:
   
   

   

   Clique em criar e, em seguida, em Terminar.

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

   

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 na seção anterior.

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, como mostrado abaixo:
   
   

   

2. No assistente para Novos serviços Web RESTful a partir de classes de entidade, clique em Adicionar tudo. Agora você deve ver o seguinte:
   
   

   

   Clique em Próximo.

3. No próximo painel, deixe os padrões inalterados, como mostrado abaixo:
   
   

   

   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.

   Clique em Terminar.

4. Observe a janela Projetos. Agora você deve mostrar 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, como mostrado abaixo:
   
   

   

   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 um recurso raiz, tal como 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.
3. Na categoria Google, arraste o item Mapa e solte-o em qualquer lugar na classe e 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.
     */
    @UriTemplate("googleMap/")
    public GoogleMapResource getGoogleMap(
            @UriParam("customerId") Integer id) {
        try {
            customerdb.Customer entity = getEntity(id);
            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:
   
   

   

6. Sempre que você clicar em um link do Google Map, o mesmo endereço será mostrado. Isso acontece porque o endereço é codificado na classe GoogleMapResource. Agora iremos modificar o método gerado que examinamos anteriormente na classe CustomerResource:

   @UriTemplate("googleMap/")
   public GoogleMapResource getGoogleMap(@UriParam("customerId")
   Integer id) {
       try {
           customerdb.Customer entity = getEntity(id);
           String apiKey = null;
           String address = entity.getAddressline1();
           Integer zoom = null;
           return new GoogleMapResource(apiKey, address, zoom);
       } finally {
           PersistenceService.getInstance().close();
       }
   }

   Altere-o para o seguinte:

   @UriTemplate("googleMap/")
   public GoogleMapResource getGoogleMapResource(
           @UriParam("customerId") Integer id) {
       Customer c = getEntity(id);
       String address = c.getAddressline1() + " " + c.getAddressline2() +
               " " + c.getCity() + " " + c.getState() + " " + c.getZip();
       String mapKey = "abcdef";
       Integer zoom = null;
       return new GoogleMapResource(mapKey, address, zoom);
   }

   O código extrai as informações do endereço da entidade customer e passa-a para a instância GoogleMapResource.

7. Teste a aplicação novamente. Clique em customers na barra lateral esquerda, em vez de googleMap. Escolha um método de entrada. Clique em Testar. Clique em /customers/1/. Clique em Testar. Agora que você possui dois links, um para código de desconto e um para o Google Map. Clique no link Google Map e, em seguida, clique em Testar novamente. Observe que a entrada correta do Google Map é retornada agora para o cliente:
   
   

   

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:

• Introdução aos clientes de serviço Web JAX-WS
• Introdução aos serviços Web JAX-WS
• Introdução aos serviços Web RESTful
• Consumindo serviços Web do StrikeIron em aplicações Web
• Consumindo serviços Web do Google em aplicações Web
• Interoperabilidade avançada do serviço Web
• Caminho do aprendizado das aplicações Java EE
• YouTube: RESTful Web Services, Building and Deploying (Part 1)
• YouTube: NetBeans RESTful Testing and Invoking RESTful Resources (Part 2)

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.