| // |
| // 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. Выберите в меню "Файл" команду "Новый проект" (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[Другие связанные руководства] |
| |