netbeans.apache.org/src/old_content/content/tutorials/68/nbm-quick-search_ru.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.
//

= Учебный курс по интеграции быстрого поиска
:jbake-type: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: Учебный курс по интеграции быстрого поиска - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, Учебный курс по интеграции быстрого поиска

В этом руководстве показан способ написания модуля, интегрирующего новые элементы в функцию быстрого поиска NetBeans.








Дополнительно, в целях поиска и устранения ошибок, можно  link:http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=11179[загрузить готовый пример] и изучить исходный код.


== Введение в интеграцию быстрого поиска

Функция быстрого поиска, впервые появившаяся в среде IDE NetBeans 6.5, состоит из текстового поля в правом верхнем углу среды IDE. При вводе строки поиска в это поле выводится раскрывающийся список совпадающих элементов. По умолчанию элементами списка являются имена действий, зарегистрированных в среде IDE, а также темы справки по Java среды IDE. Выбранное действие вызывается, а выбранная тема справки открывается в JavaHelp.

Однако также предоставляется для использования  link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/overview-summary.html[интерфейс API быстрого поиска]. С его помощью в функцию быстрого поиска можно интегрировать собственные объекты для поиска. Этой функцией можно пользоваться как в рамках среды IDE, так и в собственных приложениях, построенных на платформе NetBeans.

В этом руководстве показан способ написания модуля, интегрирующего новые элементы из  link:http://netbeans.dzone.com[NetBeans Zone] в функцию быстрого поиска.


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


== Создание проекта модуля

В этом разделе используется мастер для создания структуры исходного кода, требуемого любым модулем NetBeans. Эта структура исходного кода состоит из ряда папок в особых местах и набора файлов, которые требуются в любом случае. Например, для каждого модуля NetBeans требуется папка  ``nbproject`` , в которой хранятся метаданные проекта, а также файл  ``layer.xml`` , в котором объявляется регистрация таких элементов как кнопки панелей управления и окна.


[start=1]
1. Выберите "File" > "New Project" (Ctrl+Shift+N). В разделе "Категории" выберите параметр "Модули NetBeans". В области "Проекты" выберите "Модуль" и нажмите кнопку "Далее".

[start=2]
1. На панели "Имя и расположение" в поле "Имя проекта" введите  ``NetBeansZoneSearch`` . В поле "Расположение проекта" укажите любой каталог на компьютере, например  ``c:\mymodules`` . Оставьте переключатель "Отдельный модуль" выбранным. Панель должна выглядеть следующим образом:


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

Нажмите кнопку "Далее".


[start=3]
1. На панели "Основные настройки модуля" введите  ``org.netbeans.modules.nbzone``  в поле "Основа кодового имени". Добавьте пробелы к предложенному отображаемому имени модуля, и измените его на  ``NetBeans Zone Search`` . Установите флажок "Создать слой XML" и оставьте местоположение локализуемого файла ресурсов и слоя XML по умолчанию; при этом они будут храниться в пакете с именем  ``org/netbeans/modules/nbzone`` . Панель должна выглядеть следующим образом:


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


[start=4]
1. Нажмите кнопку "Готово".

В среде IDE создается проект  ``NetBeans Zone Search`` . Проект содержит все исходные файлы и метаданные проекта, например, сценарий сборки проекта Ant. Проект откроется в среде IDE. Логическую структуру проекта можно просмотреть в окне "Проекты" (Ctrl+1), а его файловую структуру – в окне "Файлы" (Ctrl+2). 


== Использование диалогового окна "Поставщик быстрого поиска"

В этом разделе с помощью мастера будет создан класс заглушки и сущности слоя, необходимые для начала интеграции с функцией быстрого поиска.


[start=1]
1. Щелкните узел проекта правой кнопкой мыши и выберите команду "Создать > Прочее". В диалоговом окне "Новый файл" выберите "Разработка модулей > Поставщик быстрого поиска".

[start=2]
1. Установите следующие значения на панети "Поставщик быстрого поиска":

* *Имя класса поставщика.* Имя класса для заглушки, генерируемой мастером. Введите в это поле значение "NBZoneSearchProvider".
* *Пакет.* Пакет, в котором будет создан класс заглушки. Выберите в раскрывающемся списке пункт "org.netbeans.modules.nbzone".
* *Отображаемое имя категории.* Отображаемое имя для категории, создаваемой с помощью заглушки. Введите в это поле значение "NetBeans Zone".
* *Префикс команды.* Префикс для сужения поиска до категории, создаваемой с помощью заглушки. Введите в это поле значение "nb".
* *Позиция в контекстном меню.* Выберите позицию новой категории в пределах функции быстрого поиска. Значение по умолчанию "0" соответствует размещению категории в первой позиции.

На экране должны быть представлены следующие параметры:


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


[start=3]
1. Нажмите кнопку "Готово".

Окно "Проекты" должно выглядеть следующим образом:


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

В файле  ``layer.xml``  должен содержаться следующий текст:


[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>
----



== Интеграция внешнего синтаксического анализатора HTML DOM

В следующем разделе потребуется синтаксический анализатор HTML DOM для синтаксического анализа NetBeans Zone. Можно воспользоваться любым подходящим синтаксическим анализатором по выбору. В данном учебным курсе используется  link:http://sourceforge.net/project/showfiles.php?group_id=13153[JTidy].

Существует два способа предоставления внешнего файла JAR для использования в модуле. Первый способ состоит в размещении файла JAR в отдельном модуле, так называемом "модуле-обертке библиотеки"; в таком случае модуль функциональных возможностей _зависит от_ модуля-обертки библиотеки. Оба модуля размещаются в наборе модулей. Преимущество использования двух раздельных модулей заключается в том, что при выпуске новой версии внешнего файла JAR требуется распространить небольшой по объему модуль, содержащий только внешний файл JAR, а не крупный модуль, содержащий также код функциональных возможностей. Второй способ заключается в добавлении файла JAR к модулю функциональных возможностей, как показано ниже. Преимущество этого подхода заключается в большем удобстве в краткосрочной перспективе, поскольку распространять требуется только один модуль, однако недостаток заключается в смешении внешней библиотеки с кодом функциональных возможностей, что нарушает принцип модульности.


[start=1]
1. Загрузите  link:http://sourceforge.net/project/showfiles.php?group_id=13153[JTidy] и найдите файл  ``Tidy.jar``  в пакете загрузки.

[start=2]
1. В окне "Файлы" создайте структуру папок, показанную ниже, и разместите файл  ``Tidy.jar``  в папке  ``release/modules/ext`` :


image::images/qsearch_tidyjar.png[]


[start=3]
1. В конце файла  ``project.xml`` , расположенного в папке  ``nbproject`` , добавьте теги, выделенные полужирным шрифтом:

[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. Добавьте следующую строку в файл  ``project.properties`` :

[source,java]
----

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

Внешний синтаксический анализатор HTML DOM теперь включен в путь к классам модуля. Теперь эти классы можно использовать в файле JAR; эта возможность будет реализована в следующем разделе.


== Написание кода интеграции быстрого поиска

Далее необходимо реализовать интерфейс API. Используются следующие классы интерфейса API:

|===
|Класс |Описание 

| link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchProvider.html[SearchProvider] |Главный интерфейс API быстрого поиска. Этот интерфейс необходимо реализовать для предоставления новой группы результатов для быстрого поиска. 

| link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchRequest.html[SearchRequest] |Описание запроса на быстрый поиск. 

| link:http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-quicksearch/org/netbeans/spi/quicksearch/SearchResponse.html[SearchResponse] |Объект ответа для сбора результатов SearchRequest. 
|===

Ниже указываются зависимости требуемых модулей, которые затем реализуются в собственном модуле.


[start=1]
1. Щелкните правой кнопкой мыши проект, выберите "Свойства", а затем укажите следующие зависимости на панели "Библиотеки":


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


[start=2]
1. Откройте созданный класс.

[start=3]
1. Измените класс следующим образом:

[source,java]
----

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

    /**
     * Метод вызывается инфраструктурой при запросе операции поиска.
     * Реализующие его объекты должны обрабатывать полученный запрос и заполнять объект ответа
     * соответствующими результатами
     *
     * @param request Объект запроса на поиск, содержащий строку поиска
     * @param response Объект ответа поиска, в котором хранятся результаты поиска 
     * Обратите внимание, что важно реагировать на значение, возвращаемое методом 
     * SearchResponse.addResult(...) и останавливать вычисления, 
     * если возвращается значение "false".
     */
    @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 {

            *//Адрес URL, для которого предоставляется поиск:*
            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);

            *//Получение org.w3c.dom.Document от Tidy,
            //или использование другого синтаксического анализатора по выбору:*
            Document doc = tidy.parseDOM(url.openStream(), null);

            *//Получение всех элементов "a":*
            NodeList list = doc.getElementsByTagName("a");

            *//Получение количества элементов:*
            int length = list.getLength();

            *//Итерация по всем элементам "a":*
            for (int i = 0; i < length; i++) {

                String href = null;
                if (null != list.item(i).getAttributes().getNamedItem("href")) {
                    *//Получение атрибута "href" для текущего элемента "a":*
                    href = list.item(i).getAttributes().getNamedItem("href").getNodeValue();
                }

                *//Получение атрибута "title" для текущего элемента "a":*
                if (null != list.item(i).getAttributes().getNamedItem("title")) {
                    String title = list.item(i).getAttributes().getNamedItem("title").getNodeValue();

                    *//Заголовок совпадает с запрошенным текстом:*
                    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) {

                        *//Добавление выполняемого объекта и заголовка к запросу
                        //и возвращение пустого результата, если ничего не добавлено:*
                        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. Убедитесь в том, что определены следующие выражения импорта:

[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;
----


== Установка и ознакомление с функциональными возможностями

Теперь установим модуль и воспользуемся функцией интеграции быстрого поиска. Для построения и установки модуля в среде IDE используется сценарий построения Ant. При создании проекта автоматически создается сценарий построения.


[start=1]
1. В окне "Проекты" щелкните проект правой кнопкой мыши и выберите "Выполнить".

Запускается новый экземпляр среды IDE, и выполняется установка модуля интеграции быстрого поиска.


[start=2]
1. Введите строку в средство быстрого поиска; если строка совпадает с заголовком одного из элементов в NetBeans Zone, к результату добавляется этот элемент из NetBeans Zone.


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

При вводе префикса команды, определенного в файле  ``layer.xml`` , с последующим пробелом, выполняется поиск только по связанной категории:


image::images/qsearch_command.png[]


[start=3]
1. Щелкните элемент, и если в среде IDE настроен обозреватель, в нем выводится выбранная статья.



== Использование функции быстрого поиска в платформе NetBeans

В предыдущих разделах подразумевалось создание модуля для существующего приложения. Оставшиеся две темы имеют смысл, если создается не модуль, а отдельное приложение на платформе NetBeans.


=== Включение функции быстрого поиска в платформе NetBeans

Несмотря на то, что среда IDE NetBeans поставляется с поддержкой функции быстрого поиска, в платформе NetBeans эта функция не предоставляется. По умолчанию функция быстрого поиска скрыта. Для включения этой функции необходимо выполнить шаги, приведенные ниже.


[start=1]
1. Добавьте в файл  ``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. Добавьте в файл  ``Bundle.properties``  следующую пару "ключ-значение":

[source,java]
----

Toolbars/QuickSearch=Quick Search
----


[start=3]
1. Запустите приложение на платформе NetBeans и обратите внимание на то, что функция быстрого поиска доступна для использования и работает.


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


=== Включение поставщика интернет-поиска по умолчанию в платформе NetBeans

В исходных файлах NetBeans доступна реализация поставщика интернет-поиска по умолчанию. Этот поставщик используется для поиска текста, совпадающего со строкой поиска, в Google. В среде IDE эта функция была предназначена для поиска по  ``netbeans.org``  и связанным сайтам, содержищим интерактивную документацию по среде IDE.

NOTE:  К сожалению, поставщик интернет-поиска в среде IDE пришлось отключить, поскольку после продолжительного использования компания Google выступила с жалобой о несоответствии автоматического поиска соглашению об использовании, и работа данной функции была остановлена.

С учетом вышеуказанного ограничения этот поставщик интернет-поиска можно подвергнуть брэндингу и использовать в приложении на платформе NetBeans.


[start=1]
1. Убедитесь в том, что функция быстрого поиска включена, в соответствии с описанием в предыдущем разделе.

[start=2]
1. Добавьте в файл  ``layer.xml``  следующие теги:

[source,xml]
----

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


[start=3]
1. Создайте в папке  ``branding``  приложения иерархию папок, показанную ниже, а также файл  ``Bundle.properties`` , показанный на снимке экрана:


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

В среде IDE вышеупомянутые свойства жестко запрограммированы в следующем коде, однако в платформе NetBeans они не определены, поэтому требуется их брендинг, как показано выше:


[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. Запустите приложение на платформе NetBeans и обратите внимание на то, что поставщик быстрого интернет-поиска по умолчанию доступен для использования и работает.


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


== Создание совместно используемого исполняемого файла модуля

Готовый модуль можно предоставить для использования другими разработчиками. Для этого необходимо создать и распространить двоичный файл "NBM" (модуль NetBeans).


[start=1]
1. В окне "Проекты" щелкните правой кнопкой мыши проект  ``NetBeans Zone Search``  и выберите "Создать файл распространения модуля NBM".

Создается файл NBM, который можно просмотреть в окне "Файлы" (Ctrl+2).


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


[start=2]
1. Чтобы предоставить этот файл для использования другим разработчикам, можно, например, воспользоваться  link:http://plugins.netbeans.org/PluginPortal/[порталом подключаемых модулкй NetBeans]. Для установки модуля получатель должен воспользоваться диспетчером подключаемых модулей ("Сервис > Подключаемые модули").


link:http://netbeans.apache.org/community/mailing-lists.html[Мы ждем ваших отзывов]



== Что дальше?

Дополнительные сведения о создании и разработке модулей NetBeans приведены в следующих ресурсах:

*  link:https://netbeans.apache.org/platform/index.html[Домашнаяя страница платформы NetBeans]
*  link:http://bits.netbeans.org/dev/javadoc/index.html[Список интерфейсов API среды NetBeans (текущая версия разработки)]
*  link:https://netbeans.apache.org/kb/docs/platform_ru.html[Другие связанные руководства]