はじめに
Atlassian アドベントカレンダーで、Confluenceのプラグイン化してみたいなあ...と書いた手前、プラグイン作成の勉強をしたいと思っています。
しかし、フルスクラッチではどうにもならず、せめてIDEがあってデバッグが出来れば少しは希望が持てるかも、というところ。
幸い、Bitbucket上に、Confluenceのサンプルプラグインがソースコードの形で提供されていましたので、ここを起点に学習したいと思います。
今回やること
やること：
- サンプルプラグインの紹介をします
- SDKの入手方法を（簡単に）紹介します
- プラグインを含めたConfluenceの起動をします
- IDEを使っての編集をしてみます
- IDEを使ってのデバッグをしてみます
サンプルのプラグイン
Bitbucket上に、Atlassian Tutorialとしてサンプルのソースコードがいくつか提供されています。
今回利用したのは、こちらです。
- confluence-banner-tutorial
- Confluecneのページの上部に、そのページの情報（履歴数やイイね、コメント数）を表示するためのプラグイン
前回の記事でやってみた内容に近そうなので、素材にしてみました。
プラグインについてのAtlassianのチュートリアル
上記のサンプルプラグインを使ったチュートリアルは、Atlassian Developersのサイトに記事があります。
こちらのQiitaの記事はすっ飛ばして、すぐに試したいという方は、ぜひ上記を先にご覧くださいませ!
まずはSDKを入手！
SDKは、Atlassian Developersのサイトから取得できます。各OS向けのインストール手順が記載されています。
（アカウント登録無しでも大丈夫でした）
※ SDKについては、こちらにも記載をしております。実行やJDKに関して、ちょっとハマった点についても触れています。（Atlassian SDKを入れてみる/開発用JIRAの起動）
ビルドしてConfluenceから確認してみよう！
READMEを参考にして、起動してみます。
プラグインのソースを展開したディレクトリの直下で、atras-run コマンドを実行すると、プラグインがビルドされ、プラグインを登録した状態でConfluenceが起動します。
pom.xmlの調整（うまくいかなかったら）
さて、この記事を書いている時点で、私が利用したAtlassian SDKのバージョンは6.1.2でした。プラグインをcloneしてそのまま起動するとERROR...。
pom.xmlのampsのバージョンを修正すると、うまく上がってくれました。
また、Confluenceのバージョンも、サンプルのコードでは5.4が対象でしたので、5.9.1に修正してみています。
<properties>
- <confluence.version>5.4</confluence.version>
- <confluence.data.version>5.4</confluence.data.version>
- <amps.version>4.2.10</amps.version>
+ <confluence.version>5.9.1</confluence.version>
+ <confluence.data.version>5.9.1</confluence.data.version>
+ <amps.version>6.1.2</amps.version>
<plugin.testrunner.version>1.1.2</plugin.testrunner.version>
</properties>
こちらで、再度 atlas-run を実行すると、Confluence5.9.1での起動となります。
起動させてみよう
うまく起動すると、このようなログが出ます。
$ atlas-run --product confluence
Executing: /usr/local/Cellar/atlassian-plugin-sdk/6.1.0/libexec/apache-maven-3.2.1/bin/mvn com.atlassian.maven.plugins:maven-amps-dispatcher-plugin:6.1.2:run -gs /usr/local/Cellar/atlassian-plugin-sdk/6.1.0/libexec/apache-maven-3.2.1/conf/settings.xml -Dproduct='confluence'
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0
[INFO] Scanning for projects...
.... [ 中略 ] ....
[INFO]
[INFO] Using the builder org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder with a thread count of 1
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building banner-stats 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-amps-dispatcher-plugin:6.1.2:run (default-cli) @ banner-stats >>>
[WARNING] The POM for com.atlassian.analytics:analytics-api:jar:5.0.2 is missing, no dependency information available
[INFO]
.... [ 中略 ] ....
[INFO] [talledLocalContainer] Tomcat 8.x started on port [1990]
[INFO] confluence started successfully in 250s at http://mb:1990/confluence
[INFO] Type Ctrl-D to shutdown gracefully
TomcatやConfluenceそのもののバイナリも、上記の中でダウンロードされてきます。
ちょっと時間はかかりますが、http://localhost:1990/confluence でConfluenceが待ち受けとなります。
admin / admin でログインできればOK!
サンプルプラグインの動作確認
さて、Confluenceは起動したものの、プラグインはちゃんと組み込まれているのでしょうか？画面から確認してみます。
アドオンの管理画面から確認
アドオンの管理画面から "banner" で検索すると、このように表示されます。
ぺージ上から確認
実際のプラグインの機能は、この通り。
- ぺージの上部に "Show Statistics" というリンクが表示される
- クリックすると イイね！数 / コメント数 / 履歴数 が表示される
ぺージ上部のタイトルの前に、"page-metadata-banner" というブロックがあり、ぺージのアクセス制限のアイコンや、JIRAとの連携のリンクが配置されています。
この並びに、ぺージの簡単な統計情報を表示するためのリンクが差し込まれた形です。
IDEでちょっと変更してみよう！
起動と動作確認が出来たので、勉強のために少し調整してみたい...。
ということで、まずは日本語化するところから試してみます。
Javaに明るい身ではないのですが、"banner-stats.properties" というファイルがあるので、これを日本語化すれば良さそうです。
お作法で行くと、"banner-stats_ja_JP.properties" というファイルを用意する形になります。
IntelliJ IDEA (Community Edition) が使えます！
さて、日本語のリソースファイルを用意すればいいのですが、実際はunicodeでファイルを作らないといけません。native2asciiをコマンドラインから使うのも面倒...。
ということで、ここはIDEの力を借りたい！
Atlassianのデベロッパー向けガイドには、IDEを使ったプラグイン開発環境 のぺージがあります。
NetBeansとIDEA (IntelliJ IDEA) での簡単な設定方法やデバッグ方法が紹介されています。
今回は IntelliJ IDEA を使ってみます。
なお、機能に制限はありますが、基本はJava - Mavenプロジェクトになりますので、Community Editionでも大丈夫。
実際に、IDEA Community Editionを使った画面を紹介します。
また、ターミナルからのatlas-runではなく、ツールウィンドウのMaven Projectパネルからも、コンパイルやConfluenceの起動などが実行できます。
atlas-run で起動させていると、プラグインのソースに変更があった場合、コンパイル&再デプロイし直して、自動でConfluenceやJIRAに変更が適用されます。
上手く日本語が当たると、以下のようになりました。
IDEでデバッグしてみよう！
では、次にIDE (IDEA) でデバッグしてみます。こちらも、Atlassianのデベロッパー向けガイドに情報があります。
今回参考にしたのは、こちらです。
簡単に記載すると、以下の通り。
- IDEAの画面から、リモードデバッグの設定を追加する
- atlas-run ではなく、atlas-debug コマンドでConfluenceを起動させる
実際にやってみた画面は、以下の通りです。
Ajaxでプラグイン側で提供しているエンドポイントを呼び出します。そのエンドポイントのソースコードにブレークポイントを設定すると、Ajaxでアクセスされた時点で止まっています。
実際に動かさないと、とても動作が理解できない私にとっては、これは大変助かります！
デバッグの注意点：
今回紹介したIDEを使ってのデバッグは、5005番でのリモードデバッグになります。
うまくデバッグ用ポートに繋がらない場合、Firewallでブロックされていないかどうかも確認してみて下さいね。
ここまでのまとめ
実際にはもう少しカスタマイズしていきたいのですが、ボリュームが増えてしまいそうなので、いったんこれくらいで。
ひとまず、IDE (IntelliJ IDEA) を使ってのデバッグができるところまで試してみました。
今回調整しているソースコードは、フォークして以下に置いてあります。（もうちょっと変えていこうと思っています）
何かの参考になれば幸いです。