netbeans.apache.org/src/old_content/content/tutorials/67/nbm-quick-search_pt_BR.adoc

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

= Tutorial de integração de Pesquisa rápida
:jbake-type: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: Tutorial de integração de Pesquisa rápida - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, Tutorial de integração de Pesquisa rápida

Este tutorial mostra como escrever um módulo que integre novos itens no recurso Pesquisa rápida do NetBeans.








Opcionalmente, para fins de solução de problemas, você pode  link:http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=11179[baixar a amostra completa] e inspecionar os códigos-fonte.


== Introdução à integração da Pesquisa rápida

O recurso Pesquisa rápida, introduzido no NetBeans IDE 6.5, consiste em um campo de texto no canto superior direito do IDE. Quando uma string de pesquisa é digitada no campo, uma lista suspensa aparece, mostrando os itens correspondentes. Por padrão, os itens vêm de nomes de ações registradas no IDE, assim como tópicos de ajuda no JavaHelp do IDE. Quando um item de ação é selecionado, uma ação é chamada; quando um item de ajuda é selecionado, o tópico é aberto no JavaHelp.

Entretanto, além disso, a  link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/overview-summary.html[API da Pesquisa rápida] é exposta. Você pode usá-la para integrar seus próprios itens de pesquisa no recurso Pesquisa rápida. Você pode usar o recurso no IDE ou como parte de seu próprio aplicativo na plataforma NetBeans.

Neste tutorial, você criará um módulo que integrará itens da  link:http://netbeans.dzone.com[zona do NetBeans ] com o recurso Pesquisa rápida:


image::images/qsearch_deployed-result.png[]


== Criando o projeto do módulo

Nesta seção, usaremos um assistente para criar a estrutura de código-fonte que todo módulo NetBeans precisa. A estrutura do código-fonte consiste em determinadas pastas em locais específicos e em um conjunto de arquivos que sempre são necessários. Por exemplo, cada módulo NetBeans requer uma pasta  ``nbproject`` , que contém os metadados do projeto, e um arquivo  ``layer.xml`` , para registro de declaração de itens como janelas e botões da barra de ferramentas.


[start=1]
1. Escolha Arquivo > Novo projeto (Ctrl-Shift-N). Em Categorias, selecione Módulos do NetBeans. Em Projetos, selecione Módulo e clique em Próximo.

[start=2]
1. No painel Nome e localização, digite  ``NetBeansZoneSearch``  em Nome do projeto. Altere a Localização do projeto para qualquer diretório no computador, como  ``c:\meusmodulos`` . Deixe o botão de opção Módulo independente selecionado. O painel agora deve ter esta aparência:


image::images/qsearch_new-module-1.png[]

Clique em Próximo.


[start=3]
1. No painel Configuração básica de módulos, digite  ``org.netbeans.modules.nbzone``  como o Nome base de código. Adicione espaços ao Nome de exibição do módulo sugerido, para que ele seja alterado para  ``Pesquisa na zona do NetBeans`` . Marque a caixa de verificação "Gerar camada XML" e deixe o pacote de localização e a camada XML onde estão, para que eles sejam armazenados em um pacote com o nome  ``org/netbeans/modules/nbzone`` . O painel agora deve ter esta aparência:


image::images/qsearch_new-module-2.png[]


[start=4]
1. Clique em Terminar.

O IDE cria o projeto  ``Pesquisa na zona do NetBeans`` . O projeto contém todos os metadados de projeto e fontes, como o script de construção Ant do projeto. O projeto se abre no IDE. Você pode ver a estrutura lógica na janela Projetos (Ctrl-1) e a estrutura de arquivos na janela Arquivos (Ctrl+2). 


== Usando o assistente do provedor de Pesquisa rápida

Nesta seção, usaremos um assistente para criar a classe stub e entradas de camada necessárias para começar a integração com o recurso Pesquisa rápida.


[start=1]
1. Clique com o botão direito do mouse no nó do projeto e escolha Novo > Outro. Na caixa de diálogo Novo arquivo, escolha Desenvolvimento de módulo > Provedor da pesquisa rápida.

[start=2]
1. No painel Provedor da pesquisa rápida, defina o seguinte:

* *Nome da classe do provedor.* Especifica o nome da classe do stub que o assistente irá gerar. Digite "NBZoneSearchProvider" neste campo.
* *Pacote.* Especifica o pacote em que a classe do stub será gerada. Selecione "org.netbeans.modules.nbzone" da lista suspensa.
* *Nome de exibição da categoria.* Especifica o nome de exibição da categoria que o stub criará. Digite "NetBeans Zone" neste campo.
* *Prefixo do comando.* Especifica o prefixo para limitar a pesquisa à categoria que o stub criará. Digite "nb" neste campo.
* *Posição no pop-up.* Especifica a posição da nova categoria no recurso Pesquisa rápida. Deixe "0", para que a categoria seja a primeira no pop-up.

Agora você deve ver o seguinte:


image::images/qsearch_quick-search-template.png[]


[start=3]
1. Clique em Terminar.

A janela Projetos agora deve ter esta aparência:


image::images/qsearch_projects-window-final.png[]

No arquivo  ``layer.xml`` , você deve ver o seguinte:


[source,xml]
----

<filesystem>
    <folder name="QuickSearch">
        <folder name="NetBeansZone">
            <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.nbzone.Bundle"/>
            <attr name="command" stringvalue="nb"/>
            <attr name="position" intvalue="0"/>
            <file name="org-netbeans-modules-nbzone-NBZoneSearchProvider.instance"/>
        </folder>
    </folder>
</filesystem>
----



== Integrando um analisador HTML DOM externo

Na próxima seção, precisaremos de um analisador HTML DOM para podermos analisar a zona do NetBeans. Você pode usar qualquer analisador apropriado que escolher. Para a finalidade deste tutorial, usaremos  link:http://sourceforge.net/project/showfiles.php?group_id=13153[JTidy].

Há duas maneiras de tornar um arquivo JAR externo disponível para um módulo. A primeira maneira é colocar o JAR em um módulo separado, chamado de "módulo de wrapper de bibliotecas" , e fazer do módulo de funcionalidade _depend on_ o módulo de wrapper de bibliotecas, depois de colocar ambos em uma suíte de módulos. A vantagem de ter dois módulos separados é que, quando uma nova versão do JAR externo for liberada, você só precisará redistribuir um módulo pequeno contendo somente o JAR externo, em vez de um grande que também contenha o código de funcionalidade. A segunda maneira é adicionar o JAR ao módulo de funcionalidade, o que é feito abaixo. A vantagem desta abordagem é que ela é mais conveniente somente em curto prazo, já que você possui apenas um módulo para distribuir, embora a desvantagem seja que você está misturando a biblioteca externa com o código de funcionalidade, o que não é uma abordagem estritamente modular.


[start=1]
1. Baixe o  link:http://sourceforge.net/project/showfiles.php?group_id=13153[JTidy] e localize o  ``Tidy.jar``  que está no download.

[start=2]
1. Na janela Arquivos, crie a estrutura de pasta mostrada abaixo, colocando o arquivo  ``Tidy.jar``  na pasta  ``release/modules/ext`` :


image::images/qsearch_tidyjar.png[]


[start=3]
1. Mais para o final do arquivo  ``project.xml`` , que está na pasta  ``nbproject`` , adicione as marcas de negrito abaixo, por exemplo, próximo ao final do arquivo:

[source,xml]
----


            ...
            ...
            ...
            *<class-path-extension>
                <runtime-relative-path>ext/Tidy.jar</runtime-relative-path>
                <binary-origin>release/modules/ext/Tidy.jar</binary-origin>
            </class-path-extension>*
        </data>
    </configuration>
 </project>
----


[start=4]
1. No arquivo  ``project.properties`` , adicione a seguinte linha:

[source,java]
----

cp.extra=release/modules/ext/Tidy.jar
----

O analisador HTML DOM externo agora está no classpath do seu módulo. Agora você pode usar as classes no JAR, como você precisará fazer na próxima seção.


== Codificando a integração da Pesquisa rápida

Em seguida, implementaremos a API. As classes da API são as seguintes:

|===
|Classe |Descrição 

| link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchProvider.html[SearchProvider] |A principal interface da API da Pesquisa rápida. Implemente esta interface para fornecer um novo grupo de resultados para a sua pesquisa rápida. 

| link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchRequest.html[SearchRequest] |A descrição da requisição de pesquisa rápida. 

| link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchResponse.html[SearchResponse] |O objeto da resposta para coletar os resultados de SearchRequest. 
|===

Abaixo, definiremos dependências nos módulos necessários e depois as implementaremos no seu próprio módulo.


[start=1]
1. Clique com o botão direito do mouse no projeto, escolha Propriedades e defina as dependências a seguir no painel Bibliotecas:


image::images/qsearch_set-dependencies.png[]


[start=2]
1. Abra a classe gerada.

[start=3]
1. Modifique a classe da seguinte maneira:

[source,java]
----

public class NBZoneSearchProvider implements  link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchProvider.html[SearchProvider] {

    /**
     * Method is called by infrastructure when search operation is requested.
     * Implementors should evaluate given request and fill response object with
     * apropriate results
     *
     * @param request Search request object that contains search string
     * @param response Search response object that stores search results 
     * Note that it's important to react to return value of 
     * SearchResponse.addResult(...) method and stop computation if 
     * false value is returned.
     */
    @Override 
    public void evaluate( link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchRequest.html[SearchRequest request],  link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchResponse.html[SearchResponse response]) {
        try {

            *//The URL that we are providing a search for:*
            URL url = new URL("http://netbeans.dzone.com");
            *//Stuff needed by Tidy:*
            Tidy tidy = new Tidy();
            tidy.setXHTML(true);
            tidy.setTidyMark(false);
            tidy.setShowWarnings(false);
            tidy.setQuiet(true);

            *//Get the org.w3c.dom.Document from Tidy,
            //or use a different parser of your choice:*
            Document doc = tidy.parseDOM(url.openStream(), null);

            *//Get all "a" elements:*
            NodeList list = doc.getElementsByTagName("a");

            *//Get the number of elements:*
            int length = list.getLength();

            *//Loop through all the "a" elements:*
            for (int i = 0; i < length; i++) {

                String href = null;
                if (null != list.item(i).getAttributes().getNamedItem("href")) {
                    *//Get the "href" attribute from the current "a" element:*
                    href = list.item(i).getAttributes().getNamedItem("href").getNodeValue();
                }

                *//Get the "title" attribute from the current "a" element:*
                if (null != list.item(i).getAttributes().getNamedItem("title")) {
                    String title = list.item(i).getAttributes().getNamedItem("title").getNodeValue();

                    *//If the title matches the requested text:*
                    if (title.toLowerCase().indexOf( link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchRequest.html[request.getText().toLowerCase()]) != -1) {

                        *//Add the runnable and the title to the response
                        //and return if nothing is added:*
                        if (! link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchResponse.html[response.addResult(new OpenFoundArticle(href), title)]) {
                            return;
                        }

                    }

                }

            }

        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
    }

    private static class OpenFoundArticle implements Runnable {

        private String article;

        public OpenFoundArticle(String article) {
            this.article = article;
        }

        public void run() {
            try {
                URL url = new URL("http://netbeans.dzone.com" + article);
                StatusDisplayer.getDefault().setStatusText(url.toString());
                URLDisplayer.getDefault().showURL(url);
            } catch (MalformedURLException ex) {
                Logger.getLogger(NBZoneSearchProvider.class.getName()).log(Level.SEVERE, null, ex);
            }
        }
        
    } 
    
 }
----


[start=4]
1. Certifique-se de que as seguintes sentenças import sejam declaradas:

[source,java]
----

import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.netbeans.spi.quicksearch.SearchProvider;
import org.netbeans.spi.quicksearch.SearchRequest;
import org.netbeans.spi.quicksearch.SearchResponse;
import org.openide.awt.HtmlBrowser.URLDisplayer;
import org.openide.awt.StatusDisplayer;
import org.openide.util.Exceptions;
import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
import org.w3c.tidy.Tidy;
----


== Instalando e testando a funcionalidade

Agora vamos instalar o módulo e usar a integração do recurso pesquisa rápida. O IDE utiliza um script de construção Ant para construir e instalar seu módulo. O script de construção é criado quando o projeto é criado.


[start=1]
1. Na janela Projetos, clique com o botão direito do mouse no projeto e escolha Executar.

Uma nova instância do IDE é iniciada e instala o módulo de integração da Pesquisa rápida.


[start=2]
1. Digite uma string no recurso Pesquisa rápida e, se a string corresponder ao título de algo na zona do NetBeans, o item da zona do NetBeans será incluído no resultado:


image::images/qsearch_deployed-result.png[]

Se você digitar o prefixo do comando definido em  ``layer.xml`` , seguido de um espaço, somente a categoria relacionada será pesquisada:


image::images/qsearch_command.png[]


[start=3]
1. Clique em um item e, se você tiver definido um navegador no IDE, ele será aberto, exibindo o artigo selecionado.



== Usando o recurso Pesquisa rápida na plataforma NetBeans

As seções anteriores assumiram que você estava criando um módulo para um aplicativo existente. Os dois tópicos a seguir serão aplicáveis se, em vez de criar um módulo, você estiver criando seu próprio aplicativo na plataforma NetBeans.


=== Habilitando o recurso Pesquisa rápida na plataforma NetBeans

Embora o NetBeans IDE venha com suporte para o recurso Pesquisa rápida, a plataforma NetBeans não vem. Por padrão, o recurso Pesquisa rápida está oculto. Realize as etapas abaixo para habilitá-lo.


[start=1]
1. Adicione as marcas seguintes ao arquivo  ``layer.xml`` :

[source,xml]
----

<folder name="Toolbars">
    <folder name="QuickSearch">
        <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.nbzone.Bundle"/>
        <file name="org-netbeans-modules-quicksearch-QuickSearchAction.shadow">
            <attr name="originalFile" 
            stringvalue="Actions/Edit/org-netbeans-modules-quicksearch-QuickSearchAction.instance"/>
        </file>
    </folder>
</folder>
----


[start=2]
1. Adicione este par chave/valor ao arquivo  ``Bundle.properties`` :

[source,java]
----

Toolbars/QuickSearch=Quick Search
----


[start=3]
1. Execute o aplicativo da plataforma NetBeans e você verá que o recurso Pesquisa rápida agora está disponível e funcionando:


image::images/qsearch_netbeans-platform-qsearch.png[]


=== Habilitando o provedor de pesquisa na Web padrão na plataforma NetBeans

Uma implementação de provedor de pesquisa na Web padrão está disponível nos códigos-fonte do NetBeans. Este provedor pesquisa no Google por textos que correspondam à string de pesquisa. No IDE, sua função era pesquisar no  ``netbeans.org`` , e em sites relacionados, por documentação on-line relacionada ao IDE.

*Observação:* infelizmente, o provedor de pesquisa na Web foi desabilitado no IDE porque, após o uso excessivo, o Google reclamava que as pesquisas automatizadas são contra seus termos de uso, parando de funcionar.

Se você aceitar a limitação acima, poderá marcar este provedor de pesquisa na Web e usá-lo no seu aplicativo da plataforma NetBeans.


[start=1]
1. Verifique se o recurso Pesquisa rápida está habilitado, como descrito na seção anterior.

[start=2]
1. Adicione as marcas seguintes ao arquivo  ``layer.xml`` :

[source,xml]
----

<folder name="Guardian">
   <file name="org-netbeans-modules-quicksearch-web-WebQuickSearchProviderImpl.instance"/>
</folder>
----


[start=3]
1. Na pasta  ``branding``  do aplicativo, crie a hierarquia de pastas mostrada abaixo, assim como o arquivo  ``Bundle.properties``  exibido no instantâneo:


image::images/qsearch_brand-provider.png[]

No IDE, as propriedades acima são codificadas da seguinte maneira, mas para a plataforma NetBeans elas são indefinidas, e precisam ser marcados como mostrado acima:


[source,java]
----

quicksearch.web.site=netbeans.org
quicksearch.web.url_patterns=.*netbeans\.org/kb.*,\
    /.*wiki\.netbeans\.org/.*faq.*,.*wiki\.netbeans\.org/.*howto.*,\
    .*platform\.netbeans\.org/tutorials.*
----


[start=4]
1. Execute o aplicativo da plataforma NetBeans e você verá que o provedor da Pesquisa rápida na Web padrão agora está disponível e funcionando:


image::images/qsearch_clare-wigfall.png[]


== Criando um binário de módulo que pode ser compartilhado

Agora que o módulo está concluído, você pode permitir que ele seja utilizado por outras pessoas. Para isso, você precisa criar um arquivo "NBM" (módulo NetBeans) binário e distribui-lo.


[start=1]
1. Na janela Projetos, clique com o botão direito do mouse no projeto  ``Pesquisa na zona do NetBeans``  e escolha Criar NBM.

O arquivo NBM é criado e você pode visualizá-lo na janela Arquivos (Ctrl+-2):


image::images/qsearch_shareable-binary.png[]


[start=2]
1. Disponibilize-o para outras pessoas, por exemplo, através do  link:http://plugins.netbeans.org/PluginPortal/[Portal de plug-in do NetBeans]. O destinatário deve usar o Gerenciador de plug-ins (Ferramentas > Plug-ins) para instalá-lo.


link:http://netbeans.apache.org/community/mailing-lists.html[Envie-nos seus comentários]



== Próximas etapas

Para obter mais informações sobre a criação e o desenvolvimento de módulos do NetBeans, consulte os seguintes recursos:

*  link:https://netbeans.apache.org/platform/index.html[Página inicial da Plataforma NetBeans ]
*  link:https://bits.netbeans.org/dev/javadoc/[Lista de APIs do NetBeans (Versão de desenvolvimento atual)]
*  link:https://netbeans.apache.org/tutorials[Outros tutoriais relacionados]