Перевод SpongeAPI #3 События

События
События (events) используются, чтобы сообщить плагинам о том, что что-то произошло. Многие события могут быть отменены, то есть, можно предотвратить действие, к которому относится событие. Отменяемые события реализуют интерфейс Cancellable.

В Sponge имеется много событий; но также плагины могут создавать свои собственные события, которые могут отлавливать другие плагины.

Слушателям событий присваивается приоритет, определяющий порядок, в котором слушатель событий запускается в контексте других слушателей событий (например, из других плагинов). Например, слушатель событий с приоритетом EARLY будет выполнен перед большинством других слушателей событий. См. О аннотации @Listener для получения дополнительной информации.

Диспетчер событий или менеджер событий - это класс, который отслеживает, какие плагины прослушивают какое либо событие, а также отвечает за вызов событий для слушателей событий.

Информация о любом событии передается всем плагинам без исключения!!

Слушатели событий
Чтобы прослушать(отловить) событие, слушатель события должен быть зарегистрирован. Это делается путем создания метода с любым именем, определяя первый параметр как желаемый тип события, а затем прикрепляя аннотацию @Listener к методу, как показано ниже.
Также, все классы, содержащие слушатели, должен быть зарегистрирован в менеджере событий. Исключением является класс с аннотацией @Plugin. Он регистрируется автоматический.

Примечание:
" Шина событий поддерживает супертипы. Например, ChangeBlockEvent.Break наследует ChangeBlockEvent. Поэтому слушшатель может отлавливать ChangeBlockEvent и все равно получать ChangeBlockEvent.Break. Однако слушатель, который отлавливает только ChangeBlockEvent.Break, не будет уведомлен о других типах ChangeBlockEvent. "

Регистрация слушателей событий в других классах
Для регистрации слушателей событий, с аннотацией @Listener, которые не входят в основной класс плагина, вы можете использовать метод EventManager#registerListeners(Object, Object), который принимает ссылку на плагин и экземпляр класса, содержащий слушателей событий.

Java:

import org.spongepowered.api.Sponge;[/SIZE][/FONT]
[SIZE=4][FONT=georgia]
public class ExampleListener {

    @Listener
    public void onSomeEvent(SomeEvent event) {
        // Do something with the event
    }
}

Sponge.getEventManager().registerListeners(this, new ExampleListener());

Динамическая регистрация слушателей событий
Некоторым плагинам (такие как скриптовые плагины) может понадобиться динамически регистрировать слушатели событий. В этом случае слушатель событий - это не метод с аннотацией @Listener, а класс, реализующий интерфейс EventListener. Этот слушатель событий может быть зарегистрирован путем вызова EventManager#registerListener, который принимает ссылку на плагин в качестве первого аргумента, Class события, как второй аргумент, а самого слушателя в качестве последнего аргумента. При желании вы можете указать Order для запуска слушателя событий в качестве третьего аргумента или логическое значение в качестве четвертого аргумента (перед экземпляром слушателя), которое определяет, следует ли вызывать слушателя до других модификаций сервера.
Пример реализации EventListener
Пример регистации:
Примечание:
"Для слушателей событий, созданных с помощью аннотации @Listener, можно настроить порядок выполнения. Для динамически зарегистрированных слушателей нужно использовать метод EventManager#registerListener, передавая третьим аргументом Order"

Отмена регистрации слушателей событий
Чтобы отменить регистрацию одного слушателя событий, вы можете использовать метод EventManager#unregisterListeners(Object), который принимает экземпляр класса, содержащего слушателей событий.

Кроме того, можно использовать EventManager#unregisterPluginListeners(Object),
передавая ссылку на плагин, чтобы отменить регистрацию всех слушателей
событий, связанных с этим плагином. Обратите внимание, что это удалит все слушатели событий плагина, даже те, которые зарегистрированы с аннотациями @Listener.

О аннотации @Listener
У аннотации @Listener имеется несколько настраиваемых полей:

• order устанавливает приоритет исходя из которого состовляется порядок вызывания слушателей.
• beforeModifications указывает, должен ли слушатель событий вызываться перед модами сервера, такими как моды Forge. По умолчанию установлено значение false.

По умолчанию @Listener настроен так, что ваш слушатели событий не будут вызываться, если событие отменяемое и было отменено (например, другим плагином).

GameReloadEvent
Чтобы все плагины не предоставляли свои собственные команды перезагрузки, Sponge предоставляет свою встроенную, которую плагины могут прослушивать и при выполнении выполнять любые действия по перезагрузке. То, что представляет собой «перезагрузка», зависит только от плагина. GameReloadEvent сработает, когда игрок выполнит команду перезагрузки /sponge plugins. Событие не обязательно ограничено перезагрузкой конфигурации.
Обратите внимание, что это отличается от того, что обычно подразумевается под „перезагрузкой“, поскольку событие является просто вызовом для плагинов и не выполняет никакой перезагрузки самостоятельно.