События

Что даёт вам эта страница: к концу вы напишете свой первый слушатель событий — слушатель-барьер установки, который нужен каждому аддону, трогающему базу данных, — и будете знать, как реагировать на другие действия платформы (входы, регистрации, удаление учётной записи) и даже запускать собственные межаддонные события.

Слушатель событий — это один из ваших классов, который Pano вызывает, когда на платформе что-то происходит. Вы реализуете интерфейс слушателя, помечаете класс @EventListener, и Pano подключает его во время сканирования — без вызова регистрации. Помните, что каждая правка бэкенда требует пересборки-и-перезапуска — см. Обзор бэкенда.

Барьер установки

Ваш класс-точка входа инициализирует конфигурацию и базу данных в startPlugin(), но заранее выходит, пока не завершится мастер первичной установки Pano, — иначе не было бы базы данных для инициализации. (Эта защита живёт в ShoutboxPlugin в Обзоре бэкенда.) Чтобы подхватить всё в тот момент, когда установка завершится, добавьте небольшой слушатель событий рядом с классом плагина (файл event/SetupEventHandler.kt):

package com.panomc.plugins.shoutbox.event

import com.panomc.platform.api.annotation.EventListener
import com.panomc.platform.api.event.SetupEventListener
import com.panomc.plugins.shoutbox.ShoutboxPlugin

@EventListener
class SetupEventHandler(private val plugin: ShoutboxPlugin) : SetupEventListener {
    override suspend fun onSetupFinished() {
        plugin.startPlugin()
    }
}

Когда мастер завершается, Pano вызывает onSetupFinished(), startPlugin() выполняется снова, а защита isInitialized делает безопасным вызвать его более одного раза.

• Откуда берётся plugin в этом конструкторе? Ваш собственный класс плагина тоже внедряем. Pano кладёт единственный экземпляр ShoutboxPlugin в вашу коробку, поэтому любой из ваших классов может взять его как параметр конструктора — вот как этот слушатель (и эндпоинт панели) получает его. Так что правило «что я могу внедрить?» такое: всё, что в вашей коробке, — ваши классы @Dao/@Endpoint/и т. д., плюс экземпляр вашего плагина.

Каждому аддону, трогающему базу данных, нужен ровно этот паттерн барьера установки. Скопируйте оба класса — класс плагина из Обзора бэкенда и этот слушатель — как есть и меняйте только имена классов.

Используйте @EventListener от Pano, а не от Spring

Аннотация — это com.panomc.platform.api.annotation.EventListener — а не org.springframework.context.event.EventListener от Spring. У них одинаковое простое имя, поэтому легко импортировать не тот; если так, система событий молча никогда не вызовет ваш слушатель.

Реакция на другие действия платформы

SetupEventListener — один из нескольких интерфейсов слушателей. Паттерн всегда один и тот же — реализуйте интерфейс, аннотируйте класс @EventListener, переопределяйте только те методы, которые вам важны. Среди прочего вы можете реагировать на:

• входы и регистрации — выполняйте код до или после аутентификации пользователя либо наложите вето на вход.
• удаление учётной записи — очищайте свои таблицы, когда пользователь удаляется.
• ваши собственные межаддонные события — позвольте другим аддонам реагировать на то, что делает ваш аддон, и реагируйте на их события.

Полный каталог — хуки аутентификации, очистка при удалении учётной записи, слушатели жизненного цикла плагинов и запуск собственных межаддонных событий (включая вызов getEventListeners в объекте-компаньоне и подводный камень ClassCastException у PluginLifecycleListener) — перечислен с сигнатурами в Справочнике Backend API § 6.

Что дальше

• Справочник Backend API § 6 — каждый интерфейс слушателя событий, его методы и два, которые ломают обычный паттерн.
• Обзор бэкенда — класс-точка входа ShoutboxPlugin, который перезапускает этот слушатель.
• Права доступа и журналы активности — другая половина административного действия: его защита и логирование.