// 
//     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.
//

= SaaS (Software as a Service): Tutorial do Zillow
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: SaaS (Software as a Service): Tutorial do Zillow - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, SaaS (Software as a Service): Tutorial do Zillow

O NetBeans IDE oferece um Gerenciador de Web Services que dá suporte aplicações Software as a Service (SaaS). SaaS refere-se a um modelo de entrega de aplicação de software onde um fornecedor de software desenvolve uma aplicação de software nativo da Web, hospeda e opera a aplicação para uso por seus clientes via Internet. SaaS é um modelo cada vez mais popular para oferecer funcionalidade de software, já que é econômico em termos de custo e recursos de hardware do cliente. O IDE agora facilita para os desenvolvedores de Java acessar todos os serviços SaaS populares na Web.

Este tutorial mostra como usar o SaaS simples fornecido pelo link:http://www.zillow.com/[+zillow.com+]. O Zillow.com é uma empresa de serviços imobiliários on-line baseada em Seattle, Washington, fundada em 2005 por Rich Barton e Lloyd Frink, antigos executivos da Microsoft e fundadores da Expedia. O Zillow permite que os usuários vejam o valor de milhões de casas em todos os Estados Unidos, não apenas aquelas que estão para venda. Além de dar estimativas de valores de casas, ele oferece várias funcionalidades exclusivas, incluindo a alteração no valor de cada casa em um determinado período de tempo (por exemplo, 1, 5 ou 10 anos), views aéreas de casas e preços de casas na área. Desde que possa acessar os dados apropriados, ele também fornece informações básicas sobre uma determinada casa, como metragem e o número de quartos e banheiros. Os usuários também podem obter estimativas atuais de casas, caso tenha havido alguma alteração significativa.

Neste tutorial, você exibe um gráfico que mostra a média de preços de casas em uma região dos EUA durante 12 meses. Para configurá-lo, primeiro use o Gerenciador de Serviços para inserir a operação ZillowRealEstateService.GetRegionChart em um servlet. O IDE trata a infraestrutura básica, mas você precisa modificar o código do servlet para extrair o URL do Gráfico da Região. Este tutorial mostra como usar objetos JAXB para extrair o URL. Esta é a abordagem mais simples.


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 ou Web compatível com Java EE |Servidor Web Tomcat 7.x, 8.x, GlassFish Server Open Source Edition 3.1.x, 4.x ou link:http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html[+Oracle WebLogic Server 11g-12c+]
*Importante:* se você usar o Tomcat com este tutorial, consulte 
link:http://wiki.netbeans.org/DeployREST2Tomcat55[+o Wiki do NetBeans sobre Tomcat com REST+] 
|===


== Registrando para Receber a Chave de API Zillow

Os serviços Zillow usam a autenticação de chave de API. link:http://www.zillow.com/webservice/Registration.htm[+Inscreva-se no Zillow aqui+] para receber uma chave de API. Você precisará preencher um form de registro, mas o registro é gratuito.

Outros serviços usam Autenticação HTTP, assinatura de cabeçalho ou log-in do usuário para autenticação. Esses mecanismos serão abordados em futuros tutoriais.


== Criando o Servlet

O IDE permite que você insira operações SaaS em servlets, serviços RESTful existentes, páginas JSP ou POJOs (plain Java objects, objetos Java simples). Neste tutorial, você cria uma aplicação Web com um servlet.

*Para criar o servlet:*

1. Escolha Arquivo > Novo Projeto. Em Categorias, selecione Java Web. Em Projetos, selecione Aplicação Web e clique em Próximo.
2. No campo Nome do Projeto, digite  ``ZillowRegionChart`` .
3. Selecione o GlassFish Server ou o servidor Tomcat e o Java EE 6 ou 7. Clique nas opções restantes e clique em Finalizar.
4. Clique com o botão direito do mouse no nó do projeto ZillowRegionChart e selecione Propriedades na janela de contexto. A caixa de diálogo Propriedades do Projeto será aberta.
5. Clique com o botão direito do mouse no nó do projeto e selecione Novo > Servlet. O assistente Novo Servlet será aberto. 
image::images/new-zillow-servlet.png[title="Assistente Novo Servlet com ZillowRegionChartServlet"]
6. Chame o servlet de ZillowRegionChartServlet. Crie um pacote arbitrário para ele, como zillow.regionchart. Mantenha todos os outros defaults e clique em Finalizar.

O servlet será aberto em uma guia do editor e o servlet e seu pacote pai ficam visíveis na view Projetos, no nó Pacotes de Códigos-Fonte do projeto.

image::images/zillow-project-new.png[title="Guia Projetos no IDE que mostra novo servlet"]


== Adicionando a Operação GetRegionChart do Zillow ao servlet

Use o Gerenciador de Serviços para adicionar a funcionalidade SaaS do Zillow em seu servlet. O IDE cuida de toda a infraestrutura para você.

*Para adicionar a operação GetRegionChart:*

1. Abra a guia Serviços no IDE. Expanda o nó Web Services. Navegue para a operação GetRegionChart do Zillow. 
image::images/z-llow-getregionchart.png[title="Guia Serviços com Web Services e nós Zillow expandidos"]
2. No editor, localize o método processRequest em ZillowRegionChartServlet.java. Adicione uma linha vazia no início do bloco de teste. Arraste e solte a operação getRegionChart no bloco de teste de processRequest().
3. A caixa de diálogo Personalizar SaaS GET será aberta. Você pode indicar os valores reais de cidade, estado e CEP dos EUA ou deixá-los como nulo. (Se você deixar valores nulos, obterá um gráfico da média de preços de casa para todo o país.) Clique em OK.

O IDE gera o código do serviços SaaS GET. Quando isso estiver concluído, o método processRequest() terá a seguinte aparência.


image::images/droppedcode.png[title="Código do servlet que mostra o bloco de teste getRegionChart digitado"]

O IDE também cria dois novos pacotes,  ``org.netbeans.saas``  e  ``org.netbeans.saas.zillow`` , contendo a conexão RESTful e as classes específicas do Zillow, respectivamente. A estrutura completa do pacote é mostrada abaixo. O IDE também importa as classes  ``RestConnection``  e  ``ZillowRealEstateService``  em seu servlet.

image::images/zillow-project-complete.png[title="Estrutura completa do projeto ZillowRegionChart"]


== Adicionando a Chave de API ao Projeto

Para que o projeto acesse os serviços do Zillow, você precisa passar a chave de API que obteve quando se <<get-api-key,registrou>>. Abra o arquivo  ``zillowrealestateserviceauthenticator.properties``  e copie e cole na chave de API que você recebeu no e-mail do Zillow que confirmava o seu registro


==  Modificando o Servlet para Retornar o Gráfico

O servlet que você criou não produz uma saída útil. Para fazer com que o Gráfico da Região apareça em um browser, você precisa extrair o URL do gráfico da String que o serviço do Zillow retorna, que está no formato de um arquivo XML. Uma estratégia é fazer parsing do arquivo XML e colar o URL em uma página JSP. Essa abordagem é descrita no artigo link:http://netbeans.dzone.com/news/consuming-zillow-web-services-[+Consuming Zillow Web Services+] de Adam Myatt na NetBeans Zone. Neste tutorial, você usa uma abordagem mais simples envolvendo objetos JAXB.

*Para retornar ao gráfico: *

1. Modifique a linha de saída  ``[Code]#//out.println("The SaasService returned: "+result.getDataAsString());#`` . Retire o comentário da linha e altere-o para produzir uma tag HTML <img> em vez de texto. Tenha cuidado para sair das aspas que irão circundar o URL! A linha agora tem a seguinte aparência:

[source,java]
----

out.println("<img src=\""+result.getDataAsString() + "\" />");
----
2. Mova a linha de saída para dentro do bloco  ``if`` , no final. O bloco  ``if``  agora se parece com:

[source,java]
----

if (result.getDataAsObject(zillow.realestateservice.regionchart.Regionchart.class) instanceof
  zillow.realestateservice.regionchart.Regionchart) {
        zillow.realestateservice.regionchart.Regionchart resultObj = result.getDataAsObject(zillow.realestateservice.regionchart.Regionchart.class);
        out.println("<img src=\"" + result.getDataAsString() + "\" />");
}
----
3. Substitua o método  ``result.getDataAsString()``  na saída por  ``resultObj.getResponse().getUrl()`` . Você pode usar a funcionalidade autocompletar código para selecionar  ``getResponse()``  de métodos  ``resultObj``  diferentes, como mostrado abaixo e, em seguida, usar a funcionalidade autocompletar código para selecionar  ``getUrl()``  de métodos  ``getResponse`` . 
image::images/zillow-getresponse-cc.png[title="Editor que mostra a funcionalidade autocompletar código para métodos resultObj"]
4. Altere o bloco catch para interceptar  ``JAXBException``  em vez de  ``Exception`` . Você também pode usar um método  ``Logger.getLogger(...)``  em vez de imprimir um rastreamento de pilha. Você terá que importar as classes relevantes. Veja se você pode usar a funcionalidade autocompletar código e a ação do menu de contexto Corrigir Importações para reproduzir o seguinte bloco catch:

[source,java]
----

} catch (JAXBException ex) {
    Logger.getLogger(ZillowRegionChartServlet.class.getName()).log(Level.SEVERE, null, ex);
}
----
5. Remova a seção de saída comentada do bloco try pai no código do servlet.

Suas modificações no código agora estão completas! O código final do servlet deve ter a seguinte aparência:


[source,java]
----

package zillow.regionchart;

import java.io.IOException;
import java.io.PrintWriter;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.bind.JAXBException;
import org.netbeans.saas.zillow.ZillowRealEstateService;
import org.netbeans.saas.RestResponse;

/**
 *
 * @author jeff
 */
public class ZillowRegionChartServlet extends HttpServlet {

    /** 
     * Processes requests for both HTTP 

[source,java]
----

GET
----
 and 

[source,java]
----

POST
----
 methods.
     * @param request servlet request
     * @param response servlet response
     * @throws ServletException if a servlet-specific error occurs
     * @throws IOException if an I/O error occurs
     */
    protected void processRequest(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        PrintWriter out = response.getWriter();
        try {

            try {
                String unittype = "dollar";
                String city = null;
                String state = null;
                String zIP = null;
                String width = null;
                String height = null;
                String chartduration = null;

                RestResponse result = ZillowRealEstateService.getRegionChart(
                        unittype, city, state, zIP, width, height, chartduration);
                if (result.getDataAsObject(
                        zillow.realestateservice.regionchart.Regionchart.class) instanceof zillow.realestateservice.regionchart.Regionchart) {
                    zillow.realestateservice.regionchart.Regionchart resultObj =
                            result.getDataAsObject(
                            zillow.realestateservice.regionchart.Regionchart.class);
                    out.println("<img src=\"" + resultObj.getResponse().getUrl() + "\" />");

                }
                //TODO - Uncomment the print Statement below to print result.

            } catch (JAXBException ex) {
                Logger.getLogger(ZillowRegionChartServlet.class.getName()).log(Level.SEVERE, null, ex);
            }
        } finally {
            out.close();
        }
    }
----


== Executando o Servlet do Gráfico da Região Zillow

A forma mais simples de executar o servlet é clicar com botão direito do mouse no servlet na view Projetos e selecionar Executar Arquivo. Como alternativa, clique com o botão direito do mouse no nó Projeto e selecione Propriedades. Na árvore Propriedades, selecione Executar. No campo URL relativo, digite /ZillowRegionChartServlet, como mostrado abaixo. Clique em OK e execute o projeto.

image::images/zillow-run-properties.png[title="Caixa de diálogo Propriedades do projeto ZillowRegionChart"]

Quando você executa o projeto com êxito, uma janela do browser é aberta mostrando o Gráfico da Região.

image::images/zillow-chart.png[title="Gráfico da região Zillow"]


== Mais Exercícios

A seguir, encontam-se mais algumas ideias para você explorar:

* Tente valores reais diferentes para cidade, estado e CEP. Execute o servlet novamente.
* Crie um cliente que permita que você passe a cidade, o estado e o CEP para o serviço e retorne o Gráfico da Região correspondente.
* Use uma página JSP, em vez do objeto JAXB, para retornar o gráfico, como mostrado neste link:http://netbeans.dzone.com/news/consuming-zillow-web-services-[+artigo da NetBeans Zone+].


link:/about/contact_form.html?to=3&subject=Feedback:%20Using%20SaaS%20Zillow[+Enviar Feedback neste Tutorial+]


== Consulte Também

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

* link:./rest.html[+Introdução aos Web services RESTful+]
* link:http://wiki.netbeans.org/JavaClientForDeliciousUsingNetBeans[+Criando um Cliente Java para RESTful Web Services del.icio.us+], de Amit Kumar Saha
* link:http://wiki.netbeans.org/RESTRemoting[+NetBeans Wiki: Stub de Cliente de do RESTful Web Services+]
* 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+].