リスナー
リスナーは Jira で固有の機能であり、Jira の拡張を実現する非常に強力な方法です。
Jira は、アプリケーションの内部でアクションが発生したときにイベントをトリガーする、完全なイベント サブシステムを備えています。たとえば、課題が作成されると ISSUE_CREATED イベントがトリガーされます。
リスナーは、リスナー インタフェースのいずれかを実装するクラスです。Jira でイベントが発生すると、リスナーが呼び出されます。これらのイベントを使用して、任意のアクションを実行できます。たとえば、Jira によって送信されたメールは MailListener で駆動されています。
リスナーは、Jira 内で発生するイベントから外部システムに影響を与えたいときに最も便利です。
次のすべての手順を行うには、Jira システム管理者グローバル権限を持つユーザーとしてログインする必要があります。
リスナー インタフェース
Jira には次のような (基本の JiraListener インターフェイスを拡張する) リスナーがあります。
com.atlassian.jira.event.JiraListener | すべての Jira リスナー インタフェースが拡張する基本のインタフェース。一意性、説明、パラメータなどの主要なリスナー プロパティを網羅します。 |
com.atlassian.jira.event.issue.IssueEventListener | 課題でアクションが発生すると使用される、Jira のメイン リスナー。 |
com.atlassian.jira.event.user.UserEventListener | Jira 内でユーザーに対するアクションが発生すると呼び出されるリスナー。 |
リスナー例
次の例は、環境に合わせて自由に利用および変更できます。すべての例のソースが利用可能で、独自のリスナーを簡単に作成できることをご確認いただけます。いずれの例のリスナーも Jira 2.1 に含まれており、いずれも UserEventListener および IssueEventListener を実装しています。
- DebugListener － これは、イベントやその内容を受信したら System.out に出力する、非常にシンプルなリスナーです。このリスナーをテストするには、
com.atlassian.jira.event.listeners.DebugListenerクラスのリスナーを追加します。 - MailListener － このリスナーは、Jira からの現在のメール通知の送信状況を示します。複雑なリスナーの良い例です。このリスナーは基本的にイベントをリッスンし、Velocity テンプレートを使用してイベントをメール通知に変換してメール本文を生成します。
このリスナーは、通常、Jira で常にオンになっています － 詳細については、「メール通知」を参照してください。複雑な通知や特定の通知を作成する場合は、内部の MailListener を無効にし、自分が作成したリスナーを追加します。
リスナーで実現できるその他の便利なタスクの例:
- SMS または IM 通知を送信する — リスナーは SMS または インスタント メッセンジャー（例、ICQ または AIM）、メッセージを送信する Java ライブラリを介して様々なイベントの通知を容易に送ることができます。
- グループ通知 — リスナーは課題の内容によって、信頼できるグループに課題の変更を通知することができます。例えば、環境に "windows" が含まれている課題は "windows-開発者" グループに通知することができます。
リスナーの登録
独自に作成したリスナー クラスの場合は、リスナー クラスが Jira によって認識できるクラスパスにあることを確認します。通常、最適な場所は Jira インストール ディレクトリの <jira-application-dir>/WEB-INF/classes または <jira-application-dir>/WEB-INF/lib の各サブディレクトリです (JAR ファイルとして設定)。
リスナーを登録するには、次の手順に従います。
- In the upper-right corner of the screen, select Administration
, then System. - [詳細] > [リスナー] を選択してリスナー ページを開きます。
- ページの下部にある 「リスナーの追加」 フォームで、次のフィールドの入力を完了します。
- 名前 — リスナーを適切に説明する名前
"クラス" — リスナーの完全修飾クラス名。
Jira の組み込みリスナー クラスのいずれかを使用するには、最初に [組み込みリスナー] リンクをクリックして、リスナー クラスのリストを展開し、リスト内の特定のクラスの名前をクリックします。組み込みリスナーの完全修飾クラス名が "クラス" フィールドに追加されます。
- 追加ボタンをクリックすると、リスナーが上部のリスナー一覧に追加されます。
リスナー プロパティの編集
リスナーがパラメータまたはプロパティを許可する場合、Jira の管理エリアの [リスナー] ページにある、対象のリスナーの [編集] リンクをクリックすることで変更できます。
独自のリスナーを定義する場合、String オブジェクトの配列として渡されるパラメータ名の定義をオーバーロードするメソッド getAcceptedParams があります。init メソッドは、設定値を含む Map を受け取ります (JavaDoc は現在は使用されていません)。com.atlassian.jira.event.listeners.DebugParamListener クラスは 2 つのパラメータでのこれの実行例です。
リスナーの削除
リスナーを削除するには、Jira の管理エリアの [リスナー] ページにある、対象のリスナーの [削除] リンクをクリックします。
カスタム イベント
Jira ではカスタム イベントを追加できますが、この場合はイベントを適切に処理できるようにリスナーを更新する必要があります。これはリスナーに customEvent(IssueEvent event) メソッドを実装することで可能です。たとえば、MailListener 実装は、通知プロセス用のカスタム イベントを渡します。DebugListener はこのカスタム イベントのトリガーを記録します。
参考資料
- チュートリアル － アトラシアンのイベント ライブラリを使用して Jira イベント リスナーを作成する － ここでは、上記で説明した Jira リスナー イベントではなく、アトラシアンのイベント ライブラリ (「Jira 固有のアトラシアン イベント」を参照）を使用してリスナーを作成する方法について説明しています。