Atlassian アプリケーション (Bamboo) 向けに REST API プラグインを作成した際に、苦労したポイントがあったので記事にしておきます。

準備作業

プラグインの作成と動作確認は Atlassian 社から提供されている Atlassian SDK を利用します。 Maven プロジェクトの作成から実際にサーバーアプリケーションによるプラグインの動作確認までのコマンドが提供されています（スゴイ便利）。

下記のサイトから Atlassian SDK のインストーラーバイナリをダウンロードします。

Downloads - Atlassian Developers

インストーラーバイナリを実行して Atlassian SDK をインストールします。
Eclipse の Maven パスを Atlassian SDK 内の Maven を指定するように変更します。これで Eclipse でも開発できるようになります。

Plugin プロジェクトの作成

Atlassian SDK のインストールが完了したら、Plugin 開発プロジェクトを作成します。こちらは Atlassian SDK が提供するコマンドでセットアップできます。よく考えられていますね。ここでは Bamboo のPlugin開発プロジェクトを作成します。

# atlas-create-bamboo-plugin

実行すると Maven Pom.xml の作成に必要な項目がプロンプトされますので必要な項目を設定します。

Define value for groupId: : org.esheeps.bamboo.plugin
Define value for artifactId: : bamboo-rest-plugin
Define value for version: 1.0.0-SNAPSHOT: : 1.0.0-SNAPSHOT
Define value for package: org.esheeps.bamboo.plugin: : org.esheeps.bamboo.plugin

プロジェクトの作成が完了するまでに5－10分程度かかります。

ローカル Maven リポジトリの状態によっては失敗することもありますので、 {$userprofile}/.m2 ディレクトリ内をクリアしておくことを強くお勧めします。

Plugin の実装

構成ファイルの編集

Atlassin アプリケーションの Plugin は resources/attlasian-plugin.xml ファイルで設定されます。 REST API の追加はこの XML ファイルに設定します。

rest タグで REST API の URL を設定しています。

<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
        <param name="plugin-icon">images/pluginIcon.png</param>
        <param name="plugin-logo">images/pluginLogo.png</param>
    </plugin-info>\

    <!-- add our i18n resource -->
    <resource type="i18n" name="i18n" location="bamboo-plan-rest-plugin"/>

    <rest name="Bamboo Build Plan Resource" key="bamboo-plan-rest-resource" path="/apps" version="1.0">
        <description>The Bamboo Build Plan Resource Plugin</description>
    </rest>
    
</atlassian-plugin>

上記の設定では下記のような URL になります。

http://<host>:<port>/<applicationpath>/rest/apps/1.0/<restresourcepath>

REST Resource Class の実装

REST Resource は JAX-RS (Jersey) を実装します。

@Path("/buildplan")
public class BuildPlanResource {

    private PlanManager planManager;

    public BuildPlanResource() {
        this.planManager = (PlanManager) ContainerManager.getComponent("planManager");
    }

    @GET
    @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
    @Path("/plans/{key}")
    public Response getPlan(@PathParam("key") String key) {
        PlanKey planKey = PlanKeys.getPlanKey(key);
        Plan plan = planManager.getPlanByKey(planKey);
        
        BuildPlan buildPlan = new BuildPlan();
        buildPlan.setBuildKey(plan.getBuildKey());
        buildPlan.setBuildName(plan.getBuildName());
        buildPlan.setProjectName(plan.getClass().getName());
        
        return Response.ok(buildPlan).build();
    }

}

ここで大きな落とし穴があります。

Atlassian Plugin では Plugin 内でアプリケーションが提供するコンポーネントを Spring OSGi によるインジェクションで利用するようにするとありますが、 REST Resource に関しては、@Inject, @ImportComponent 属性を利用すると、プラグインが有効になりません。。。

公式なドキュメントに記載がないので動作する実装ということになるのですが、 ContainerManagerからコンポーネントのインスタンスを取得するようにします。

this.planManager = (PlanManager) ContainerManager.getComponent("planManager");

Plugin の実行と動作確認

Plugin を実行するには下記のコマンドを Plugin 開発プロジェクトのルートディレクトリで実行するだけです。

# atlas-run

atlas-run コマンドを実行すると、

Maven ビルド
Bamboo サーバーのダウンロード
Plugin のインストール
Bamboo サーバーの実行

がすべて行われます（すげー！）。

ただし、時間もかかります。初回は15-30分程度、次回以降も5分程度はかかります。ちょっとしたコーヒーブレークですね。

Quick Reload が有効ですので、別ターミナルで

atlas-mvn package

を実行して Plugin を変更することができます。

動作確認時の注意点

Spring OSGi の実装が誤っていた場合など特定の条件では、そもそも Plugin が有効にならないことがあります。この際にはログを注意深く確認してエラーの内容を確認してください。

The dawn of modern programmers

現代プログラマーの朝焼け

How to build REST plugin module for Atlassian applications.