| // |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| // |
| |
| = Introdução aos Web Services RESTful |
| :jbake-type: tutorial |
| :jbake-tags: tutorials |
| :jbake-status: published |
| :icons: font |
| :syntax: true |
| :source-highlighter: pygments |
| :toc: left |
| :toc-title: |
| :description: Introdução aos Web Services RESTful - Apache NetBeans |
| :keywords: Apache NetBeans, Tutorials, 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. |
| |
| |
| image::images/netbeans-stamp-80-74-73.png[title="O conteúdo desta página se aplica ao NetBeans IDE 7.2, 7.3, 7.4 e 8.0"] |
| |
| |
| *Para seguir este tutorial, são necessários os recursos e o software a seguir.* |
| |
| |=== |
| |Software ou Recurso |Versão Necessária |
| |
| |link:https://netbeans.org/downloads/index.html[+NetBeans IDE+] |Pacote de download do Java EE |
| |
| |link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+JDK (Java Development Kit)+] |versão 7 ou 8 |
| |
| |Servidor de aplicações em conformidade com Java EE | |
| |
| link:http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html[+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 link:https://glassfish.java.net/download.html[+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: |
| |
| * link:http://jcp.org/en/jsr/detail?id=311[+JSR 311: JAX-RS: A API Java dos Web Services RESTful+] |
| * link:http://jersey.dev.java.net/[+Jersey, a Implementação de Referência JAX-RS (JSR 311) de código-fonte aberto para construir Web services RESTful+] |
| |
| 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. |
| |
| 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 link:http://en.wikipedia.org/wiki/Java_Persistence_API[+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 link:http://download.oracle.com/javaee/5/tutorial/doc/bnbqa.html[+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. |
| |
| image::images/register-mysql-server.png[] |
| |
| [start=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 link:../ide/install-and-configure-mysql-server.html[+Conectando-se a um Banco de dados MySQL+]. |
| |
| image::images/basic-mysql-properties.png[] |
| |
| [start=3] |
| . Inicie o servidor MySQL e conecte-se a ele. Consulte “Iniciando o Servidor MySQL” em link:../ide/install-and-configure-mysql-server.html[+Conectando-se a um Banco de Dados MySQL+]. |
| |
| [start=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. |
| |
| image::images/create-database.png[] |
| |
| [start=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. |
| |
| image::images/new-database-name.png[] |
| |
| [start=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. |
| |
| image::images/create-sample-contents.png[] |
| |
| [start=7] |
| . Clique em Sim. O IDE cria e preenche o banco de dados, e adiciona uma conexão ao banco de dados. |
| |
| image::images/generated-db.png[] |
| |
| |
| == 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. |
| |
| |
| [start=2] |
| . Em Nome do Projeto, digite ``CustomerDB`` . Clique em Próximo. |
| |
| [start=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. |
| |
| image::images/open-wizard.png[] |
| |
| [start=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. |
| |
| image::images/new-mysql-datasource.png[] |
| |
| |
| [start=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): |
| |
| image::images/select-tables.png[title="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"] |
| |
| [start=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 link:http://netbeans.dzone.com/nb-generate-simpler-rest[+NetBeans para Gerar Web Services RESTful Mais Simples+]. |
| |
| image::../../../images_www/articles/71/websvc/rest/entity-classes.png[] |
| |
| [start=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. |
| |
| 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. |
| |
| image::images/class-name-location.png[] |
| |
| 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. |
| |
| image::../../../images_www/articles/71/websvc/rest/configure-test-client.png[] |
| |
| [start=6] |
| . Selecione *Cliente de Teste da Web no Projeto* e clique em Procurar. |
| |
| [start=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. |
| |
| |
| [start=8] |
| . Clique com o botão direito do mouse em WebServiceTest e escolha Executar. |
| |
| [start=9] |
| . Abra seu browser em link:http://localhost:8080/WebServicesTest/test-resbeans.html[+http://localhost:8080/WebServicesTest/test-resbeans.html+] |
| |
| image::../../../images_www/articles/71/websvc/rest/test-rest1.png[title="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`` . |
| |
| |
| [start=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. |
| |
| image::images/test-rest-raw.png[] |
| |
| 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. |
| |
| link:/about/contact_form.html?to=3&subject=Feedback:%20Getting%20Started%20with%20REST%20Services%20in%20NetBeans%20IDE%20[+Enviar Feedback neste Tutorial+] |
| |
| |
| |
| == Consulte Também |
| |
| Para obter mais informações sobre o uso do NetBeans IDE para desenvolver aplicações Java EE, consulte os seguintes recursos: |
| |
| * link:http://netbeans.dzone.com/nb-generate-simpler-rest[+NetBeans para Gerar Web Services RESTful Mais Simples+] |
| * link:../../trails/web.html[+Trilha do Aprendizado de Web services+] |
| * YouTube: link:http://www.youtube.com/watch?v=cDdfVMro99s[+RESTful Web Services, Building and Deploying (Part 1)+] |
| * YouTube: link:http://www.youtube.com/watch?v=_c-CCVy4_Eo[+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 das funcionalidades de desenvolvimento Java EE do NetBeans IDE, link:../../../community/lists/top.html[+inscreva-se na lista de notícias nbj2ee@netbeans.org+]. |
| |