新しいEventSystemの使い方

Minecraft1.1向けのBukkit API以降、新しいイベントの仕組みが提供されています。
この新しい仕組みは、シンプルでかつ、汎用性・高速性・可読性等に優れています。

解説動画[編集]

当項目の、翻訳元記事で紹介されている動画を参照して下さい。
http://wiki.bukkit.org/Introduction_to_the_New_Event_System#Video_Tutorial

基礎[編集]

PlayerLoginEventについて説明します。
このイベントは最低限動作するための処理のみを記述するよう心がけ、
極力シンプルに保ちつつ編集していきましょう。

イベントリスナ[編集]

まず、イベントを待ち受ける処理（Event Listenerと呼ばれます）が必要です：

@EventHandler
public void onPlayerLogin(PlayerLoginEvent event) {
    // ここに処理を書きます...
}

次に、発生するイベント（Event Handlerと呼ばれます）が必要になります。

イベントハンドラ[編集]

イベントハンドラはイベントリスナに対する注釈であり、次のような書き方をします：

@EventHandler // EventPriority.NORMAL がデフォルト値

この記述は、メソッドがイベント優先度がNORMALのイベントハンドラである事を指定します。

イベントハンドラには優先度を指定でき、次のような書き方をします：

@EventHandler(priority = EventPriority.HIGHEST) // 高優先度のイベントハンドラとする
@EventHandler(priority = EventPriority.LOW) // 低優先度のイベントハンドラとする

以上をまとめると、次のようになります：

@EventHandler
public void onPlayerLogin(PlayerLoginEvent event) {
    // ここに処理を書きます...
}

リスナの追加[編集]

"PlayerListener"として拡張する場合は、"Listener"インタフェースを実装する必要があります。
この時点では、次のような形のメソッドになりそうです：

public class myPlayerListener implements Listener {
    @EventHandler
    public void onPlayerLogin(PlayerLoginEvent event) {
        // ここに処理を書きます...
    }
}

リスナ内部のメソッドは任意の名前を付けて呼び出する事が可能であり、
"onPlayerLogin()"のような、メソッドの名称が重要ではない事に言及しておきましょう。
「Bukkitは、どのEventを識別可能でどうやってListenするのか？」と不思議に思うかもしれませんが・・・
Bukkitは、あなたが指定したイベントからそれら（識別可能なEventと、そのListenの方法）を読み込みます。
上記の例で言えば、PlayerLoginEventから読み込みます。

Note: 特定のイベントハンドラを1つも登録していなければ、Bukkitはそのクラスをイベントリスナとして登録することができません。

イベントハンドラの設定[編集]

イベントハンドラには、様々な内容を指定可能です。
現時点では次のような指定が行えます：

型項目名デフォルト値概要指定できる値

EventPriority priority EventPriority.NORMAL リスナに指定する優先度。
EventPriority.MONITOR

EventPriority.HIGHEST

EventPriority.HIGH

EventPriority.NORMAL

EventPriority.LOW

EventPriority.LOWEST

boolean ignoreCancelled false この値にTrueを指定したメソッド場合は、イベントがキャンセルされた際にイベントを受け付けない。
true

false

イベントの優先度[編集]

上記の表にあるように、イベントの優先度は6種類ありますが、イベントが呼び出される順序は下記のようになっています。

EventPriority.LOWEST
EventPriority.LOW
EventPriority.NORMAL
EventPriority.HIGH
EventPriority.HIGHEST
EventPriority.MONITOR

すべてのプラグインでイベント発生内容を取得できるようにする必要があります。
だから、あるプラグインでキャンセルされてしまった後であっても、その他のプラグインにもイベントリスナーが呼び出されます。
また、実際に別のプラグインが先にイベントをキャンセルしたとしても、イベントを uncancel することができます。
これを理解するには、優先順位の理解が本当に重要になります。

あるイベントが発生すると、まずLOWESTのリスナーが呼び出され、リスナーから設定内容の変更や、isCancelledの変更を行います。
その後、LOWからHIGHESTまで、順にリスナーが行われ、設定内容が書き換わります。
最終的に、MONITORのリスナーが呼び出されます。この時点で、全てのリスナーが設定した内容が最終結果として参照できるようになります。
MONITORは、イベントの内容を変更すべきではなく、イベントの結果を確認するためだけに使用してください。

例として、BLOCK_PLACE イベントが処理されるとしましょう。
3つのプラグインが有効になっており、1つ目は基本的な領域保護プラグイン、2つ目はカンバンを使った付加価値的プラグイン、3つ目はログ記録プラグインです。
領域保護プラグインはPriority.LOWESTで待機します。そのプラグインは、「この領域内にブロックを配置することはできない」と判断して、イベントをキャンセルします。
カンバンを使った付加価値的プラグインはPriority.NORMALで待機します。そのプラグインは、「この領域内にカンバンを置くことができる」と判断したので、イベントをuncancelします（event.isCancelled(false)）。
ログ記録プラグインはPriority.MONITORで待機します。これは、イベント処理が実際に実行された（キャンセルされていない）という最終結果を確認し、イベント内容をログに記録します。

あなたはイベントの結果を変更する場合、LOWESTからHIGHESTの間で、慎重に選択してください。
あなたが、イベントの最終結果を受け取りたいが、結果を変更しないときは、MONITORを使用してください。
ただし、MONITORのリスナーがイベントをキャンセルしたりしないように、イベントの内容を変更したりしないように、十分注意してください。最悪、他のプラグインの動作を阻害してしまうことになってしまいます。

イベントリスナの登録[編集]

イベントリスナを記述するクラスは、
Listenerインタフェースを実装(implements)し、かつイベントハンドラを含んでいなければなりません。

import org.bukkit.event.Listener;

public class LoginListener implements Listener {
}

イベントリスナの登録処理は、PluginManagerインスタンスのregisterEventsメソッドを使って、プラグインクラスと共に記述します。

getServer().getPluginManager().registerEvents(Listener, Plugin);

リスナの例[編集]

このリスナは、2つのイベントハンドラを含んでいます。
1つは高優先度のもの、もうひとつは通常の優先度のものです。

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;
 
public class LoginListener implements Listener {
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // 何かの処理
    }
 
    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // 何かの処理
    }
}

プラグインへのイベントの登録[編集]

イベントの登録処理は、リスナとプラグインが必要です。
丁度よい事に、既にLoginListenerを作成していますので、これを利用してLoginPluginを作りましょう！

import org.bukkit.plugin.java.JavaPlugin;

public class LoginPlugin extends JavaPlugin {
    public void onEnable() {
        getServer().getPluginManager().registerEvents(new LoginListener(), this);
    }
}

プラグインへのイベントのリスナとしての登録[編集]

メインとなるクラスもイベントを持つ事ができます。
例:

import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;
 
public class LoginPlugin extends JavaPlugin implements Listener {
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
    }
 
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // 何かの処理
    }
}

リスナへのイベントの登録[編集]

イベントの登録には複数の方法があります。リスナクラスでイベントを登録する例を記述します。

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;
 
public class LoginListener implements Listener {
    public LoginListener(LoginPlugin plugin) {
        plugin.getServer().getPluginManager().registerEvents(this, plugin);
    }
 
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // Some code here
    }
 
    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // Some code here
    }
}

LoginPluginは次のようになります：

import org.bukkit.plugin.java.JavaPlugin;
 
public class LoginPlugin extends JavaPlugin {
    public void onEnable() {
        new LoginListener(this);
    }
}

イベントリスナの登録解除[編集]

自分のプラグインから登録したイベントリスナだけでなく、他のプラグインから登録されたイベントリスナであっても、自由に登録を解除することが可能です。

特定のイベントからリスナを登録解除する[編集]

全てのイベントは、staticメソッドの getHandlerList() を持っています。
HandlerList を取得して unregister() メソッドを実行すれば、イベントに関連するリスナの登録を解除することが可能です。

例：

PlayerInteractEvent.getHandlerList().unregister(plugin);
// 指定したプラグインから PlayerInteractEvent に登録された、
// 全てのイベントリスナを登録解除します。

getHandlerList() メソッドの詳細については、後述の自作イベントのところで説明します。

全てのイベントリスナの登録解除[編集]

HandlerList クラスの staticメソッド unregisterAll() を使用すると、指定したプラグイン、または、指定したイベントリスナークラスから登録された全てのイベントリスナを登録解除することができます。

例：

HandlerList.unregisterAll(plugin);
// 指定したプラグインから登録された
// 全てのイベントリスナを登録解除します。

イベントの自作[編集]

Bukkit自体が利用しているイベント記述の仕組みと全く同一の仕組みを利用して、イベントを自作する事ができます。この方法は、従来のような、自作イベントである事に起因する固有のチェックが不要な点、 Bukkitの処理方法をそのまま利用するためにパフォーマンスを犠牲にしないという点で、従来のイベント自作の方法よりも優れています。

イベントを自作する際は、次の2点に留意して下さい。

Eventクラスを継承する必要がある
static(静的)なハンドラとして作成する必要がある

staticハンドラは、自作イベント中に次のように記述して下さい。

private static final HandlerList handlers = new HandlerList();
 
public HandlerList getHandlers() {
    return handlers;
}
 
public static HandlerList getHandlerList() {
    return handlers;
}

上記のコードを実際に自作のイベント処理の中に記述する事で、処理は疎結合となり、実行速度が改善します。

自作イベントの例[編集]

import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
 
public class CustomEvent extends Event {
    private static final HandlerList handlers = new HandlerList();
    private String message;
 
    public CustomEvent(String example) {
        message = example;
    }
 
    public String getMessage() {
        return message;
    }
 
    public HandlerList getHandlers() {
        return handlers;
    }
 
    public static HandlerList getHandlerList() {
        return handlers;
    }
}

自作イベントの呼び出し[編集]

イベントの呼び出し方法は、従来の方法と同様です：

// イベントのインスタンス化
CustomEvent event = new CustomEvent("Sample Message");
// イベントの実行
Bukkit.getServer().getPluginManager().callEvent(event);
// イベントから得たメッセージの出力処理
Bukkit.getServer().broadcastMessage(event.getMessage());

自作イベントの待ち受け[編集]

イベントはどのようにListen（待受,受付などとも表記）すれば良いでしょう？簡単です。通常のイベントと同様に待ち受けして下さい。

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
 
public class CustomListener implements Listener {
    @EventHandler
    public void normalLogin(CustomEvent event) {
        // 何かの処理
    }
}

自作イベントをキャンセル可能にする[編集]

次に、自作イベントをキャンセル可能に実装してみましょう。Cancellableクラスを実装してください（implements Cancellable）。
あとはそのまま利用してください。とっても簡単ですね！
では、実例をみてみましょう。

import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
    private static final HandlerList handlers = new HandlerList();
    private String message;
    private boolean cancelled;

    public CustomEvent(String example) {
        message = example;
    }

    public String getMessage() {
        return message;
    }

    public boolean isCancelled() {
        return cancelled;
    }

    public void setCancelled(boolean cancel) {
        cancelled = cancel;
    }

    public HandlerList getHandlers() {
        return handlers;
    }

    public static HandlerList getHandlerList() {
        return handlers;
    }
}

イベントをコールした後に、イベントがリスナーによってキャンセルされているかどうかを調べてください。
キャンセルされていないなら、通常通り処理を実行すれば良いのです。

// イベントのインスタンス化
CustomEvent event = new CustomEvent("Sample Message");
// イベントのコール
Bukkit.getServer().getPluginManager().callEvent(event);
// イベントがキャンセルされていないなら・・・
if (!event.isCancelled()) {
    // イベントからメッセージ内容を取得して処理する
    Bukkit.getServer().broadcastMessage(event.getMessage());
}