Introdução aos Web Services 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, como HTTP, e as informações são trocadas usando representações desses recursos. Neste tutorial, você primeiro aprende um pouco sobre REST e depois vê como o NetBeans IDE dá suporte a esse estilo de arquitetura.

Conteúdo

O conteúdo desta página se aplica ao NetBeans IDE 7.2, 7.3 e 7.4

Para seguir este tutorial, são necessários os recursos e o software a seguir.

Software ou Recurso Versão Necessária
NetBeans IDE Pacote de download do Java EE
JDK (Java Development Kit) versão 6 ou 7
Servidor de aplicações em conformidade com Java EE

Oracle WebLogic Server 11g-12c,
ou GlassFish Server Open Source Edition 3.x ou 4.x.
(Não funciona no Tomcat, a menos que o plug-in de suporte do EJB esteja instalado no Tomcat)

O banco de dados jdbc/amostra no
servidor de banco de dados JAVA DB (Derby) ou
servidor de banco de dados MySQL

No Java DB (Derby), o banco de dados jdbc/amostra é gerado pelo NetBeans IDE
ao instalar o IDE com o servidor de aplicações GlassFish.

No MySQL, o IDE preenche o banco de dados de amostra após você tê-lo criado no servidor MySQL de dentro do IDE.

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

Importante: os projetos Java EE 6 e Java EE 7 requerem GlassFish Server ou Oracle WebLogic Server 12c.

Introdução

Os Web services RESTful são serviços construídos com o estilo de arquitetura RESTful. A construção de Web services 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 ter a capacidade de transmitir dados diretamente via HTTP.

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

Para obter informações detalhadas, consulte:

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

Veja uma lista das funcionalidades RESTful fornecidas pelo IDE:

  1. Criação rápida de Web services RESTful com base em padrões e classes de entidade JPA.
  2. Geração rápida de código para chamar Web services como Google Maps, Yahoo News Search e o StrikeIron arrastando e soltando componentes do gerenciador de Web Services na janela Serviços.
  3. Geração de Clientes Java RESTful para serviços registrados no gerenciador de Web Services.
  4. Geração de cliente de teste para testar Web services RESTful.
  5. View lógica para navegação fácil de classes de implementação do Web service RESTful no seu projeto.
  6. Framework Spring totalmente integrado, oferecendo tratamento de transações Spring.

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

Web Services RESTful, Persistência e Classes de Entidade

Os Web services RESTful no Java dependem da Java Persistence API para se comunicarem com um banco de dados. Especificamente, os Web services RESTful dependem de classes de entidade e uma unidade de persistência, como definido na API de Persistência. As classes de entidade são classes Java que mapeiam para objetos em um banco de dados relacional. Conforme o Tutorial Java EE5, “Uma entidade é um objeto de domínio de persistência leve. Normalmente, uma entidade representa uma tabela em um banco de dados relacional, e cada instância da entidade corresponde a uma linha nessa tabela". Uma unidade de persistência consiste no conjunto de classes de entidades, na fonte de dados, no provedor da persistência e no próprio nome da unidade de persistência, como definido em um arquivo persistence.xml.

Você pode usar o NetBeans IDE para criar classes de entidade e Web services RESTful no mesmo processo, ou você pode usar o IDE para criar Web services RESTful de classes de entidade existentes. Neste tutorial, use o assistente Serviços RESTful a partir do Banco de Dados para gerar classes de entidade e Web services RESTful no mesmo processo. O assistente gera automaticamente a unidade de persistência.

Usando um Servidor de Banco de Dados MySQL

Se Você usar o servidor de bando de dados MySQL em vez de um JavaDB (Derby), você deverá registrar o servidor do banco de dados no IDE e adicionar o banco de dados de amostra ao servidor.

Para usar um servidor de banco de dados MySQL com este tutorial:

  1. Registre o servidor MySQL no IDE, se o servidor ainda não estiver registrado. Para registrar um servidor MySQL, vá à janela Serviços do IDE, clique com o botão direito do mouse no nó Banco de dados e selecione Registrar servidor MySQL.
    Opção Registrar Servidor MySQL na janela Serviços
  2. Uma caixa de diálogo será aberta, na qual você digitará os detalhes de configuração do seu servidor MySQL, incluindo o nome de usuário e senha de administrador. Consulte “Configurando as Propriedades do Servidor MySQL” em Conectando-se a um Banco de dados MySQL.

    Propriedades básicas do servidor MySQL que você está registrando no IDE
  3. Inicie o servidor MySQL e conecte-se a ele. Consulte “Iniciando o Servidor MySQL” em Conectando-se a um Banco de Dados MySQL.
  4. Clique com o botão direito do mouse no nó do servidor MySQL e selecione Criar Banco de Dados. A caixa de diálogo Criar Banco de Dados MySQL será aberta.
    Opção do menu de contexto Criar Banco de Dados
  5. Digite sample como o novo nome do banco de dados. Conceda acesso total ao usuário raiz, ou ao usuário que você desejar.
    Caixa de diálogo Nome do Novo Banco de Dados preenchida
  6. Clique em OK. Uma caixa de diálogo é aberta, informando que sample é o nome de um banco de dados de amostra e perguntando se você deseja criar tabelas, objetos e dados para esse banco de dados.
    Solicitação para preencher o banco de dados com dados de amostra
  7. Clique em Sim. O IDE cria e preenche o banco de dados, e adiciona uma conexão ao banco de dados.
    Banco de dados de amostra gerado e conexão com o banco de dados na janela Serviços

Criando Web Services RESTful de um Banco de dados

O objetivo deste exercício é criar um projeto e gerar classes de entidade e Web services RESTful com base em um banco de dados.

Esta seção usa o banco de dados JavaDB (Derby) e a fonte de dados jdbc/de amostra O JavaDB está incluído no SDK. A fonte de dados jdbc/amostra é gerada pelo NetBeans IDE automaticamente quando o IDE é instalado junto com o GlassFish.

Criando o Projeto

Para criar Web services RESTful, é necessário um projeto de aplicação Java Web.

Para criar o projeto:

  1. Selecione Arquivo > Novo Projeto (Ctrl-Shift-N no Linux e no Windows, ⌘-Shift-N no MacOS). Em Categorias, selecione Java Web. Em Projetos, selecione Aplicação Web. Clique em Próximo. O assistente Nova Aplicação Web será aberto.

    Como alternativa, você pode criar uma aplicação Web Maven. Selecione Arquivo > Novo Projeto (Ctrl-Shift-N no Linux e no Windows, ⌘-Shift-N no MacOS). Em Categorias, selecione Maven. Em Projetos, selecione Aplicação Web Maven e clique em Próximo.

  2. Em Nome do Projeto, digite CustomerDB. Clique em Próximo.
  3. Selecione Java EE 6 Web ou Java EE 7 Web. Em Servidor, selecione o servidor que você deseja usar, mas observe que os projetos do Java EE exibe GlassFish server 3.x ou 4.x. Clique nas opções remanescentes e clique em Finalizar.

    Importante para Projetos Maven: no NetBeans IDE 7.2 você não pode definir o servidor ao criar uma aplicação web Maven. Entretanto, você tem que definir o servidor antes de poder criar uma unidade de persistência. Portanto, após criar a aplicação web Maven, abra as Propriedades do projeto e defina o servidor nas propriedades de Execução. Para abrir as Propriedades do projeto, clique com o botão direito do mouse no nó Projeto e selecione Propriedades no menu de contexto.

Gerando Classes de Entidade e Serviços RESTful

Quando você tiver uma aplicação Java Web, adicione classes de entidade e Web services RESTful ao projeto.

Para gerar classes de entidade e Web services RESTful:

  1. Clique com o botão direito do mouse no nó CustomerDB e selecione Novo > Outro > Web Services > Web Services RESTful do Banco de dados. O assistente Novo Web Service RESTful é aberto, no painel Tabelas de Bancos de dados.
    Web Services RESTful na opção Banco de dados no menu
  2. No painel Tabelas do Banco de dados, se estiver utilizando o GlassFish Server, selecione a fonte de dados jdbc/sample no campo drop-down Fonte de Dados.

    Se estiver utilizando o Tomcat, selecione jdbc:derby://localhost:1527/sample. Se o servidor de banco de dados Derby não iniciar automaticamente, será necessário iniciá-lo a partir da guia Bancos de dados na janela Serviços.

    Observação para usuários do MySQL: É necessário criar uma nova fonte de dados. Selecione Nova Fonte de Dados, dê a ela um nome descritivo arbitrário e selecione a conexão de banco de dados jdbc:mysql://localhost:3306/sample. Essa conexão foi estabelecida ao criar o banco de dados de amostra no MySQL.
    Nova fonte de dados utilizando conexão mysql

  3. Em Tabelas Disponíveis, selecione CUSTOMER e, em seguida, clique em Adicionar. A tabela DISCOUNT_CODE, que tem um relacionamento com a tabela CUSTOMER, também é adicionada automaticamente à lista Tabelas Selecionadas. Se você estiver usando um banco de dados MySQL ou algumas versões do Derby, a tabela MICRO_MARKET também será adicionada. Você agora verá o seguinte (versão do Derby):

    Painel Tabelas de Bancos de Dados do assistente Novas Classes de Entidade do Banco de Dados que mostra as tabelas CUSTOMER e DISCOUNT_CODE selecionadas
  4. Clique em Próximo. A Página Classes de Entidade será aberta. Digite entities como o nome do Pacote. Você agora verá o seguinte (versão do Derby).

    Observação: O assistente Web Services RESTful do Banco de Dados gera automaticamente anotações JAXB. Se você gerar classes de entidade para uma aplicação Java EE com o assistente Classes de Entidade do Banco de dados e mais tarde quiser criar Web services RESTful com base nessas classes de entidade, certifique-se de que a caixa Gerar Anotações JAXB esteja marcada. Você também pode adicionar anotações JAXB manualmente às classes de entidade antes de executar o assistente Web Services RESTful de Classes de Entidade. Para obter mais informações, consulte NetBeans para Gerar Web Services RESTful Mais Simples.

    Painel Classes de Entidade do assistente Web Services RESTful do Banco de Dados que mostra o nome do pacote
  5. Clique em Próximo. Um painel será aberto no qual você poderá definir o nome e a localização das classes e pacotes de serviços gerados. Para projetos do Java EE, você tem a opção de alterar o nome e a localização da classe de configuração da aplicação REST.

    Aplicações Spring Framework: registre os recursos RESTful no descritor de implantação web.xml. NÃO Use javax.ws.rs.core.Application.

    Para este tutorial, aceite os defaults e clique em Finalizar. Quando você clica em Finalizar o IDE gera classes de entidade e serviço. Em um projeto Java EE, o IDE também gera uma classe de configuração de aplicação, que é uma subclasse de Application.

    Serviço gerado e classes de configuração e pacotes de serviços

Agora, o IDE gera Web services RESTful. Quando o IDE tiver finalizado, observe a janela Projetos. As classes da entidade geradas estão no pacote entities e os serviços estão no pacote service. Os web services do Java EE RESTful EE6 de um banco de dados instanciam o EntityManager em cada classe de serviço. Isso elimina a necessidade de classes do controlador JPA e gera códigos mais simples.

Testando os Web Services RESTful

O objetivo deste exercício é testar sua aplicação. Você criará uma nova aplicação web para os testes e, em seguida, usará um assistente no IDE para gerar os testes no novo projeto.

  1. Escolha Arquivo > Novo Projeto no menu principal.
  2. Selecione o tipo de projeto Aplicação Web na categoria Java Web. Clique em Próximo.
  3. Digite WebServicesTest para o nome do projeto. Clique em Próximo.
  4. Selecione o GlassFish Server como servidor de destino e o Java EE 6 ou Java EE 7 como a versão do Java EE. Clique em Finalizar.
  5. Clique com o botão direito do mouse no nó do projeto CustomerDB e selecione Testar Web Services RESTful. Uma caixa de diálogo será aberta perguntando se você deseja gerar o cliente de teste dentro do projeto do serviço ou em um outro projeto Java Web. Essa opção permite a você driblar as restrições de segurança em alguns browsers. Você pode usar um projeto Web, contanto que ele esteja configurado para ser implantado no mesmo domínio de servidor que o projeto CustomerDB.
    Caixa de diálogo para selecionar se um cliente de teste deverá ser gerado localmente ou em outro projeto Java Web implantado no mesmo domínio
  6. Selecione Cliente de Teste da Web no Projeto e clique em Procurar.
  7. Selecione o projeto WebServiceTest na caixa de diálogo Selecionar Projeto. Clique em OK.

    O IDE gera o arquivo test-resbeans.html no projeto WebServiceTest. O IDE também inicia automaticamente o servidor e implanta a aplicação CustomerDB.

    Se a janela de saída mostrar uma mensagem de erro dizendo que uma ou mais classes não existe e que o projeto não pode ser construído, adicione as bibliotecas Jersey às bibliotecas de tempo de compilação. Clique com o botão direito do mouse no nó do projeto e selecione Propriedades. No menu em árvore Propriedades, selecione Bibliotecas. Clique em Adicionar Biblioteca e procure as bibliotecas Jersey.

  8. Clique com o botão direito do mouse em WebServiceTest e escolha Executar.
  9. Abra seu browser em http://localhost:8080/WebServicesTest/test-resbeans.html
    Página inicial de testes do Web service RESTful no browser

    À esquerda está o conjunto de recursos raiz. Aqui eles são nomeados entities.customer e entities.discountCodes e entities.microMarket.

  10. Clique no nó entities.customer. No campo "Escolher método para testar", selecione GET (application/json) ou GET (application/xml). Clique em Testar. O cliente de teste enviará uma solicitação e exibirá o resultado na seção Saída do Teste. O cliente de teste exibirá a View Bruta por default. A imagem a seguir mostra a resposta a uma solicitação aplicação/xml.
    Janela View bruta no testador do Web service RESTful

Existem 5 guias na seção Saída do Teste.

  • A View Tabular é uma view nivelada que exibe todas as URI no documento resultante. Atualmente, essa view exibe apenas uma advertência de que relações conteúdo-continente não são permitidas.
  • A View Bruta 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 guia Sub-Recurso mostra os URLs do recurso raiz e dos sub-recursos. Quando o Web service RESTful tem como base classes de entidade de banco de dados, o recurso raiz representa a tabela do banco de dados e os sub-recursos representam as colunas.
  • A guia Cabeçalhos exibe as informações do cabeçalho HTTP.
  • A guia Monitor HTTP exibe as solicitações HTTP reais e as respostas enviadas e recebidas.

Saia do browser e retorne ao IDE.

Web Services RESTful no Spring Framework

O Jersey é integrado ao Spring Framework. Quando você cria uma aplicação Java Web com o Spring Framework, um servlet com reconhecimento de REST é automaticamente criado. No entanto, o Spring 3 não contém aopalliance.jar, que o Web service RESTful exige para injetar um objeto EntityManager.

Criando uma aplicação Java Web com o Spring Framework

Quando você cria a aplicação Java Web no assistente Novo Projeto, como descrito em Gerando Classes de Entidade de um Banco de dados, depois de selecionar o servidor, clique em Próximo, em vez de em Finalizar para abrir o painel Frameworks do assistente. Selecione Spring Web MVC e clique em Finalizar.

Observação. Se já criou seu projeto, você poderá adicionar suporte para o framework Spring Web MVC clicando com o botão direito do mouse no nó do projeto na janela Projetos e escolhendo Propriedades no menu pop-up. Na janela Propriedades do Projeto, selecione a categoria Frameworks e, em seguida, clique em Adicionar e selecione Spring Web MVC.

Adicionando aopalliance.jar ao Projeto

O Spring 3 não contém aopalliance.jar. A aplicação exige essa biblioteca para injetar EntityManager. Para corrigir o problema, você precisa fazer download desse jar e adicioná-lo a seu classpath. Consulte Problema 193626 e os fóruns do Spring.

Para adicionar aopalliance.jar:

  1. Faça download de um arquivo compactado zip de aopalliance.jar de http://sourceforge.net/projects/aopalliance/files/aopalliance/1.0/.
  2. Descompacte o arquivo compactado no local que desejar.
  3. Clique com o botão direito do mouse no nó do projeto Web Service RESTful do Spring na janela Projetos e escolha Propriedades no menu pop-up e, em seguida, selecione a categoria Bibliotecas na janela Propriedades do Projeto.
    Menu de contexto que mostra o nó de propriedades

    Se preferir, clique com o botão direito do mouse no nó Bibliotecas do projeto na janela Projetos e escolha Adicionar JAR/Pasta.

  4. Clique em Adicionar JAR/Pasta e localize o aopalliance.jar no browser do sistema do arquivo. Clique em Abrir.

    Você poderá usar a referência do caminho absoluto.

    Procurando aopalliance.jar
  5. O arquivo aopalliance.jar agora está incluído em suas bibliotecas. Clique em OK.
    Propriedades da biblioteca que mostram o aopalliance.jar adicionado

Criando Serviços RESTful no projeto compatível com Spring

Depois de criar uma aplicação Java Web com o Spring framework e adicionar aopalliance.jar ao classpath do projeto, execute o Web Service RESTful no assistente Banco de dados, conforme descrito em Gerando Entidades e Serviços. No entanto, NÃO registre recursos RESTful com uma subclasse de javax.ws.rs.core.Application. Em vez disso, use o descritor de implantação web.xml. O Spring framework gerará um descritor de implantação web.xml em todos os casos.

Opções para registrar recursos RESTful, web.xml escolhido

Para obter mais informações sobre as funcionalidades dos projetos do Spring framework no NetBeans IDE, consulte Introdução ao Spring Framework.

Erros de Compilação

Você poderá ter erros de compilação nas classes de serviço geradas. Você verá esses erros se criar os serviços RESTful antes de adicionar aopalliance.jar ao classpath.

Para corrigir erros de compilação em classes de serviço:

  1. Assegure-se de adicionar aopalliance.jar ao classpath, conforme descrito em Adicionando aopalliance.jar ao Projeto.
  2. Na barra do menu superior do IDE, clique em Editar e selecione Localizar em Projetos...
  3. Procure todas as ocorrências da anotação @Error no projeto.
    Caixa de diálogo Localizar em Projetos que mostra a procura pela anotação @Error
  4. Delete todas as linhas @Error do código.
    Resultados da busca por @Error, com uma linha realçada e prestes a ser deletada

Consulte Também

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

Para enviar comentários e sugestões, obter suporte e se manter informado sobre os mais recentes desenvolvimentos das funcionalidades de desenvolvimento Java EE do NetBeans IDE, inscreva-se na lista de notícias .

get support for the NetBeans

Support


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo