maven2のsiteゴールは，標準Webページや各種レポートの出力により，プロジェクトの情報共有を行うためのWebページを簡単に生成することができる。もちろんこれだけでも十分魅力的なのだが，特にオープンソースなライブラリなどを開発するプロジェクトであれば，そのライブラリの使用方法やチュートリアル，ダウンロードページなどを追加して，siteゴールのみでコンテンツ全てを賄いたくなってくるだろう。今回は，siteゴールで自作のWebページを追加する方法を紹介しようと思う。
まずは，siteゴールを提供してくれるmaven-site-pluginプラグインについて，日本語を使用できるように設定しておく必要がある。もちろん自作のWebページは日本語で記述したいだろうから，ほとんどの場合この設定は必須となるだろう。
siteゴールで適用されるロケールをja，入出力されるコンテンツの文字コードをUTF-8と設定している。実はこれだけで，標準Webページに関しては日本語化される。
siteゴールで出力されるコンテンツは，実はsite.xmlファイルを作成することで制御することができる。site.xmlファイルを工夫することにより，出力されるコンテンツに対して，様々なカスタマイズを施すことが可能だ。もちろん，今回の「自作ページを追加する」という目標を達成するためにも，site.xmlファイルが必要となる。site.xmlファイルは，src/siteディレクトリに作成する。
site.xmlファイルは，XML形式のテキストファイルである。以下に例を示してみよう。
body要素の中にmenu要素が記述されている。menu要素を使用することにより，siteゴールで出力される左側のメニューについて，自作のメニューを追加することができるのだ。上記の例では，「Hello!」というメニューを追加し，item要素を更に定義することによって，「User Guide」というメニュー項目を追加している。「User Guide」メニュー項目はリンクとなり，その飛び先はhref属性で指定されているuserguide.htmlファイルとなる。
標準Webページおよび各種レポートを出力する場所は「${reports}」で示す。上記では，自作メニューの下に出力するよう指示がされた状態である。
この時点でsiteゴールを実行すると，出力結果は以下のようになる。自作のメニューが追加されていることがわかるだろう。
さて，href属性で指定したuserguide.htmlファイルだが，これを作成するための方法として，4種類存在する。
- site/resourcesディレクトリ内にuserguide.htmlファイルを作成する。
- site/aptディレクトリ内にuserguide.aptファイルを作成する。
- site/xdocディレクトリ内にuserguide.xmlファイルを作成する。
- site/fmlディレクトリ内にuserguide.fmlファイルを作成する。
resourcesディレクトリに作成する方法は，ページ全体をuserguide.htmlファイルで全て記述する必要があるので，siteゴールが出力するヘッダや左のメニューを使わないページにしたいときに採用する。つまり，標準Webページのようなページにしたい場合は，この方法を選択すべきではない。
xdocディレクトリに作成する方法は，自作したいページをXDoc形式で記述したい場合に採用する。これは，文書構造を決められたタグセットを使ってXML形式で記述していく形態となる。XDoc形式で書かれたファイルは，こんな感じになる。XML大好きな人には，これがお勧め。
fmlディレクトリに作成する方法は，自作したいページがFAQのページな場合に採用する。これは，FAQに特化した文書構造を，XDoc形式と同じように，決められたタグセットを使ってXML形式で記述する。fml形式で書かれたファイルは，こんな感じになる。
最後に紹介するaptディレクトリに作成する方法が，僕の個人的なお勧めである。この方法では，自作したいページをAPT形式(Almost Plain Text)で記述する。APT形式は，Wikiでページを記述するときの文法に似ている。どのような形式なのかは，Mavenサイトの「Guide to the APT Format」に例と共に詳しく載っているので，参考にして欲しい。今回の例でいけば，以下のような感じだ。
上記の内容を，userguide.aptというファイル名でsite/aptディレクトリに保存する。この際，文字コードをUTF-8にしておく必要があるので，お忘れなく。その後，siteゴールを実行して，出力されたWebページの左のメニューから「User Guide」リンクをクリックすれば，APT形式で書かれた内容がめでたくHTML形式に変換されて，しかも標準Webページと同じレイアウトで出力されているのが確認できるだろう。
まとめると，
- site.xmlにメニュー項目を追加する。
- APT形式でページを記述してsite/aptディレクトリに保存する。
- siteゴールを実行する
の繰り返しで，maven2によるプロジェクトのWebページを手軽に追加していくことができる。思ったよりも手軽に自分なりのプロジェクトサイトを作ることが可能である。
APT形式で書かれたファイルの中にマルチバイト文字が含まれていても，maven-site-pluginプラグインに対する文字コード指定が行われていて，尚且つAPT形式のファイルがUTF-8であれば，正しく日本語ページを出力することができる。しかし残念なことに，site.xmlファイルにマルチバイト文字を記述しても，どうしても文字化けしてしまう。つまり，メニューに日本語が使えないことを意味している。これは，maven-site-pluginが国際化について非常に中途半端な対応になってしまっていることが原因で，最近リリースされたmaven2.0.5でも修正されていない。
ま，メニューに日本語が使えなくても，ほとんど支障はないだろう。maven2のsiteゴールは，それだけでもmaven2の採用理由になるくらい，非常に重要なゴールである。標準Webページ，各種レポート，そして自作ページの追加といった機構をうまく利用して，プロジェクトの成功を確かなものにして欲しい。
- Posted:
- 02.19.2007
- Category:
- Maven
maven2によって管理されているプロジェクトは，siteゴールを使用することによって，さまざまな情報をWebページとして自動的に出力することができる。これについては，「maven2のsiteゴールによる標準Webページの出力」エントリで紹介した。今回は，プロジェクトの成果物に関する各種レポートをWebページとして出力するための方法を紹介してみよう。
Javaソフトウェア開発では，ソースコードを元にしてさまざまな2次的成果物を作成することになる。コンパイラによるclassファイルの生成や，コメントの記述を利用したJavadocの出力などが代表例としてあげられるだろう。それに加えて，単体テストの結果やカバレッジ率の測定結果なども，やはり2次的成果物ということができるだろう。
これらの出力は，maven2を利用していれば，いとも簡単に行うことができる。
ポイントは，pom.xmlファイルのreportingタグだ。各種レポートを出力するための機能は，maven2のプラグインとして提供されている。reportingタグの中に，出力したいレポートのためのプラグインの記述を行うことで，siteゴールの実行時にプラグインが機能するようになり，レポートが出力されるようになる。もちろん，出力結果の左にあるメニューに，レポートページを表示するためのリンクが追加される。
まずは，単体テストの結果をレポートとして出力するための記述を紹介しよう。
たったこれだけ追記すれば良い。「mvn site」を実行後，target/siteディレクトリにあるindex.htmlファイルをWebブラウザで表示すると，左のメニューに「Project Reports」-「Maven Surefire Report」という項目が追加されているのがわかるだろう。これをクリックすれば，プロジェクトに存在するJUnitテストケースの実行結果が表示されるはずだ。
次は，Javadocを出力してみよう。Javadocを出力するためには，maven-javadoc-pluginプラグインを利用する。
先ほどよりも記述が多く感じるのは，Javadocを生成する際の文字コード関連の設定をconfigurationタグを使って記述しているからである。上記の例では，ソースコードのレベルが1.5，Javaソースファイルの文字コードはShift_JIS，Javadocのhtmlファイルを出力する際の文字コードはTF-8でcharset指定も一緒，JavaSE提供のコアAPIのリンクとしてjava.sun.comのURLを指定，といった設定を施している。
siteゴールを使用した場合，一度出力したファイルは，直接の変更がなければ上書きをしない，という動きになる。そのため，左のメニューにリンクが追加されないことがある。よって，「mvn clean site」というように，一旦前回の出力結果を削除してからsiteゴールを実行すると，確実だろう。
では，カバレッジ測定結果のレポートも出力するようにしてみよう。これには，cobertura-maven-pluginプラグインを使用する。
お決まりのように「mvn clean site」を実行すれば，左のメニューに「Project Reports」-「Cobertura Test Coverage」リンクが追加されているのがわかるだろう。そのリンクをクリックすると，カバレッジ測定の結果が掲載されたページを表示することができる。
今回紹介した３つのレポート以外にも，数多くのプラグインが存在する。他にどのようなレポートを出力することができるかは，「Available Plugins」のページの「reporting」に一覧があるので，参考にするといいだろう。お好みのプラグインを見つけてpom.xmlファイルのreportingタグに記述し，有益な情報をプロジェクトで共有して欲しい。
最後に，ちょっとしたテクニックというわけではないのだが，知っておくとより良いことを紹介しておこう。siteゴールでは，pom.xmlファイルに記述された定型的な情報が標準Webページとして出力される。しかし，プロジェクトによっては，メーリングリストを持ってるわけではなかったり，developersタグで開発者の情報を記述していなかったりする場合もあるだろう。そのような場合は，何も情報がない無駄ページは，出力されるWebページに含めないようにしておきたいところだ。
これを実現するには，maven-project-info-reports-pluginプラグインを使用すれば良い。
reportタグを使用して，出力したいページを指定することができるようになる。上記の例では，標準Webページの中から，依存ライブラリとプロジェクトサマリーの２つのみを出力するように指定している。この状態で「mvn clean site」とすることで，下記のようなメニューにすることが可能だ。
レポートが出力されるようになっただけでも，siteゴールの必要性は非常に高まる。継続的統合環境を作れば，さらに便利さが増してくるだろう。しかし，例えば一般に公開するライブラリのためのWebページとなると，Usageなど独自のWebページも追加したくなってくるはずだ。
次回は，Webページの自作の方法を紹介し，さらにmaven2を魅力的なツールとして感じられるようにしたい。
- Posted:
- 02.16.2007
- Category:
- Maven
ソフトウェアを構成するファイル群やそれらに対するコンパイルやパッケージング，依存関係などを管理してくれるmaven2。プロジェクトに存在するさまざまな情報や処理結果をチームで共有することが開発に必要なのは明らかであり，多くの場合はそのプロジェクト用にWebページを構築して情報をチームメンバーに公開することが行われる。しかし，Webページの更新作業について，手作業ではなかなか難しく，ついつい更新が滞ってしまうことが多くのプロジェクトで見られる。アジャイルやイテレーティブな開発プロセスを採用している場合は，更新が滞ってしまうと致命的なミスを高い確率で招いてしまうだろう。
maven2では，プロジェクトの情報や，単体テスト結果やカバレッジ結果，JavadocのWebページへの公開などについて，自動でWebページを作成するゴールが標準で備わっている。それがsiteゴールだ。
maven2で管理されているプロジェクトであれば，何も考えずにsiteゴールを実行するだけで，標準的なWebページを出力してくれる。
mvn site
作成されたWebページは，target/siteディレクトリに出力されている。この中のindex.htmlファイルをWebブラウザで表示すれば，以下のようなWebページが表示されるはずである。
使用したpom.xmlファイルの記載がほとんどなされていないため（descriptionタグすら書いていない），非常に殺風景なページである。本来pom.xmlの中に，チームの構成やメーリングリスト，ライセンス関連やソースコードのリポジトリなどの情報が記述されていれば，それらが出力されるWebページに反映される。もちろん，対象のプロジェクトが必要とする依存ライブラリの情報に関しても，しっかりとWebページに反映される。標準で出力してくれるWebページを以下に示しておこう。
- About – プロジェクトの概要。descriptionタグの内容が反映される。
- Continus Integration – 継続的統合に関する情報。
- Dependencies – 依存ライブラリの情報。dependenciesタグの内容が反映される。
- Issue Tracking – 問題解決のための問題管理システムに関する情報。issueManagementタグの内容が反映される。
- Mailing Lists – メーリングリストの情報。mailingListsタグの内容が反映される。
- Project License – ライセンスの情報。licensesタグの内容が反映される。
- Project Summary – プロジェクトの基本的なサマリー情報。プロジェクト名やホームページ，組織の情報やビルド情報など。それぞれname，url，organization，buildタグなどの内容が反映される。
- Project Team – プロジェクトのチームの情報。developersタグなどの情報が反映される。
- Source Repository – ソースコード管理に関する情報。scmタグの内容が反映される。
これだけでも非常に有用な情報である。maven2を使用し，適切にpom.xmlが記述されていれば，プロジェクトの概要を第3者に説明するためのWebページは，いとも簡単に作成することができてしまう。
しかし，これだけではプロジェクトメンバーに十分な情報が共有されるとは思えないだろう。不十分な点として，以下があげられる。
- 単体テスト結果やカバレッジ測定結果，JavadocやCheckstyleなどの実行結果といった各種レポートが含まれていない。
- pom.xmlファイルに記述可能な定型的なものではなく，プロジェクト固有の情報を掲載する自由なページを追加したい。
上記2つの点についても，maven2のsiteゴールはきちんと対応してくれる。しかも，かなり手軽にそれを実現することができる。
次のエントリからは，maven2のsiteゴールを有効に利用するための上記2つの実現方法について紹介していこうと思っている。
- Posted:
- 02.15.2007
- Category:
- Maven
