netbeans.apache.org/src/old_content/content/tutorials/71/nbm-quick-search_ja.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[完了したサンプルをダウンロード]してソースを調べることもできます (任意)。


== 高速検索の統合入門

NetBeans IDE 6.5 で導入された高速検索機能は、IDE の右上隅のテキストフィールドで構成されます。検索文字列をフィールドに入力すると、ドロップダウンリストが表示され、一致する項目が示されます。デフォルトでは、項目は IDE に登録されているアクションの名前と IDE の JavaHelp トピックから検索されます。アクション項目を選択するとアクションが呼び出され、ヘルプ項目を選択すると 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 パーサーの統合

次の節では、NetBeans Zone を解析できるようにするために、HTML DOM パーサーが必要になります。任意の適切なパーサーを使用できます。このチュートリアルでは、 link:http://sourceforge.net/project/showfiles.php?group_id=13153[JTidy] を使用します。

モジュールで使用可能な外部 JAR ファイルを作成する方法は、2 つあります。1 つ目の方法は、JAR を「ライブラリラッパーモジュール」と呼ばれる個別のモジュールに置き、機能性モジュールとライブラリラッパーモジュールをモジュールスイートに置いてから、機能性モジュールをライブラリラッパーモジュールに_依存_させます。2 つの別個のモジュールを持つことの利点は、外部 JAR の新規バージョンがリリースされたときに再配布が必要なのが、機能性コードも含む大きなモジュールではなく、外部 JAR のみを含む小さなモジュールだけであることです。2 つ目の方法は、次で行う機能性モジュールに JAR を追加する方法です。この方法の利点は、配布するモジュールが 1 つだけなので、短期だけの場合に便利であることです。欠点は、外部ライブラリを機能性コードと混在させるため、厳密にはモジュールアプローチではなくなることです。


[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.  ``nbproject``  フォルダにある  ``project.xml``  ファイルの最後のほう、すなわちファイルの最後の直前に、次のボールドタグを追加します。

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

    /**
     * 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. 次のインポート文が宣言されていることを確認します。

[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 プラットフォームでの高速検索機能の使用

前の節では、既存アプリケーションのモジュールを作成することが想定されていました。このあとの 2 つのトピックは、モジュールを作成する代わりに、NetBeans プラットフォーム上に独自のアプリケーションを作成する場合に適用されます。


=== NetBeans プラットフォームでの高速検索機能の有効化

NetBeans IDE には高速検索機能のサポートがありますが、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 プラットフォームでのデフォルトの Web 検索プロバイダの有効化

NetBeans ソースでは、デフォルトの Web 検索プロバイダの実装が可能です。このプロバイダは、検索文字列が一致するテキストを Google で検索します。IDE では、 ``netbeans.org``  と、IDE に関連するオンラインドキュメント用の関連サイトを検索するために使用されています。

NOTE:  残念ながら、Web 検索プロバイダを何度も使用していたので、Google がこの自動検索が利用規約に反しているとし、機能を継続することを拒否しました。そのため、IDE で Web 検索プロバイダは無効になっています。

前述の制限に同意する場合は、この Web 検索プロバイダをブランディングし、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 プラットフォームアプリケーションを実行すると、デフォルトの Web 高速検索プロバイダが利用可能で、機能していることがわかるはずです。


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[NetBeans API の一覧 (現行の開発バージョン)]
*  link:https://netbeans.apache.org/kb/docs/platform_ja.html[その他の関連チュートリアル]