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 depois vê como o NetBeans IDE dá suporte a esse estilo de arquitetura.
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.
Além de construir serviços Web RESTful, o IDE também oferece suporte ao teste e à construção de aplicativos cliente que acessem serviços Web RESTful e à criação de código para invocar serviços Web (com base tanto em RESTful quanto em SOAP.)
Veja uma lista dos recursos RESTful fornecidos pelo IDE:
Criação rápida de serviços Web RESTful a partir de padrões e classes de entidade JPA.
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 do gerenciador de serviços Web na janela Serviços.
Geração de clientes Java RESTful para serviços registrados no gerenciador de serviços Web.
Geração de cliente de teste para testar serviços Web RESTful.
Visualização lógica para navegação fácil de classes de implementação do serviço Web RESTful no seu projeto.
Estrutura Spring totalmente integrada, oferecendo manipulação de transações Spring.
Neste tutorial, você aprenderá como o IDE o ajuda na geração, implementação e teste de serviços Web RESTful.
Serviços Web RESTful, persistência e classes de entidade
Os serviços Web RESTful em Java dependem da API de Java Persistence para se comunicar com um banco de dados. Especificamente, os serviços Web RESTful dependem das classes de entidade e uma unidade de persistência, conforme definido na API de persistência. As classes de entidade são classes Java que fazem mapeamentos a objetos em um banco de dados relacional. De acordo com o tutorial do Java EE5, "uma entidade é um objeto de domínio leve e de persistência. Normalmente, uma entidade representa uma tabela em um banco de dados relacional e cada instância da entidade corresponde a uma linha de tal tabela." Uma unidade de persistência está formada pelo conjunto de classes de entidade, a fonte de dados, o provedor de persistência e o próprio nome da unidade de persistência, conforme definido em um arquivo persistence.xml.
É possível utilizar o NetBeans IDE para criar classes de entidade e serviços Web RESTful no mesmo processo ou utilizar o IDE para criar serviços Web RESTful a partir das classes de entidade existentes. Neste tutorial, os serviços RESTful são utilizados do assistente de banco de dados para gerar classes de entidade e serviços Web RESTful no mesmo processo. O assistente gera automaticamente a unidade de persistência.
Utilizando um servidor de banco de dados MySQL
Se utilizar o servidor de banco de dados MySQL em lugar do JavaDB (Derby), é necessário registrar o servidor de banco de dados com o IDE e adicionar o banco de dados sample ao servidor.
Para utilizar o servidor de banco de dados MySQL com este:
Registre seu servidor MySQL no IDE caso o servidor não esteja registrado. Para registrar um servidor MySQL, vá à janela Serviços do IDE, clique com o botão direito do mouse no nó Bancos de dados e selecione Registrar servidor MySQL.
É exibida a caixa de diálogo na qual as informações de configuração do servidor MySQL são fornecidas, incluindo o nome de usuário e senha do administrador. Consulte "Configurando as propriedades do servidor MySQL" em Conectando-se a um banco de dados MySQL.
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 é aberta.
Digite sample como nome para o novo banco de dados. Conceda acesso total ao usuário raiz ou a um usuário da sua preferência.
Clique em OK. A caixa de diálogo é exibida informando-lhe que sample é nome de um banco de dados de amostra e perguntando se deseja criar tabelas, objetos e dados neste banco de dados.
Clique em Sim. O IDE cria e preenche o banco de dados e adiciona uma conexão ao banco de dados.
O objetivo deste exercício é criar um projeto e gerar classes de entidade e serviços Web RESTful a partir de um banco de dados.
Esta seção utiliza o banco de dados JavaDB (Derby) e a fonte de dados jdbc/sample. O JavaDB está incluído no SDK. A fonte de dados jdbc/sample é gerada automaticamente pelo NetBeans IDE quando o IDE é instalado junto com o GlassFish.
Criando o projeto
Para criar os serviços Web RESTful, você precisa de um projeto de aplicação Web Java.
Para criar o projeto:
Escolha Arquivo > Novo projeto (Ctrl-Shift-N). Em Categorias, selecione Java Web. Em Projetos, selecione Aplicação Web. Clique em Próximo. O assistente para Nova aplicação Web se abre.
Como alternativa, você pode criar uma aplicação Web Maven. Escolha Arquivo > Novo projeto (Ctrl-Shift-N). Em Categorias, selecione Maven. Em Projetos, selecione Aplicação Web Maven e clique em Próximo.
Em Nome do projeto, indique CustomerDB. Clique em Próximo.
Selecione EE 6 ou EE 5. Em Servidor, selecione o servidor que deseja utilizar, mas note que os projetos EE 6 requerem o servidor GlassFish 3 ou posterior. Clique nas opções restantes e clique em Terminar.
Importante em projetos Maven: não é possível definir o servidor ao criar aplicação Web Maven. No entanto, é necessário definir o servidor antes de criar a unidade de persistência. Portanto, depois de criar a aplicação Web Maven, abra as propriedades do projeto e defina o servidor na propriedade Executar. Para abrir as propriedades do projeto, clique com o botão direito do mouse no nó Projeto e selecione Propriedades no menu de contexto.
Tomcat 7 e EE6: o Tomcat 7 não funcionará com os serviços RESTful EE6 gerados pelo NetBeans IDE 7.0 ou posterior. Isso ocorre porque o NetBeans 7.0 introduz as fachadas de sessão nos serviços RESTful e o Tomcat 7 não tem o plug-in compatível com o EJB 3.1 ou os EJBs EE6. Consulte o projeto Apache Geronimo e o projeto de plug-in Apache OpenEJB para seguir o andamento destes problemas.
Gerando classes de entidade e serviços RESTful
Com aplicações Web Java, adicione classes entidade e serviços Web RESTful ao projeto.
Para gerar classes de entidade e serviços Web RESTful:
Clique com o botão direito do mouse no nó CustomerDB e selecione Novo > Outro > Serviços Web > Serviços Web RESTful do banco de dados. O assistente para Novo serviço Web RESTful se abre no painel Tabelas de banco de dados.
No painel Tabelas do banco de dados, se estiver utilizando o servidor GlassFish, selecione a fonte de dados jdbc/sample no campo suspenso 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 aba Bancos de dados na janela Serviços.
Nota aos usuários de MySQL: é necessário criar uma nova fonte de dados. Selecione Nova fonte de dados, dê um nome descritivo arbitrário e selecione a conexão de banco de dados jdbc:mysql://localhost:3306/sample Esta conexão é criada quando o banco de dados de amostra é criado no MySQL.
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. A página Classes de entidade se abre. Em Pacote, digite entities. Agora você deve ver o seguinte.
Nota sobre os serviços EE6: o assistente para Serviços Web RESTful de banco de dados gera automaticamente anotações JAXB. Se gerar classes de entidade para um aplicativo EE6 com o assistente para Classes de entidade de banco de dados e quiser posteriormente criar serviços Web RESTful a partir dessas classes de entidade, certifique-se de que a caixa Gerar anotações JAXB esteja marcada. Também é possível adicionar anotações JAXB manualmente às classes de entidade antes de executar o assistente para Serviços Web RESTful de classes de entidade. Para obter mais informações, consulte NetBeans para gerar serviços Web RESTful mais simples.
Clique em Próximo. O painel Classes geradas se abre. Neste painel, é possível definir o local do serviço Web RESTful gerado pelo IDE. O painel Classes geradas é diferente nos serviços Web RESTful EE5 e EE6 porque os projetos EE5 incluem classes de conversor, porém os serviços Web RESTful EE6 utilizam, ao contrário, anotações JAXB nas classes de entidade.
Aceite os pacotes e os locais padrão e clique em Terminar. O IDE gera as classes da entidade. A seguir, se abre uma caixa de diálogo perguntado como você deseja registrar os recursos RESTful. Nos projetos EE5, você tem a opção (padrão) de utilizar um adaptador de servlet Jersey RESTful no descritor de deployment web.xml ou de codificar manualmente sua própria solução. Nos projetos EE6, você tem a opção adicional (padrão) de utilizar uma subclasse de javax.ws.rs.core.Application.
Tanto para um aplicativo EE5 quanto EE6, crie um adaptador de servlet REST Jersey padrão no web.xml e clique em OK. Isso está relacionado ao problema nº 16118 do GlassFish.
O IDE gera agora os serviços Web RESTful. Quando o IDE for finalizado, examine a janela Projetos. As classes de entidade geradas estão no pacote entities. Os serviços estão no pacote service Em um projeto EE5, há classes de conversor no pacote converter e um descritor de deployment web.xml em Arquivos de configuração.
Aviso: o IDE pode solicitar que você resolva os problemas de referência do projeto. Neste caso, clique com o botão direito do mouse no nó do projeto CustomerDB e selecione Resolver problemas de referência. Este problema pode ocorrer quando o serviço for o primeiro aplicativo Jersey a ser executado em uma instalação do WebLogic. Neste caso, o IDE resolve o problema de referência copiando as bibliotecas Jersey no servidor.
Nos serviços Web RESTful EE6 a partir de um banco de dados, o NetBeans IDE utiliza anotações JAXB nas classes de entidade e fachadas de sessão EJB para as classes de serviço. Isso elimina a necessidade das classes de conversor e gera códigos mais simples.
O objetivo deste exercício é testar seu aplicativo.
Clique com o botão direito do mouse no nó do projeto e escolha Testar serviços Web RESTful. O servidor é iniciado e o aplicativo é implantado. Quando o deployment estiver concluído, o navegador exibirá seu aplicativo, com um link para cada um dos serviços Web.
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 nas bibliotecas de tempo de compilação. Clique com o botão direito do mouse no nó do projeto e selecione Propriedades. Na árvore de menu Propriedades, selecione Bibliotecas. Clique em Adicionar biblioteca e procure as bibliotecas Jersey.
À esquerda está o conjunto de recursos raiz. Aqui eles se chamam customers e discountCodes.
Clique no nó customers. A janela do navegador mostra uma lista de parâmetros para testar o serviço de clientes.
Você pode definir os seguintes parâmetros:
Choose method to test: Escolha o método GET ou POST e o tipo de MIME em uma lista suspensa.
Start: Primeira entidade a ser exibida. Observe que a numeração começa com 0, não 1.
Max: Número máximo de entidades a serem buscadas. Se for definido como 0, todas as entradas são buscadas.
Expand level: Um recurso avançado. Alguns serviços retornam uma hierarquia em árvore que se repete infinitamente. Esse parâmetro especifica qual profundidade dessa hierarquia deve ser exibida na Visualização bruta.
Query: Um recurso avançado. Pesquisa o documento XML ou JSON de acordo com a sintaxe JPA.
Clique na lista suspensa Métodos para selecionar GET(application/xml). Digite "3" no campo Max. Deixe os valores padrão nos outros parâmetros e clique em Testar. O resultado é exibido na seção Saída do teste.
Existem 5 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 Sub-recurso mostra os URLs do recurso raiz e dos sub-recursos. Quando o serviço da Web 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 aba Cabeçalhos exibe as informações do cabeçalho HTTP.
A aba Monitor HTTP exibe as requisições HTTP reais e as respostas enviadas e recebidas.
Observe que há 6 resultados listados, embora você tenha especificado um mínimo de 3 entidades a serem exibidas. Abra a aba Visualização bruta para ver o motivo. Cada entidade corresponde a um elemento <customer>, e você possui apenas 3 clientes nos resultados de teste. Entretanto, a visualização Tabular lista URIs, não entidades, e cada entidade possui duas URIs, uma como um atributo do elemento <customer> pai e uma como um atributo do elemento <discountCode> filho. Portanto, embora haja somente 3 entidades de cliente, existem URIs no total.
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.
Abra a classe CustomerResource no editor.
Adicione o seguinte método a CustomerResource:
@GET
@Produces("text/html")
public String getGoogleMap() {
// Arraste a operação getGoogleMap e solte-a aqui
return "";
}
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.
No IDE, abra a aba Serviços e expanda o nó Serviços Web. Em Serviços Web, expanda Google. Em Google, expanda Serviço de mapa.
Arraste o item getGoogleMap e solte-o no corpo do método getGoogleMap criado na Etapa 2, antes da linha return = "";. A caixa de diálogo Personalizar getGoogleMap SAAS é aberta. Aceite os padrões e clique em OK.
O IDE adiciona o seguinte bloco de teste ao método getGoogleMap na classe CustomerResource.
@GET
@Produces("text/html")
public String getGoogleMap() {
// Arraste a operação getGoogleMap e solte-a aqui
try {
String address = "16 Network Circle, Menlo Park";
java.lang.Integer zoom = 15;
String iframe = "false";
RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
//TODO - Retire o comentário da Declaração de impressão abaixo para imprimir o resultado.
//System.out.println("The SaasService returned: "+result.getDataAsString());
} catch (Exception ex) {
ex.printStackTrace();
}
return "";
}
O IDE também cria os pacotes org.netbeans.saas e org.netbeans.saas.google, que contêm os seguintes recursos e classes:
RestConnection - Um wrapper de HttpUrlConnection
RestResponse - Um wrapper da resposta HTTP
googlemapservice.properties - Um arquivo de propriedades que armazena a chave API
GoogleMapService - Um wrapper de serviço que contém os métodos do wrapper que utiliza RestConnection para fazer chamadas ao serviço Google Map.
No bloco de teste de getGoogleMap(), substitua a instrução print comentada pela linha return result.getDataAsString();. O método agora tem a seguinte aparência:
Abra googlemapservice.properties. Cole na chave de API que você obteve do Google na Etapa 3.
Clique com o botão direito do mouse no nó do projeto CustomerDB e escolha Testar serviços Web RESTful. O IDE implanta e reimplanta seu projeto no servidor e abre uma janela do navegador com o cliente de teste.
Clique em customers na barra lateral esquerda. Critérios de teste para customers aberto no painel principal. Deixe os padrões e clique em Testar. Uma tabela de clientes se abre.
Na tabela, clique em customer1. Uma janela de teste desse cliente se abre no painel principal. No menu suspenso, selecione o tipo MIME text/html. Clique em Testar. O GoogleMap de 16 Network Circle, Menlo Park se abre na Visualização bruta.
O mapa do Google do endereço Menlo Park aparece para todos os clientes no banco de dados. Para exibir os mapas do Google dos endereços reais dos clientes, crie uma instância de cliente para cada entidade no banco de dados e defina o endereço como igual a uma concatenação de variáveis de endereço de cada cliente. Se você estiver usando uma versão anterior do IDE do que 6.5, adicione também uma linha no fim do bloco de teste para fechar a instância de cliente. O método agora tem a seguinte aparência (alterações em negrito):
@GET
@Produces("text/html")
public String getGoogleMap() {
try {
Customer c = getEntity();
String address = c.getAddressline1() + " " + c.getAddressline2() + " " +
c.getCity() + " " + c.getState() + " " + c.getZip();
java.lang.Integer zoom = 15;
String iframe = "false";
RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
return result.getDataAsString();
} catch (Exception ex) {
ex.printStackTrace();
}
//O método close() só é necessário com as versões do NetBeans IDE mais recentes que a 6.5
finally {
PersistenceService.getInstance().close();
}
return "";
}
Teste os serviços Web RESTful novamente. Selecione novamente o tipo de MIME text/html MIME dos clientes. Um mapa do Google do endereço desse cliente no banco de dados agora é exibido na Visualização bruta. Para customer1, o mapa seguinte é exibido:
Observação: Se o GoogleMaps não encontrar um endereço, ele mostra uma visualização aproximada do oceano.
Começando no NetBeans IDE 6.5 e Jersey 0.8, o Jersey é integrado no Spring Framework. Quando você cria um aplicativo Java Web com a estrutura Spring, um servlet compatível com REST é automaticamente criado. No entanto, o Spring 3 não contém o aopalliance.jar, requerido pelo serviço Web RESTful para introduzir um objeto EntityManager.
Criando um serviço Web RESTful com a estrutura Spring
Para criar serviços Web RESTful com a estrutura Spring, repita os procedimentos descritos neste tutorial, com uma exceção. Quando você cria o aplicativo Java Web no assistente para 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 Terminar. Isso abre o painel Frameworks. Selecione Spring Web MVC e clique em Terminar.
Depois que você criar os serviços RESTful, observe as seguintes diferenças entre o projeto Spring e o projeto criado sem o Spring:
O projeto Spring não possui uma classe chamada PersistenceService.java no pacote customerdb.service.
CustomerResource.java importa org.springframework.transaction.annotation.Transactional e contém inúmeras anotações @Transactional.
Essas diferenças se devem ao fato de a estrutura Spring manipular transações e gerenciamento de entidades, enquanto no outro projeto o IDE tinha que criar uma classe que utilizava javax.transaction.UserTransaction e javax.persistence.EntityManager. A estrutura Spring resulta em um código mais limpo e em uma manipulação de transações e gerenciamento de entidades mais eficientes.
Para mais informações sobre os recursos dos projetos de estrutura Spring no NetBeans IDE, consulte Introdução à estrutura Spring.
Adicionando aopalliance.jar ao projeto
O Spring 3 não contém o aopalliance.jar. O aplicativo precisa desta biblioteca para introduzir o EntityManager. Para corrigir o problema, é necessário baixar este jar e adicioná-lo ao seu classpath. Também é necessário remover as anotações @Error do seu código. Consulte o problema nº 193626 e os fóruns do Spring.
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 .
