目次


Eclipseでヘルプを集中化する

Eclpseの持つ、動的なヘルプとプラグイン・アーキテクチャーを利用する

Comments

開発者は昔から、システムをモジュール化して構築しておくことによって、部分的なアップグレードを容易に、他の部分に影響を与えずに行えることを知っていました。モジュラーになっていると、オリジナルのシステムを新規な方法で拡張することも容易にできます。これが、Eclipseが一連のプラグインとして構築されている大きな理由です。そうすれば、他の開発者は既存のモジュールを置き換え、高度なものにできるのです。

Eclipseでのヘルプは、Eclipseの他の環境部分と同様、プラグイン・アーキテクチャーで作られています。この記事では、この重宝なアーキテクチャーを利用して、ヘルプの内容を外部化する方法を解説します。この記事を読むための前提としては、Java™やEclipse、Webなどに関する実際的な知識が必要です。ただし、Eclipseの中でヘルプがどのように構成されているか、プラグインがどのように動作するか、などについて知っている必要はありません。この記事の目標は、集中化されたサーバー上でEclipse環境用のヘルプを、なぜ、どのようにして(イントラネットあるいはインターネットで)ホストするか、またヘルプに対して、どのようにEclipse環境内からアクセスするかを示すことです。

なぜ集中化するのか

Eclipseでのヘルプは一体物の実体ではありません。一連のプラグインが一緒につながっており、一体としての印象を与えているのです。しかし、「なぜEclipseでヘルプを集中化したいのか? Java版のEclipseをダウンロードすればJava開発を行うことができ、必要なヘルプは全てローカルにあるではないか」という質問には、この説明では不十分です。皆さんの開発チーム全体にとっても同じことです。チームのメンバーそれぞれが自分のローカル・コピーを持っており、余分なプラグインが登場するまでは、何ら問題ないのです。

プラグインの侵入

現実的なプロジェクトで言えば、あなたや、開発チームの他のメンバーが、1つか2つ、プラグインによるサービスが必要であると気が付いた時に、『その日』が来るのです。(プラグインはいくらもあり、安いものなので、1つか2つではなく、2、3ダース必要かも知れません。)実際的なチーム開発では、ビルド・プロセスから、使用するサードパーティーJARファイルに至るまで、全員の開発環境を同じにしておく必要があります。チーム全員が同じものを作っている、というのは、単にプロジェクトにおけるベスト・プラクティスなのです。実際、単にこのプラクティスを扱うためだけに、無数のサードパーティー・ツールが出現しています。JavaのMakeツールであるAntや、連続的統合が可能になるCruiseControl、その他にも多数あります。経験を積んだJava開発者であれば、開発環境やプロセスが、チーム全体で再現可能なようにしておくことが重要なことを知っています。ですから、ヘルプも同じように考えるべきなのです。

Eclipseでプラグインをインストールする場合、より高度なプラグインは、それ自身のヘルプもインストールします。そして、ヘルプはそのように構成されているため、ヘルプは既存のヘルプ・インフラの中に、そのままマージされるように見えるのです。外部からアクセスできるヘルプ・リポジトリーを持つ理由は、この点なのです。開発プロセスの他の部分に一貫性を持たせたいのと同じように、ヘルプにも一貫性を持たせたいと思いませんか。ヘルプは既存のEclipseヘルプを包含しますが、追加のプラグインによってマージされたヘルプも包含するのです。

ヘルプ・システムを最大限利用するためには、プロジェクト特有、あるいはチーム特有の注記を標準のヘルプ項目に追加することによって、独自の内容をヘルプ・システムに追加する必要があります。自分の仕事が楽になるようなプラグインをダウンロードすることもできますが、チームの全員が同じようにそれを使い、それに関する同じ注記にアクセスできるようにしておく必要があります。そうした情報を1ヶ所に置くことによって、情報の同期が外れる危険性を無くすことができます。これもまた、ベスト・プラクティスの1つであり、Dave ThomasとAndy Hunt共著によるThe Pragmatic Programmer(参考文献)にまとめられています。この本では、DRY(Don't Repeat Yourself、自分で繰り返すことをするな)という原則、つまり情報の置かれる場所が1ヶ所以上あると情報の同期が外れ、結局どれも信用できなくなる、という原則を説明しています。あなたが「自分で繰り返すことをしない」ならば、その1つのコピーが正規のコピーであることが分かります。これは、ヘルプにも当てはまるのです。

Eclipseでのヘルプの構成

Eclipseでのヘルプの外部化を始める前に、その環境でのヘルプの構成を理解する必要があります。そのためには、ちょっと脇道にそれて、Eclipseでのヘルプの構成を探らなければなりません。

ヘルプの内部構成を見るための一番簡単な方法は、helpエクステンション・ポイントを持つプラグインを作ってみることです。EclipseにはPDE(Plug-in Development Environment)が同梱されているので、新しいプラグインを作るのは簡単です。まず、新しいプラグイン・プロジェクトを作りますが、これには幾つかの方法があります。File>New Project, File>New Plug-in Project...を選択するか、あるいは、ControlとNを組み合わせたギャラリー(gallery)手法を使います。汎用の2つの方法のうち、どちらかを選ぶと、図1のようなNew Projectダイアログが表示されます。

図1. 汎用のプロジェクト・ギャラリーから、新しいプラグイン・プロジェクトを作る
汎用のプロジェクト・ギャラリーから、新しいプラグイン・プロジェクトを作る
汎用のプロジェクト・ギャラリーから、新しいプラグイン・プロジェクトを作る

このウィザードでの次のステップで、名前やディレクトリー構造など、プロジェクトの詳細を規定します。このダイアログを図2に示します。

図2. プロジェクトの物理属性を規定する
プロジェクトの物理属性を規定する
プロジェクトの物理属性を規定する

この場合は、単にヘルプ・プラグインのエクステンション・ポイントを作っているだけです。しかしPDEには、ヘルプ・エクステンション用のものも含めて、事前構築された様々なエクステンション・ポイントが用意されています。エクステンション・ポイントのリストを見るには、図2のProject Settingsの「Create a Java Project」を選びます。そうしないと、その次のウィザード・ダイアログで、サンプルのエクステンション・ポイントが現れません。この場合は、後でJavaコードを作ることになるので、このオプションは選択されています。ヘルプ・エクステンションだけを作り、事前定義されたエクステンション・ポイントを使いたい場合には、このオプションをチェックしたままにしておきます。

次のウィザード・ページでは、プラグインに関するメタ情報を規定します。これを図3に示します。

図3. プラグインに関するメタ情報ページ
プラグインに関するメタ情報ページ
プラグインに関するメタ情報ページ

PDEでは、プラグインの構築を容易にするために、事前定義されたタイプのプラグインを含めて、様々なテンプレートを用意しています。こうしたテンプレートを利用して、ヘルプ・プラグインのためのインフラを作ります。図4は、テンプレートを選択するためのウィザード・ページを示しています。

図4. プラグイン・テンプレート
プラグイン・テンプレート
プラグイン・テンプレート

カスタム・プラグイン・ウィザードでは、様々なエクステンション・ポイントを提供しています。その中の1つがヘルプ・エクステンションですが、これを図5に示します。

図5. ヘルプ・エクステンションのプラグイン・テンプレート
ヘルプ・エクステンションのプラグイン・テンプレート
ヘルプ・エクステンションのプラグイン・テンプレート

最後に、このヘルプ・プラグインで、どのようなタイプの内容を提供するかを選択します。これは最後のウィザード・ページで行いますが、これを図6に示します。

図6. 目次のカテゴリーを選択する
目次のカテゴリーを選択する
目次のカテゴリーを選択する

PDEウィザードのツアーが終わると、XMLやJavaソース、ビルド・インフラストラクチャ(build infrastructure)などを含めた、ファイルの集合が得られます。

TOC(Table Of Contents)の内部

PDEウィザードの最後のページ(図6)では、プラグインで含めようとしているヘルプ・ファイルの目次(Table Of Contents)である、TOC.XMLファイルが作られます。このTOCフォーマットは、Eclipseの内部ヘルプと、プラグインで使われます。これは全体を通して一貫しています。デフォルトで生成されるTOCファイルは、リスト1のようなものです。

リスト1. デフォルトで生成されるTOCファイル
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Repository Table of Contents" topic="html/toc.html">
   <topic label="Getting Started">
      <anchor id="gettingstarted"/>
   </topic>
   <topic label="Concepts">
      <anchor id="concepts"/>
   </topic>
   <topic label="Tasks">
      <anchor id="tasks"/>
   </topic>
</toc>

図6で作られたタイトルが、<toc>タグの先頭に現れており、これがhtml/toc.htmlのトピックを指していることに注意してください。このTOCエントリーは、このヘルプ・セットに対するヘルプ・ディレクトリー構造の最上位レベルにあります。つまり、物理的なヘルプHTMLファイルは、ルート・ディレクトリーから下の、ここで規定されるディレクトリー構造の中に現れるのです。一般的に言って、こうしたHTMLファイルはスペースを考慮して、zipファイル(伝統的にdoc.zipと呼ばれます)として現れます。Eclipseプラグインのディレクトリーを検索すると、幾つかのdoc.zipファイルがあるのが分かるでしょう。こうしたdoc.zipファイルそれぞれが、ヘルプが呼び出される度にEclipseのメイン・ヘルプにマージされるヘルプを含んでいるのです。

TOCファイルの中にある他のエントリーは、プライマリーTOCを生成した時に同時に生成される他のTOCを指します。これらには「gettingstarted」や「concepts」、「tasks」などがあります。こうしたセカンダリーTOCエントリーは、それぞれに対応して、プロジェクトの中に目次XMLファイルを持っています。また、PDEはプロジェクトの中に、コンテンツHTMLファイルに対する適当なディレクトリー構造を作っています。これは、図7に示す、パッケージ・エクスプローラーから借用した断片を見ると分かると思います。

図7. PDEがXMLコンフィギュレーション・ファイルとディレクトリー構造を作る
PDEがXMLコンフィギュレーション・ファイルとディレクトリー構造を作る
PDEがXMLコンフィギュレーション・ファイルとディレクトリー構造を作る

こうした構造があるために、ヘルプ・ファイルを好きな数だけ、適当な構造を持たせて作ることができます。そしてそれらをzipファイルにまとめ、Eclipseのヘルプ・システム・ブラウザーによって、継ぎ目のない一体として合体させることができるのです。

外部リポジトリーを作る

Eclipseでのヘルプ・ファイルの構成が分かったので、これを独立のサーバーに外部化する方法を調べてみましょう。Eclipseでは、インストールの中にInfocenterと呼ばれるツールを提供することによって、これを実現しています。皆さんが想像される通り、Eclipseでのヘルプ・システムは、実際にはEclipseに埋め込まれたWebサーバー/サーブレット・エンジンによって駆動されます。実際、簡略版のApache Tomcatが、ヘルプ用のアプリケーション・サーバーとして使われているのです。Eclipseに同梱されているプラグインの1つであるorg.eclipse.help.appserver_3.0.0は、Webサーバーをカプセル化しています。Infocenterはアプリケーション・サーバーを外部化しているため、Eclipse環境の外でアプリケーション・サーバーを操作できるのです。

Infocenter

外部サーバーにInfocenterを設定するには、Eclipse Runtime Binaryをインストールします(Eclipseからzipファイルとしてダウンロードすることができます)。これをサーバーのディレクトリー構造の中に解凍します(これは、サーバーに対して行う、Eclipseのインストールと全く同じであることに注意してください)。Infocenterは、infopops(コンテキスト依存の、ツール・ヒントのポップアップ)とActive Help(新しいファイルを作るのと同じように、ヘルプ・ビューからコマンドを実行します)を除いて、内部ヘルプの機能を全てサポートしています。こうした高度なヘルプ機能は、外部サーバーから実装することは不可能です。Infocenterは、Javaクラスのセットとして、Runtime Binaryと一緒に含まれており、コマンドラインから呼び出されます。

サーバーでInfocenterを起動するためには、次のようなコマンドを発行します。ここではEclipseのインストール・ディレクトリーを[ehome]としています(リスト2では、読みやすいように複数行に分けていますが、本来は1行です)。

リスト2. サーバーでInfocenterを起動する
java 
-classpath [ehome]\plugins\org.eclipse.help.base_3.0.1\helpbase.jar
org.eclipse.help.standalone.Infocenter 
-eclipsehome [ehome] 
-port 8081
-command start

このコマンドは、クラスパスがInfocenter JARファイルを指すように設定してEclipseがどこにインストールされているかを伝え、ポート番号を設定し、そしてstartコマンドを発行します。サーバーを停止するには、同じコマンドで、startの代わりにshutdownを使います。いったんInfocenterを起動すると、ブラウザーが使えるようになり、http://localhost:8081/help/index.jspのようなURLを発行することができます。

ブラウザーの中に、標準のEclpseヘルプが見えるようになります。これを図8に示します。

図8. 外部で実行しているEclpseのヘルプ
外部で実行しているEclpseのヘルプ
外部で実行しているEclpseのヘルプ

スタンドアローンのInfocenter

Infocenterは、スタンドアローンのサーバーなので、別なWebサーバーを必要とはしません。ただし現実的な環境では、アクセス制御や可視性その他など、重要な問題を制御するために、通常のWebサーバーを使った方が良いかも知れません。Webサーバーは、特定なURLパターンに基づいてInfocenterにコマンドを転送するように、簡単に設定することができます。

例えば、Apacheのconf/httpd.confファイルに次のような変更を加えてプロキシー・モジュールを設定し、http://bigsprawlingcompany.com/eclipsehelprepoという形のリクエストを、http://internalhelpserver:8081/helpのようなInfocenter URLにリダイレクトされるようにします。

LoadModule proxy_module modules/ApacheModuleProxy.dll
ProxyPass /eclipsehelprepo http://internalhelpserver:8081/help 
ProxyPassReverse /eclipsehelprepo http://internalhelpserver:8081/help

ヘルプ・アクセスをプラグインする

これでヘルプを外部化できたので、そこにEclipse内部からアクセスする方法が必要になります。これには幾つかの方法があります。この記事では、新しい、リモートのリポジトリーに導くための、最上位レベルの新規メニュー・アイテムを作ります。既存のメニュー・アイテムを書き直すことによって、既存のヘルプ振る舞いを置き換えることもできますが、あまりお勧めできません。一般的に、既に存在しているものを壊すのは良い考えではありませんし、この場合は特にそうです。何らかの理由でサーバーがダウンした場合にもローカル・ヘルプを使える、という機能を開発者から奪うべきではありません。プラグインの開発では、医師の義務倫理規定(Hippocratic Oath)と同じように、『何よりも、害を加えるな』という原則を守るべきなのです。

新規のメニュー・アイテムを作るための一番簡単な方法は、PDEウィザードにインフラを作らせる方法です。このヘルプ・リポジトリー・メニュー・アイテムを作るためには、前と同じ手順を使いますが、ウィザード・ページの1つを変更します。図5に示したテンプレート選択のページに、新しいSample Actionを追加します。これを図9に示します。

図9. ヘルプ・リポジトリーにサンプル・アクションを追加する
ヘルプ・リポジトリーにサンプル・アクションを追加する
ヘルプ・リポジトリーにサンプル・アクションを追加する

これで、新規メニュー・アイテム用のインフラが作られます。新しいアクションを作っているので、アクションの名前を規定するための新しいウィザード・ページも作られます。このページを図10に示します。

図10. Sample Actionクラスのウィザード・ページ
Sample Actionクラスのウィザード・ページ
Sample Actionクラスのウィザード・ページ

このページでActionクラスに名前を付けます。それが結果的にActionクラスを作ることになります。このActionクラスには、Eclipseで新しいアクション(この場合はメニュー・アイテム)を追加するための、定型的なコードが含まれています。追加が必要なコードは、ヘルプ・ビューアーを呼び出すためのコードのみです。このビューアーは、標準のEclipseヘルプ・ビューアー、あるいはブラウザーです。この場合は、ユーザーのデフォルト・ブラウザーを呼び出します。完全機能のブラウザーを使うことによって、ヘルプ・ビューアーを使うのと全く同じ利点を利用できますが、それだけではなく、開発に関連してWebで見つけたブックマークと並んで、ヘルプ・リポジトリー・コードへのブックマークも作ることができます。run()メソッドの中のコードは、次の1行です。

public void run(IAction action) {
     Program.launch("http://localhost:8081/help");

当然ですが、URLは、このヘルプ・リポジトリーに置きます。ちょっと手間をかければ、アドレスを規定できるような設定をPreferencesダイアログに追加し、プラグインの中にハードコード化しなくて済むようにもできます。ただし、この話題に関しては、Preferencesダイアログを修正するようなプラグインの構築に関しての記事で取り上げる方が適当でしょう。

一緒にまとめる

メニューのプラグインができあがると、Eclipseのメイン・メニュー・バーのヘルプを、外部化したInfocenterに追加することができます。図11は、この新しいメニューを示しています。

図11. Eclipseでの新しいHelp Repositoryメニュー・アイテム
Eclipseでの新しいHelp Repositoryメニュー・アイテム
Eclipseでの新しいHelp Repositoryメニュー・アイテム

このメニュー・アイテムをクリックすると、そのコンピューターにどのような外部ブラウザーが設定されているかによらず、Infocenterヘルプが起動します。最終的な結果を図12に示します。

図12. 外部化されたヘルプ・ブラウザーがEclipseのメニュー・プラグインから起動されている
外部化されたヘルプ・ブラウザーがEclipseのメニュー・プラグインから起動されている
外部化されたヘルプ・ブラウザーがEclipseのメニュー・プラグインから起動されている

ご覧の通りです。これで、外部ヘルプ・リポジトリーができました。このリポジトリーで、アプリケーション開発チーム全体のための、ヘルプ・システム統合が始められるのです。一度このリソースが手元にある状態に慣れてしまうと、今までこれを使わずにいたことが不思議に思えるでしょう。

まとめ

この記事の中で議論してきた小片は、全てつなぎ合わされました。その合計は、部分を集めたものよりも大きいのです。これで、適切なプラグイン・ヘルプを全て備え、しかも皆さん独自の内容を持った、高度にカスタム化されたヘルプ・セットを作ることができます。他の参照資料と並んで、会社のコーディング標準をヘルプの中に置けたら素晴らしいと思いませんか。

開発環境の外でヘルプを構築すると、そのヘルプは在宅の開発者や、遠隔のクライアント・サイトにいる開発者にも利用できるようになります。ヘルプ環境が、重要な参照リソースとなるのです。実際、ヘルプを外部化することによって、ベンダーから滝のように降ってくる情報を静的にグループ化する以上のものとして、ヘルプを扱えるようになるのです。


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Open source, Java technology
ArticleID=236848
ArticleTitle=Eclipseでヘルプを集中化する
publish-date=06212005