# Extensions # Service Ein Service ist die generischste Schnittstelle, die ein Plugin bereitstellen kann, denn es wird eine beliebige Anzahl Parameter beliebigen Typs entgegengenommen und ein Objekt beliebigen Typs zurückgegeben. ```kotlin fun registerService(serviceName: String, service: Service) ``` `serviceName` ist eine frei wählbare ID, die über alle Services eines Plugins hinweg eindeutig sein muss. Es ist kein Problem, wenn mehrere Plugins einen Service mit derselben ID bereitstellen, da zum Ansprechen eines Services auch die `id` des Plugins herangezogen wird. Ein Service muss `com.batix.plugins.Service` implementieren. Hier gibt es nur eine Methode, `call`. Diese Methode nimmt eine beliebige Anzahl an Argumenten vom Typ `Any?` (entspricht `Object` in Java) entgegen und gibt ein Objekt vom Typ `Any?` zurück (kann auch `null` sein). Es liegt an der Implementierung selbst, herauszufinden, wie viele Argumente übergeben wurden, welchen Typ diese haben, dementsprechend Code auszuführen und ein Ergebnis zurückzugeben. Nutzern dieses Services sollte in einer Anleitung die `id` des Plugins und des Services sowie die Semantik mitgeteilt werden, also wie sich die Methode bei welchen Parametern verhält.

**Typen** Die Typen der Parameter und des zurückgegebenen Objektes (und jeweils eventueller weiterer, darin eingebetteter Typen – wie bei Listen oder Maps) sollte sich auf **Standard-JVM- und Framework-Typen** wie beispielsweise `String` oder `ContainerRecord` beschränken. Das hat den Hintergrund, dass die Klassen des Plugins und seiner Dependencies nicht im Framework und anderen Plugins bekannt sind. Außerdem hilft es Leaks zu vermeiden, wenn das Plugin entladen wird.

Mithilfe der Klasse `com.batix.plugins.Plugin` kann auf einen Service zugegriffen werden. Dafür holt man sich zunächst mittels der statischen Methode `byId` eine Referenz auf das Plugin und dann davon weiter eine Referenz auf den Service via `getService`. Beide Referenzen können befragt werden, ob das Plugin geladen bzw. der Service verfügbar ist. Die Service-Referenz stellt eine `call` Methode (blockiert den aktuellen Thread) sowie eine asynchrone `callAsync` Methode (gibt ein `Future` Objekt zurück) bereit. Beide Methoden liefern eine Exception, falls das Plugin oder der Service nicht verfügbar ist. Eine andere Möglichkeit stellen die `tryCall` und `tryCallAsync` Methoden bereit. Diese werfen keine Exception, wenn etwas nicht verfügbar ist, sondern haben dann als Ergebnis das Objekt `com.batix.plugins.PluginRef.ServiceRef.UNAVAILABLE`. ## Beispiel Die `Service`-Klasse im Beispiel besteht nur aus einer Methode, die eine Anzahl von `String`-Parametern erwartet und einen `String` zurückgibt (je nach Anzahl der Parameter einen anderen). ```kotlin import com.batix.plugins.Service class HelloService : Service { override fun call(vararg args: Any?): Any { return when { args.isEmpty() -> "Hello." args.size == 1 -> "Hi ${args[0]}!" else -> "Welcome ${args.joinToString(separator = ", ")}." } } } ``` In der Plugin-Hauptklasse wird der Service registriert. ```kotlin override fun load() { registerService(`"hello-service"`, HelloService()) } ``` Aufrufen kann man diesen Service dann z. B. mittels Groovy-Code im Framework. ```groovy import com.batix.plugins.Plugin import com.batix.plugins.PluginRef def service = Plugin.byId("com.batix.website:mitarbeiter-import") .getService("hello-service") println(service.call()) // "Hello." println(service.call("John")) // "Hi John!" println(service.call("Joe", "Jack", "Jill")) // "Welcome Joe, Jack, Jill." ``` # Action Plugins haben die Möglichkeit, Actionbausteine bereitzustellen, die ganz normal in Menüpunkt-Aktionen im Framework verwendet werden können. Plugin-Actionbausteine stehen dann dort (gruppiert nach Plugin) genau wie die Standard-Bausteine zur Auswahl. ```kotlin fun registerAction(actionId: String, actionInfo: ActionInfo) ``` `actionId` ist eine frei wählbare ID, die über alle Actionbausteine eines Plugins hinweg eindeutig sein muss. Es ist kein Problem, wenn mehrere Plugins einen Baustein mit derselben ID bereitstellen, da zum Ansprechen eines Actionbausteins auch die `id` des Plugins herangezogen wird. `actionInfo` enthält die Metadaten des Actionbausteins, wie Titel und Beschreibung. Es kann auch ein Link zu einer externen Hilfeseite definiert werden. Außerdem wird die Klasse referenziert, welche den Baustein implementiert. Diese Klasse muss von `com.batix.plugins.PluginAction` abgeleitet sein und die `doAction()` Methode implementieren. Jeder Aufruf einer Aktion erzeugt für jeden Actionbaustein eine eigene Instanz der entsprechenden Klasse. Innerhalb von `doAction()` stehen dann z. B. `request` und `response` zur Verfügung. ## Parameter / Properties Damit der Baustein in der Verwaltung konfiguriert werden kann, müssen dessen Parameter definiert werden. Diese werden in `actionInfo` hinterlegt und können dann in `doAction()` ausgelesen werden. Es können verschiedenartige Parameter hinterlegt werden, so gibt es z. B. die Methoden `addTextParameter` für Texteingaben oder `addBooleanParameter` für eine Ja/Nein-Auswahl. ```kotlin fun addTextParameter( name: String, title: String, description: String, descriptionIsHtml: Boolean, required: Boolean ) ``` `name` ist ein interner Bezeichner, der dann auch wieder beim Auslesen in `doAction` angegeben werden muss.

**Tip** Es empfiehlt sich, diesen internen Wert als Konstante im Code zu definieren, da der Wert an mehreren Stellen im Code (Parameterdefinition und Auslesen) benötigt wird.

Mit `title` kann für die Anzeige im Backend ein freundlicher Name gesetzt werden. `description` ist ein Erklärungstext, der unter dem Titel angezeigt wird – `descriptionIsHtml` legt fest, ob dieser bereits als HTML formatiert ist oder nicht. Falls `required` gesetzt ist, wird dieser Parameter in der Verwaltung als Pflichteingabe markiert. In der Action kann dann mit `getProperty`, `getPropertyReplaced` oder `getBooleanProperty` der vom Benutzer eingestellte Wert abgefragt werden. ```kotlin fun getProperty(key: String): String? fun getProperty(key: String, defaultValue: String?): String? fun getPropertyReplaced(key: String): String? fun getPropertyReplaced(key: String, defaultValue: String?): String? fun getBooleanProperty(key: String): Boolean ``` `getPropertyReplaced` ersetzt Platzhalter in der Form \[\[paramname\]\] durch den Wert des Request-Parameters oder Actionscript-Attributs `paramname`. Mittels `addCustomParameter` kann sogar komplett eigener HTML-Code zur Benutzereingabe geliefert werden. Dazu leitet man am besten eine Klasse von `com.batix.action.ExtendedActionParameter` ab und implementiert im Minimum die folgenden Methoden: - `getName()` – liefert den internen Bezeichner zurück - `getTitle()` – gibt den Titel zurück - `writeAdminView(StringBuffer, String, Connection)` - in den `StringBuffer` schreibt man den HTML-Quelltext, der in der Verwaltung angezeigt werden soll - der `String` ist der aktuell gespeicherte Wert des Parameters - `Connection` ist eine Datenbankverbindung Wichtig hierbei ist, dass `writeAdminView` ein HTML-Formular-Element mit passendem `name` erzeugt (Prefix `param:` und dann der interne Bezeichner), damit die Eingabe auch gespeichert wird. ## Beispiel Das Beispiel-Action definiert 3 Parameter: einen vom Typ Text, eine Ja/Nein-Auswahl und einen speziellen Parameter. Die Action-Klasse definiert die internen Bezeichner der Parameter als Konstanten. In der `doAction`-Methode werden die Parameter ausgelesen. ```kotlin import com.batix.plugins.PluginAction class ImportMitarbeiterAction : PluginAction() { companion object { const val PROP_API_TOKEN = "api-token" const val PROP_SEND_NOTIFICATION = "send-notification" const val PROP_IMPORTANT_THING = "important-thing" } override fun doAction() { val apiToken = getPropertyReplaced(PROP_API_TOKEN, "") require(!apiToken.isNullOrEmpty()) { "API-Token darf nicht leer sein" } val doSendNotification = getBooleanProperty(PROP_SEND_NOTIFICATION) val importantThing = getProperty(PROP_IMPORTANT_THING) // ... } } ``` Damit der Baustein in der Verwaltung auftaucht, muss dieser dem Application Framework bekannt gegeben werden. Das erfolgt in der `load`-Methode der Plugin-Hauptklasse. Hier werden nebst den Metadaten des Bausteins auch dessen Parameter definiert. ```kotlin override fun load() { registerAction( "import-mitarbeiter", // actionId ActionInfo( "Mitarbeiter importieren", // title "Importiert Mitarbeiter aus der externen Datenquelle.", // description false, // deprecated true, // beta "https://www.batix.de/unternehmen/unternehmenskultur/team/", // helpLink ImportMitarbeiterAction::class.java // actionClass ).apply { addTextParameter( ImportMitarbeiterAction.PROP_API_TOKEN, // name "API Token", // title "Token zur Authentifizierung an der abzufragenden API", // description false, // descriptionIsHtml true // required ) addBooleanParameter( ImportMitarbeiterAction.PROP_SEND_NOTIFICATION, // name "Benachrichtigung versenden", // title "(Standard: nein)", // description false, // descriptionIsHtml false // required ) addCustomParameter(object : ExtendedActionParameter() { override fun getName(): String { return ImportMitarbeiterAction.PROP_IMPORTANT_THING } override fun getTitle(): String { return "Wichtige Einstellung" } override fun writeAdminView(sb: StringBuffer, value: String?, conn: Connection) { sb.append("""""") } }) } ) } ``` Der Plugin-Actionbaustein taucht somit in der Auswahl der Actionbausteine auf. ![action-auswahl.png](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/1zxppJGkTZeN7E4E-action-auswahl-png.png) Die definierten Parameter stehen im Formular zur Verfügung. ![action-parameter.png](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/5FL04O92bH6CJ0qd-action-parameter-png.png)`` # Tag Das Framework kann durch Plugins um Batix-Tags (``) erweitert werden, welche dann in normalen Quelltexten wie Komplettseiten oder Textbausteinen verwendet werden können. ```kotlin fun registerTag(tagInfo: TagInfo) ``` Es gibt zwei Arten von Tags: Frontend- und Backend-Tags. Der Unterschied besteht darin, dass sich Backend-Tags in der Verwaltung darstellen oder dort konfiguriert werden können (wie z. B. `` oder ``), Frontend-Tags hingegen können dies nicht. ## Frontend-Tags Frontend-Tags werden mithilfe von `TagInfo.frontend` registriert und müssen von `com.batix.plugins.PluginFrontendTag` abgeleitet sein. Es reicht im einfachsten Fall, die Methode `addFrontendSourceText(StringBuffer)` zu überschreiben. An den `StringBuffer` hängt man die Ausgabe an und gibt diesen am Ende wieder zurück. ```kotlin registerTag(TagInfo.frontend("tagname", MyFrontendTag::class.java, null)) ```

**Injection Vulnerability** Es müssen (HTML-)Steuerzeichen passend encoded werden, um Injectionlücken zu vermeiden.

Es empfiehlt sich daher die Methode `writeEncodedOutput(String, StringBuffer)` zu benutzen. Dieser übergibt man als ersten Parameter den gewünschten (uncodierten) Ausgabetext und reicht als zweiten Parameter den `StringBuffer` durch, den man übergeben bekommen hat. Die Methode sorgt automatisch dafür, dass entsprechend der aktuellen Frontendseite das passende Encoding (z. B. htmlencode bei HTML-Seiten) gewählt wird. Außerdem unterstützt das Tag damit automatisch den Parameter `encode` (also z. B. ``). ## Backend-Tags Backend-Tags werden mithilfe von `TagInfo.backend` registriert und müssen von `com.batix.plugins.PluginBackendTag` abgeleitet sein. Hier müssen neben `addFrontendSourceText(StringBuffer)` noch die Methoden `getDataTable()` und `addAdminSourceText(StringBuffer)` überschrieben werden. ```kotlin registerTag(TagInfo.backend("tagname", MyBackendTag::class.java, null)) ``` Der erste Parameter (`"tagname"`) ist dabei der Name des Tags, wie er dann auch hinter `etwas Inhalt...`), kann der Inhalt (*Body*) mittels `computeBody()` ausgeführt und das Ergebnis ausgelesen werden. Eventuelle Batix-Tags im Body werden damit auch evaluiert. ## Parameter Einem Tag können im Quelltext Parameter übergeben werden. ```html ``` Diese Parameter können mit den `get*Parameter(key: String)`-Methoden ausgelesen werden – `key` ist der Name des Parameters. Mit `containsParameter(key: String)` kann festgestellt werden, ob ein Parameter angegeben wurde oder nicht. ```kotlin fun getStringParameter(key: String): String? fun getStringParameter(key: String, defaultValue: String?): String? fun getIntParameter(key: String): Integer fun getIntParameter(key: String, defaultValue: Integer): Integer fun getBooleanParameter(key: String): Boolean ``` ## Backend-Tag Speicherung Backend-Tags stellen ein Eingabeelement für Redakteure oder Admins bereit. Dafür muss im Quellcode ein sogenannter Titel am Tag vergeben werden. Bei `` ist der Titel beispielsweise "Anrede". Dieser wird dem Benutzer im Backend angezeigt. Das bedeutet, dass die vom Benutzer getätigten Eingaben in der Datenbank gespeichert werden müssen. Die Methode `getDataTable()` teilt dem Framework mit, in welcher Tabelle die Daten zu speichern sind. Für kurze, einzeilige Texte ist das "EZT", für längere Texte "MZT". Der entsprechende Wert ist von `getDataTable()` einfach als String zurückzugeben. Die Methode `addAdminSourceText(StringBuffer)` ist für das Rendern des entsprechenden Eingabefeldes zuständig. Für kurze Texte kann das ein `` sein. Der Name des Inputs muss als Prefix die Tabelle (gleicher Wert wie bei `getDataTable()`), einen Punkt als Separator und als Suffix den Titel des Tags enthalten (dieser ist als Feld `titel` verfügbar). Er muss also beispielsweise "EZT.Anrede" lauten. Ist bereits ein Wert gespeichert, ist das Feld `dataId` gefüllt. Dessen Wert muss dann noch, inklusive einem weiteren Punkt, an den Name angehangen werden.

**Vorgefertigte Methoden** Als Best-Practice empfiehlt sich die Verwendung der Methoden `appendAdminHeadline(StringBuffer)` und `appendPublishStatus(StringBuffer)`, um eine konsistente Ausgabe des Titels und des Veröffentlichungsstatus zu erreichen.

Der Aufruf `getData("INHALT")` gibt den aktuell in der Datenbank gespeicherten Wert zurück. Dieser kann dann zur Ausgabe im Frontend sowie zur Vorbefüllung des Eingabefelds im Backend verwendet werden. ## Beispiel ### Frontend-Tag Das Tag wird in der Plugin-Hauptklasse mithilfe von `TagInfo.frontend` registriert. ```kotlin override fun load() { registerTag(TagInfo.frontend("unixtime", UnixTimeTag::class.java, null)) } ``` Dieses Beispiel-Tag gibt den aktuellen Epoch-Timestamp aus. ```kotlin import com.batix.plugins.PluginFrontendTag import com.batix.tags.BatixTagData import java.time.Instant class UnixTimeTag(data: BatixTagData?) : PluginFrontendTag(data) { override fun addFrontendSourceText(sb: StringBuffer): StringBuffer { val time = Instant.now().epochSecond writeEncodedOutput(time.toString(), sb) return sb } } ``` Der Aufruf im Quellcode ist minimal. ```html ``` Die Ausgabe im Frontend ist dann z. B. *1584620787*. ### Backend-Tag In der Plugin-Hauptklasse wird das Tag mit `TagInfo.backend` registriert. ```kotlin override fun load() { registerTag(TagInfo.backend("formattedtime", FormattedTimeTag::class.java, null)) } ``` Die Tag-Klasse implementiert die Frontend-Logik sowie die Anzeige des Eingabeelements im Backend. ```kotlin import com.batix.Tools import com.batix.plugins.PluginBackendTag import com.batix.tags.BatixTagData import java.time.LocalDateTime import java.time.format.DateTimeFormatter import java.util.* class FormattedTimeTag(data: BatixTagData?) : PluginBackendTag(data) { override fun addFrontendSourceText(sb: StringBuffer): StringBuffer { // Backendeingabe lesen val pattern = getData("INHALT") as String? ?: "dd.MM.yyyy HH:mm:ss" // Parameter aus Quelltext lesen val locale = Locale.forLanguageTag(getStringParameter("locale", "de-DE")) val now = LocalDateTime.now() val formatter = DateTimeFormatter.ofPattern(pattern, locale) writeEncodedOutput(formatter.format(now), sb) return sb } override fun getDataTable(): String { return "EZT" } override fun addAdminSourceText(sb: StringBuffer): StringBuffer { val inhalt = getData("INHALT") as String? ?: "" appendAdminHeadline(sb) appendPublishStatus(sb) var inputName = "$dataTable.$titel" if (dataId != null && dataId != "del") { inputName += ".$dataId" } sb.append("""""") return sb } } ``` Im Quelltext wird das Tag dann inklusive Titel verwendet. ```html ``` In der Verwaltung können Eingaben getätigt werden. ![tag-beispiel.png](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/rJlnHilQYC8xvdEX-tag-beispiel-png.png) Im Frontend wird dann z. B. folgender Text ausgegeben: ``` 13:28 19. March ``` # Timer Job Plugins können neue Timer-Tasks für die im Framework eingebaute Zeitsteuerung mitbringen. Diese können dann beim Anlegen neuer Zeitsteuerungen ausgewählt und parametrisiert werden. ```kotlin fun registerTimerJob(jobId: String, jobInfo: JobInfo) ``` `jobId` ist eine frei wählbare ID, die über alle Timer Jobs eines Plugins hinweg eindeutig sein muss. Es ist kein Problem, wenn mehrere Plugins einen Job mit derselben ID bereitstellen, da zum Ansprechen eines Jobs auch die `id` des Plugins herangezogen wird. Der Titel des Jobs, sowie eine Instanz der implementierenden Klasse und die Standard-Parameter werden in `jobInfo` festgehalten. Die Standard-Parameter sind ein String-Array - jedes Element davon wird in der Oberfläche im Textfeld in eine eigene Zeile geschrieben (Kommentarzeilen beginnen mit `#`).

**Thread-Safety** Die Instanz wird für alle Ausführungen nachgenutzt, sollte also thread-safe programmiert werden.

Die Klasse muss die `run(JobContext)` Methode aus `com.batix.plugins.Job` implementieren. `JobContext` enthält Informationen zum aktuellen Aufruf, wie z. B. die vom Benutzer eingestellten Parameter (`properties`) oder das Projekt, in dem die Zeitsteuerung definiert wurde (`web`). ## Beispiel Der Timer Job wird dem Framework in der Plugin-Hauptklasse bekannt gegeben. ```kotlin override fun load() { registerTimerJob( "logString", // jobId JobInfo("Log String", LogStringJob(), arrayOf("level", "#text")) ) } ``` Diese Beispiel-Job-Klasse liest die eingestellten Parameter und loggt die festgelegte Nachricht mit dem entsprechenden Level. ```kotlin import com.batix.Log import com.batix.plugins.Job import com.batix.plugins.JobContext class LogStringJob : Job { override fun run(context: JobContext) { val level = context.properties.getProperty("level", "INFO") val text = context.properties.getProperty("text", "DEFAULT TEXT") when (level.lowercase()) { "error" -> Log.error(text) "warn" -> Log.warn(text) "notice" -> Log.notice(text) "debug" -> Log.debug(text) else -> Log.info(text) } } } ``` Der Job ist dann in der TimerTask-Auswahl einer Zeitsteuerung sichtbar. [![timer-task.png](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/SUSKvsufU8D35Rla-timer-task-png.png)](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/SUSKvsufU8D35Rla-timer-task-png.png) Wählt man diesen aus, werden die Steuerparameter vorausgefüllt. ``` level= #text= ``` # Request Interceptor (ehemals "Request Handler") Bestimmte, von Clients (z. B. Browser) angefragte Pfade, können durch Plugins überwacht und optional direkt beantwortet werden, ohne die Standardabläufe des Frameworks (wie Projekt und Menüpunkt finden) zu involvieren. ```kotlin fun registerRequestInterceptor( pathPattern: String, interceptor: RequestInterceptor, priority: Int = 50 ) fun registerRequestInterceptor( condition: RequestCondition, interceptor: RequestInterceptor ) ``` Im einfachsten Fall wird ein regulärer Ausdruck (`pathPattern`) definiert und alle Requests mit passendem Pfad (also dem Text hinter der Domain ab `/`) werden an den `interceptor` gegeben. Mit einer `RequestCondition` kann zusätzlich noch die Domain (auch mittels regulärem Ausdruck) abgefragt werden. Außerdem kann damit nur auf Forwards reagiert (`onlyForwards()`) oder es können Forwards ausgeschlossen werden (`noForwards()`). Der `interceptor` muss das Interface `com.batix.plugins.RequestInterceptor` implementieren. Hier gibt es drei Methoden, von denen eine oder mehrere überschrieben werden können. Die `priority` bestimmt die Ausführungsreihenfolge der Interceptors und kann gesetzt werden, wenn man mit einem Interceptor andere beeinflussen will. ## `RequestInterceptor`-Interface

**Thread-Safety** Dieselbe Instanz wird für alle Requests verwendet, muss also thread-safe implementiert werden.

Es können drei Methoden implementiert werden: ```kotlin fun handlePre(event: RequestEvent) fun handlePost(event: RequestEvent) fun handleFrontendException(event: RequestEvent, exception: FrontendException) ``` Das `RequestEvent` beinhaltet dabei den `event.request: HttpServletRequest` und den `event.response: HttpServletResponse` sowie Methoden, um die folgende Requestbehandlung zu beeinflussen. `handlePre` wird noch vor allen Framework-Funktionen aufgerufen und bestimmt durch das übergebene `RequestEvent`, ob der Request komplett vom Plugin behandelt wurde und deshalb von folgenden Plugins oder vom Framework nicht weiter beachtet werden soll. Wird auf dem Event `preventDefault` aufgerufen, wird das Framework seine Standardabläufe (wie z. B. Projekt und Menüpunkt finden) nicht durchführen. Ohne den Aufruf läuft der Request normal weiter - in diesem Fall sind Modifikationen an `response` mit Vorsicht zu genießen, da die weiteren Abläufe ggf. zu einem Redirect führen oder gesetzte Werte wieder überschrieben werden können. Wird auf dem Event `stopPropagation` aufgerufen, werden (nach priority) nachfolgende Plugins den Request nicht erhalten und damit auch nicht auf diesen reagieren können. Der Aufruf von `handlePost` erfolgt, nachdem alle anderen Abläufe im Framework erledigt sind, auch falls es Fehler gab. In dieser Phase könnten schon Teile der Response-Header oder sogar des Response-Bodys geschrieben sein, Modifikationen dort sollten also mit Bedacht durchgeführt werden, wenn überhaupt. Methodenaufrufe auf dem `RequestEvent` zur Beeinflussung des nachfolgenden Ablaufs sind hier wirkungslos - das Framework hat den Request bereits behandelt, und nachfolgende Plugins werden auch nur dann übersprungen, falls in `handlePre` der `stopPropagation`-Aufruf erfolgte. Mit `handleFrontendException` kann auf Fehler aufgrund verschiedener Dinge, wie z. B. Projekt / Menüpunkt / Datei nicht gefunden, fehlende Authentifizierung oder auch Serverfehler, reagiert werden - wobei der genaue Fehler(-Grund) in `exception` festgehalten ist. Hier kann lediglich mit `preventDefault` die nachfolgende Fehlerbehandlung des Frameworks unterbunden werden - nicht aber die nachfolgender Plugins. Möchte man die Methoden je Request korrelieren, so bieten sich Request-Attribute an, in denen man seinen State festhalten kann. In der `RequestInterceptor`-implementierenden Klasse selbst können keine Felder o. ä. benutzt werden, da die Instanz der Klasse ja threadübergreifend verwendet wird. Es werden übrigens nicht nur Frontendaufrufe gematcht. Auch Aufrufe des Backends können überwacht werden. So könnte man dieses z. B. durch eine Prüfung der Client-IP, oder anderen Merkmalen, noch weiter abschotten. Eine Sonderform von Request Interceptors ist für [statischen Content](https://batix.help/books/batix-plugins/page/static-content) verfügbar. ## Priority Die `priority` bestimmt die Ausführungsreihenfolge der Interceptors, auch über mehrere Plugins hinweg: Je niedriger die Priorität, desto früher wird ein Interceptor aufgerufen. Im Regelfall spielt sie kaum eine Rolle, ist aber entscheidend um zu bestimmen, welche Interceptors denn von Aufrufen von `stopPropagation` betroffen werden sollen. `stopPropagation` kann aber in jedem Fall nur Interceptors mit einem größeren `priority`-Value betreffen - mehrere Interceptors derselben Priorität können sich nicht gegenseitig abbrechen. Zudem wird sich der Prioritätswert gemerkt, falls in `handlePre` `stopPropagation` aufgerufen wird, und gewährleistet, dass auch das `handlePost` der verhinderten Interceptors nicht aufgerufen wird. `registerRequestInterceptor( condition: RequestCondition, interceptor: RequestInterceptor)` nimmt keine gesonderte `priority`, da diese intern Teil der `RequestCondition` ist und direkt auf ihr definiert werden kann. ## Beispiel Hier werden drei Request Interceptors registriert. Einer misst die Dauer von Requests, ein Weiterer überprüft Authentifizierung bei API-Zugriffen, ein Letzter führt eine Fehlerstatistik. ```kotlin override fun load() { registerRequestInterceptor( "^/api/.*", AuthInterceptor(), RequestCondition.AUTH_PRIORITY ) registerRequestInterceptor("^/api/.*", TimingInterceptor()) registerRequestInterceptor("^(?!/verwaltung/).*", ErrorMetricsInterceptor()) } ``` Der `AuthInterceptor` prüft bei jedem Request, ob es sich um einen authentifizierten `BxUser` handelt, der einer bestimmten Gruppe angehört und blockt unauthentifizierte Anfragen ab, indem er die Ausführung nachfolgender Interceptors (in diesem Fall `TimingInterceptor` - aber auch andere Interceptors anderer Plugins, die auf dem selben Pfad lauschen) und Framework-Funktionen verhindert. Die `AUTH_PRIORITY` entspricht einem Wert von *15* und liegt damit vor allen anderen registrierten Interceptors. Hier wird zwar nur `handlePre` implementiert, trotzdem wird implizit auch `handlePost` vom `TimingInterceptor` verhindert. ```kotlin import com.batix.Log import com.batix.ConnectionPool import com.batix.modul.BxUser import com.batix.plugins.RequestEvent import com.batix.plugins.RequestInterceptor import jakarta.servlet.http.HttpServletResponse class AuthInterceptor : RequestInterceptor { override fun handlePre(event: RequestEvent) { val user = BxUser.findInstance(event.request) // User-Instanz if (user != null) { // angemeldet ConnectionPool.withSystemConnectionDo { conn -> if ("17AD26C9C4C" in user.getGroups(conn).map { it.id }) { Log.debug("user is authenticated") return } } } event.preventDefault() event.stopPropagation() event.response?.sendError(HttpServletResponse.SC_UNAUTHORIZED) } } ``` Der `TimingInterceptor` merkt sich zu Beginn aller Requests, die mit `/api/` anfangen, deren Start in einem Request-Attribut. Wenn der Request fertig ist, wird der Startzeitpunkt wieder ausgelesen, die Dauer berechnet und geloggt. Ohne explizite Angabe einer `priority` erhält er die `RequestCondition.DEFAULT_PRIORITY` von *50*. ```kotlin import com.batix.Log import com.batix.plugins.RequestEvent import com.batix.plugins.RequestInterceptor import java.time.Duration import java.time.Instant class TimingInterceptor : RequestInterceptor { override fun handlePre(event: RequestEvent) { event.request.setAttribute(REQUEST_STARTED_ATTRIBUTE, Instant.now()) // event.preventDefault() // CMS-Weiterbehandlung stoppen // event.stopPropagation() // Plugin-Weiterbehandlung stoppen } override fun handlePost(event: RequestEvent) { val instant = event.request.getAttribute(REQUEST_STARTED_ATTRIBUTE) as Instant val duration = Duration.between(instant, Instant.now()) Log.debug("request of ${event.request.requestURL} took $duration") } companion object { private const val REQUEST_STARTED_ATTRIBUTE = "timing-interceptor-started" } } ``` `ErrorMetricsInterceptor` überwacht für alle Requests, die **nicht** mit `/verwaltung/` anfangen, aufgetretene Fehler und aktualisiert eine fiktive Statistik. ```kotlin import com.batix.plugins.RequestInterceptor import com.batix.tags.FrontendException import com.batix.tags.FrontendExceptionInterface import com.batix.plugins.RequestEvent class ErrorMetricsInterceptor : RequestInterceptor { override fun handleFrontendException(event: RequestEvent, exception: FrontendException) { val errorCode = exception.errorCode stats.errors.withInternalCode(errorCode).increment() if (errorCode == FrontendExceptionInterface.Code.UNKNOWN_WEB.bxCode) { stats.unknownProjects.countDomain(event.request.serverName) } } } ```

**javax / jakarta** Ab Framework v3.0 müssen die `jakarta` anstatt der `javax` Klassen verwendet werden.

### Statische Ressourcen schützen Ein anderes Anwendungsgebiet für Request Interceptors ist das Schützen der statischen Ressourcen, die in der Verwaltung unter *Ressourcen* > *Vorlagen* > *statische Ressourcen* gepflegt werden. Hierfür wird einfach ein Request Interceptor für die zu schützenden Pfade / Dateien definiert und die gewünschten User-Checks durchgeführt. Simples Beispiel: ```kotlin registerRequestInterceptor("^/static/my-project/assets-for-vips/.*$", object : RequestInterceptor { override fun handlePre(event: RequestEvent) { val user = BxUser.findInstance(event.request) val vipsGroup = UserGroup.findGroup("196243C94D0") val allowed = user != null && ConnectionPool.withSystemConnectionDo { conn -> user.isInGroup(conn, vipsGroup) } if (!allowed) { event.response.status = HttpServletResponse.SC_UNAUTHORIZED // 401 event.preventDefault() } } }) ```

**Verfügbarkeit** Nur verfügbar für Systeme, die in Docker laufen oder speziell konfiguriert sind (`/static/` via Tomcat). Das ist standardmäßig ab Framework Version 2.9 der Fall.

# Static Content

**Verfügbarkeit** Ab Batix Application Framework Version 2.7.1 verfügbar.

Plugins können in ihre .zip Datei statische Ressourcen-Dateien wie HTML-Seiten, Bilder, Schriften oder JS-/CSS-Dateien integrieren. Diese müssen in einem Unterordner unterhalb des Projektordners namens `static` liegen. Falls im Plugin-Projektverzeichnis ein Ordner `static` existiert, wird dessen Inhalt automatisch in die ZIP übernommen. Es können auch komplette [Vue](https://vuejs.org/) Apps oder auch mit [VitePress](https://vitepress.dev/) erstellte Dokumentationen ausgeliefert werden. Dank Gradle landet sogar automatisch zur Build-Zeit die kompilierte Vue-App oder die erstellte VitePress-Seite in der .zip Datei. Siehe dazu auch den Guide [Vue App ausliefern](https://plugins.batix.help/guide/vue-app.html).

**INFO** Hier ist die Rede von `RequestHandler`n, obwohl es im vorherigen Kapitel immer `RequestInterceptor` hieß. Das hat historische Gründe - `RequestHandler` war der alte Name und zugunsten einfacherer Backwards-Compatibility wurde hier der Name nicht angepasst - es handelt sich aber intern trotzdem um `RequestInterceptor`s.

```kotlin fun registerRequestHandlerForStaticContent( pathPrefix: String, staticPath: String, fallback: String, guard: StaticContentHandler.Guard = null ) fun registerRequestHandlerForStaticContent( condition: RequestCondition, pathMapper: Function, staticPath: String, fallback: String, guard: StaticContentHandler.Guard = null ) ``` Die erste Methode eignet sich für einfache Fälle. `pathPrefix` ist der Anfang des Pfads, auf den reagiert werden soll - dies ist kein regulärer Ausdruck, sondern ein normaler String. Es wird dabei auf jede Domain reagiert. `staticPath` ist der Name des Ordners im `static` Ordner des Plugin-ZIPs. `fallback` ist ein optionaler Parameter, der eine Alternativ-Datei angibt, welche ausgeliefert wird, falls eine nicht-existierende Datei angefordert wird - bei SPAs ist dies meistens index.html. `guard` ist ein Callback, der das Functional Interface `StaticContentHandler.Guard` und damit die Methode `intercept` implementiert. Hier kann entschieden werden, ob die Ressource doch nicht (z. B. wegen fehlender Authorisierung) ausgeliefert werden soll (in diesem Fall sollte der Guard `true` zurückgeben). Hat man als `pathPrefix` beispielsweise /import-plugin/frontend/ und als `staticPath` den Ordner "import-frontend" definiert (und `fallback` mit `null` angegeben), dann würde ein Aufruf von domain.tld/import-plugin/frontend/import.html die Datei <ZIP>/static/import-frontend/import.html ausliefern, falls diese existiert. Ein Aufruf von domain.tld/import-plugin/frontend/ (entspricht also dem `pathprefix`) liefert die index.html Datei (<ZIP>/static/import-frontend/index.html) aus. Mit der zweiten Methode hat man dank einer `RequestCondition` mehr Kontrolle, unter welchen Pfaden die statischen Dateien ausgeliefert werden. Dafür muss man mittels `pathMapper` aber auch eine Funktion übergeben, die aus dem Request den entsprechenden Pfad zur statischen Datei extrahiert (da es ja kein festes Prefix gibt). Wird eine angefragte Datei nicht gefunden und es ist kein `fallback` angegeben (oder `fallback` wird auch nicht gefunden), wird eine Fehlerseite mit Status 404 erzeugt. Dateien werden mit passendem MIME-Type und Cache-Headern ausgeliefert. Der Aufruf ohne Dateiangabe (also z. B. domain.tld/import-plugin/frontend/) liefert die Datei index.html aus (falls diese existiert). Ein in beiden Fällen optionaler `guard` kann die `intercept`-Methode überschreiben und auf Request, Response sowie den Ressourcennamen reagieren um die Auslieferung ggf. zu unterbinden (`return true` heißt blockieren). ```kotlin fun interface Guard { fun intercept( request: HttpServletRequest, response: HttpServletResponse, resource: String ): Boolean } ``` ## Beispiel Es wird folgender Inhalt der Plugin-ZIP angenommen (Ausschnitt). ``` └── static └── import-frontend ├── css │ └── bootstrap.min.css ├── import.html ├── index.html └── js └── bootstrap.min.js ``` Der folgende Handler wird registriert. ```kotlin override fun load() { registerRequestHandlerForStaticContent( "/import-plugin/frontend/", // pathPrefix "import-frontend", // staticPath "index.html" // fallback ) } ``` Daraus ergeben sich folgende Request-zu-Datei Mappings.
RequestDatei
domain.tld/import-plugin/frontend/import.html<ZIP>/static/import-frontend/import.html
domain.tld/import-plugin/frontend/<ZIP>/static/import-frontend/index.html
domain.tld/import-plugin/frontend/existiert.nicht<ZIP>/static/import-frontend/index.html
Innerhalb der .html Dateien können die Scripts und Styles mittels relativem Pfad angesprochen werden. ``` ``` # Admin Page Für Backend-Benutzer können eigenständige Seiten innerhalb der Verwaltung zur Verfügung gestellt werden. Das entspricht den bisherigen "Plugin-Seiten" auf Projektebene, die allerdings direkt im Backend als normale Menüpunkte angelegt wurden. Admin Pages stehen in allen Projekten zur Verfügung und beziehen ihren Inhalt aus der ZIP-Datei des Plugins, siehe zu dieser Funktionsweise auch die [Static Content](https://batix.help/books/batix-plugins/page/static-content) Extension. ```kotlin fun registerAdminPage(info: AdminPageInfo) ``` `AdminPageInfo` besteht aus `id`, `title`, `staticPath`, `handler` und `guard`. `id` ist eine frei wählbare ID, die über alle Admin Pages eines Plugins hinweg eindeutig sein muss. Es ist kein Problem, wenn mehrere Plugins eine Admin Page mit derselben ID bereitstellen, da zum Ansprechen einer Admin Page auch die `id` des Plugins herangezogen wird. `title` ist der Titel, wie er im Verwaltungsmenü auftaucht. `staticPath` ist der Unterordner im `static` Ordner des Plugin-ZIPs, aus dem die Dateien ausgeliefert werden. Der optionale Wert `handler` ist ein `RequestHandler`, der aufgerufen wird, falls eine Datei angefordert wird, die nicht existiert. Hiermit können die Actions der bisherigen Plugin-Seiten nachgebildet werden. Der optionale Wert `guard` ist ein `StaticContentHandler.Guard`, wie er auch bei [Static Content](https://batix.help/books/batix-plugins/page/static-content) verwendet wird. Falls definiert, wird die `intercept` Methode von `guard` in folgenden Fällen mit diesen Werten aufgerufen: - `resource=""` - um zu prüfen, ob die Admin Page dem Backend-Benutzer in der Navigation angezeigt werden soll oder nicht. Wird `true` zurückgegeben, taucht die Admin Page in der Navigation nicht auf. - `resource="index.html"`, `resource="assets/style.css"`, `resource="dynamic/do-something-action"` - um zu prüfen, ob der Request auf diese Ressource erlaubt werden soll oder nicht. Wird `true` zurückgegeben, erfolgt die Auslieferung der Ressource nicht, ebenfalls wird weder `handler` aufgerufen noch eine eigene Fehlermeldung generiert. ## Beispiel[​](https://plugins.batix.help/extensions/admin-page.html#beispiel) In der Pluginhauptklasse wird die Admin Page registriert. In der Plugin-ZIP müssen die Dateien dementsprechend im Ordner static/import-ma/ liegen. ```kotlin override fun load() { registerAdminPage( AdminPageInfo( "import-mitarbeiter", // id "Mitarbeiterimport", // title "import-ma", // staticPath null, // handler null // guard ) ) } ``` Im Backend stellt sich die Admin Page im Menü wie folgt dar. [![admin-page-menu.png](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/R9pFjVLAfk1fXIb2-admin-page-menu-png.png)](https://batix.help/uploads/images/gallery/2025-05/scaled-1680-/R9pFjVLAfk1fXIb2-admin-page-menu-png.png) # WebSocket
Auch WebSockets können von Plugins ganz einfach genutzt werden. Dabei können sogar erweiterte Funktionalitäten wie Subprotokolle verwendet oder der Handshake modifiziert werden. ```kotlin fun registerWebSocket(socketId: String, handler: WebSocketHandler) ``` `socketId` ist eine frei wählbare ID, die über alle WebSockets eines Plugins hinweg eindeutig sein muss. Es ist kein Problem, wenn mehrere Plugins einen WebSocket mit derselben ID bereitstellen, da zum Ansprechen eines WebSockets auch die `id` des Plugins herangezogen wird. Der WebSocket wird dann unter einem Pfad bereitgestellt, der nach folgendem Schema aufgebaut ist. ``` /.well-known/bx-websockets// ``` Als `handler` übergibt man eine Instanz, die `com.batix.plugins.WebSocketHandler` implementiert.

**Thread-Safety** Dieselbe Instanz wird für alle Requests verwendet, muss also thread-safe implementiert werden.

Im Handler können eine oder mehrere der folgenden Methoden überschrieben werden. Die Methodennamen sind selbsterklärend. ```kotlin fun onOpen(client: WebSocketContext) fun onClose(client: WebSocketContext, closeReason: CloseReason) fun onTextMessage(client: WebSocketContext, message: String) fun onBinaryMessage(client: WebSocketContext, data: ByteArray) fun onError(client: WebSocketContext, throwable: Throwable) // ab Framework v2.7.8 ```
Mittels `client` kann der Gegenüber identifiziert werden. In `WebSocketContext` stecken die `httpSession` (falls eine beim Öffnen des WebSockets vorhanden war) sowie die `webSocketSession` mit der z. B. Nachrichten geschickt oder der Socket geschlossen werden kann. Außerdem gibt es noch die Methode `getAllClients()` mit der alle aktuell zu diesem WebSocket Handler verbundenen Clients aufgelistet werden (das schließt auch `client` mit ein). Der häufigste Fall ist eine Textnachricht zu versenden, dies kann wie folgt erledigt werden. ```kotlin client.webSocketSession.basicRemote.sendText("Text...") ``` Eine Verbindung kann mittels `close()` geschlossen werden, dabei ist auch die Angabe einer `CloseReason` möglich. ```kotlin client.webSocketSession.close(CloseReason( CloseReason.CloseCodes.NORMAL_CLOSURE, "Verbindung beendet." )) ``` ## Erweiterte Funktionalitäten[​](https://plugins.batix.help/extensions/websocket.html#erweiterte-funktionalitaten) Für diese Funktionalitäten muss der WebSocket schon beim Start des Frameworks initialisiert werden. Dafür ist es nötig die entsprechenden Informationen in der `plugin.yaml` Datei zu hinterlegen und das Plugin beim Systemstart zu laden. Dazu wird in `plugin.yaml` ein neuer Hauptkey `configuredWebSockets` ergänzt. ```yaml configuredWebSockets: advanced-socket: subprotocols: - proto1 - proto2 configurator: com.company.plugin.MySocketConfigurator ``` Dies ist eine Map, wobei der Key (im Beispiel hier `advanced-socket`) der `socketId` entspricht. Diese muss dann durch das Plugin noch registriert werden (wie normale WebSockets). Dem Beispiel folgend, müsste also noch folgender Aufruf erfolgen. ```kotlin registerWebSocket("advanced-socket", SomeHandler()) ``` `subprotocols` und `configurator` können beide zusammen oder auch einzeln pro WebSocket verwendet werden.

**Nur nach Framework-Neustart verfügbar** Diese speziellen WebSockets sind nur nach einem Neustart des Frameworks, und nur wenn das Plugin zu diesem Zeitpunkt automatisch geladen wird, verfügbar. Damit Änderungen an `subprotocols` und eine neue `configurator` Instanz wirksam werden, muss das Framework neugestartet werden.

### Subprotokolle[​](https://plugins.batix.help/extensions/websocket.html#subprotokolle) Falls der Server mehrere Subprotokolle unterstützt, können diese unter `subprotocols` aufgelistet werden (Liste von Strings). Schickt ein Client seinerseits auch Subprotokolle mit, wird das erste verwendet, welches auch der Server unterstützt. Diese Auswahl kann optional durch einen Configurator angepasst werden (s. u.). Das ausgehandelte Subprotokoll kann folgendermaßen ausgelesen werden. Wurde sich auf kein Subprotokoll geeinigt (oder gab es keine), ist dieser Wert leer. ```kotlin client.webSocketSession.negotiatedSubprotocol ``` ### Configurator[​](https://plugins.batix.help/extensions/websocket.html#configurator) Weitere Details können durch einen sogenannten Configurator angepasst werden. Dies ist eine von `jakarta.websocket.server.ServerEndpointConfig.Configurator` abgeleitete Klasse.

**javax / jakarta** Ab Framework v3.0 müssen die `jakarta` anstatt der `javax` Klassen verwendet werden.

Der vollqualifizierte Name der Klasse (d. h. inklusive Package) ist als `configurator` des entsprechenden WebSockets in der `plugin.yaml` anzugeben. Hier gibt es verschiedene Methoden, die überschrieben werden können. Es folgt eine Auswahl. ```kotlin fun getNegotiatedSubprotocol(supported: List, requested: List): String ``` Hiermit kann die Auswahl des Subprotokolls getroffen werden. Es ist ein String zurückzugeben, der sowohl in `supported` (Liste der Subprotokolle des **Servers**), als auch in `requested` (Liste der Subprotokolle des **Clients**) vorkommt. Ist kein Subprotokoll akzeptabel, muss ein Leerstring zurückgegeben werden. ```kotlin fun checkOrigin(originHeaderValue: String): Boolean ``` Mit dieser Methode kann der Origin-Header des Clients überprüft werden, falls für diesen nur bestimmte Werte zugelassen sein sollen. Der Rückgabewert ist, ob der Check erfolgreich war. Diesen Header schicken ziemlich alle Browser mit, andere Clients aber ggf. nicht (können ihn auch fälschen). ```kotlin fun modifyHandshake( sec: ServerEndpointConfig, request: HandshakeRequest, response: HandshakeResponse ) ``` Hierdurch kann die HTTP-Response des Verbindungsaufbaus angepasst werden. Subprotokolle und der Origin-Check sind an dieser Stelle schon durchlaufen wurden. ## Beispiel[​](https://plugins.batix.help/extensions/websocket.html#beispiel) Das Beispiel implementiert den simpelst-möglichen Broadcast-WebSocket, d. h. eine eingehende Nachricht wird an alle verbundenen Clients geschickt (inkl. dem Sender). ```kotlin override fun load() { registerWebSocket("broadcast", Broadcaster()) } ``` Lautet die Plugin-ID `com.batix.website:import-mitarbeiter`, so ist der WebSocket dann unter folgender URL erreichbar. ``` wss://domain.tld/.well-known/bx-websockets/com.batix.website:import-mitarbeiter/broadcast ```

**ws/wss und Domain auslesen** Um in JavaScript das passende Protokoll (`ws` oder `wss`) und die Domain herauszufinden, kann folgendes Snippet verwendet werden (Standardports vorausgesetzt).

```javascript const wsPath = "/.well-known/bx-websockets//"; const protocolPrefix = (window.location.protocol === 'https:') ? 'wss:' : 'ws:'; const socket = new WebSocket(protocolPrefix + "//" + location.host + wsPath); ```

Grundsätzlich empfiehlt sich eine verschlüsselte HTTPS-Verbindung, damit auch die WebSocket-Verbindung verschlüsselt ist.

Im Handler ist lediglich die `onTextMessage` Methode zu überschreiben. ```kotlin import com.batix.plugins.WebSocketContext import com.batix.plugins.WebSocketHandler class Broadcaster : WebSocketHandler { override fun onTextMessage(client: WebSocketContext, message: String) { client.allClients.forEach { it.webSocketSession.basicRemote.sendText(message) } } } ```
# Event Listener Plugins können sich beim Framework für Events registrieren und selbst Events auslösen. Ein Event besteht immer aus einem Namen sowie zugehörigen Daten. ## Name[​](https://plugins.batix.help/extensions/event-listener.html#name) Der Name muss gegenüber anderen Events unique sein. Anhand dessen erfolgt das Routing der Events an die interessierten Event-Listener. Es sollte daher ein kontext-spezifischer Präfix gewählt werden, ähnlich den Java-Packages. Das Framework selbst benutzt Namen wie `user.update.backend` und `login.backend.fail`. Für eigene Events wird das Schema `my-company.my-project.my-event` empfohlen. ## Daten[​](https://plugins.batix.help/extensions/event-listener.html#daten) Jedes ausgelöste Event enthält spezielle, relevante Daten. Diese werden in einer Instanz einer Klasse transportiert, die von `com.batix.event.EventData` abgeleitet ist. Diese Basisklasse bringt bereits Felder für `request`, `response` und `application` mit. Die abgeleitete Klasse kann beliebige Felder und Methoden hinzufügen. Die Methode `getEventName` muss in jedem Fall implementiert werden: ```kotlin class MyEventData : EventData() { override fun getEventName(): String { return "example.tool.test-event" } } ``` Der Rückgabewert von `getEventName` ist der Name des ausgelösten Events. Da es möglich ist, dass sich derselbe Event-Listener für unterschiedliche Events (mit kompatiblen Daten) registriert, kann er hiermit unterschieden, welches Event genau ausgelöst wurde.

**TIP** Werden keine zusätzlichen Daten benötigt, kann die Klasse `com.batix.event.StandardEventData` benutzt werden. Dieser ist dann nur der Event-Name zu übergeben.

## `EventManager`[​](https://plugins.batix.help/extensions/event-listener.html#eventmanager) Der `EventManager` ist das Herzstück der Event-Maschinerie. Mittels seiner Methode `fireEvent` können Events ausgelöst werden.

**Achtung** Die anderen Methoden wie `on` und `off` sollten von Plugins nicht direkt benutzt werden, da es sonst ggf. zu Memory-Leaks kommen kann.

Um ein Event auszulösen, reicht die Übergabe der Daten: ```kotlin val data = MyEventData() EventManager.fireEvent(data) ``` Es gibt auch Überladungen von `fireEvent`, die noch weitere Daten wie z. B. `request` und `response` entgegennehmen. Sind diese verfügbar, kann man sie mit übergeben, um im Event-Listener darauf zuzugreifen. Sie werden dann automatisch in der `EventData` Grundklasse der Instanz vermerkt. ## `EventListener`[​](https://plugins.batix.help/extensions/event-listener.html#eventlistener) Um Events zu empfangen, wird eine Instanz von `com.batix.event.EventListener` benötigt. Dazu definiert man zunächst eine Klasse, welche die entsprechenden Daten verarbeiten kann: ```kotlin class MyEventListener : EventListener() { override fun syncCallback( eventName: String, info: MyEventData, application: ServletContext?, request: HttpServletRequest?, response: HttpServletResponse?, ): MyEventData? { // ... return null } } ``` Wie der Name `syncCallback` vermuten lässt, wird diese Methode bei der Abarbeitung des Events synchron aufgerufen. Es wird also gewartet, bis `syncCallback` fertig ist, bevor das Event dem ggf. nächsten Listener übergeben wird. Deshalb sollten in dieser Methode auch keine Sachen ablaufen, die längere Zeit benötigen. Um dennoch Callbacks abzuarbeiten, die länger dauern, unterstützt der `EventManager` auch asynchrone Callbacks. Über den Rückgabewert von `syncCallback` wird gesteuert, ob ein späterer, asynchroner Aufruf gewünscht ist, oder nicht. Wird `null` zurück gegeben, erfolgt kein späterer Aufruf. Ansonsten gibt man die erhaltenen Daten zurück und ein Worker ruft so bald wie möglich das asynchrone Callback auf. Man kann auch beides kombinieren: z. B. eine einfache Verarbeitung wie Logging synchron und das Wegspeichern von Daten asynchron. Um Events asynchron verarbeiten zu können, muss nebst `syncCallback` noch die Methode `asyncCallback` implementiert werden: ```kotlin class MyEventListener : EventListener() { override fun syncCallback( eventName: String, info: MyEventData, application: ServletContext?, request: HttpServletRequest?, response: HttpServletResponse?, ): MyEventData? { if (canBeDoneQuick) { doStuff() return null } return info } override fun asyncCallback(state: MyEventData) { // ... } } ``` Je nachdem, welche Daten bei `fireEvent` übergeben wurden, sind `application`, `request` und `response` sowohl als Parameter als auch in den Event-Daten verfügbar, oder nicht.

Zu beachten ist, dass in `asyncCallback` der Request höchstwahrscheinlich schon vorbei ist. Daher müssen hier Zugriffe auf `request` und `response` vermieden werden.

## `registerForEvent`[​](https://plugins.batix.help/extensions/event-listener.html#registerforevent) Ein Plugin kann sich mittels `registerForEvent(eventName, listener)` für ein Event anmelden. Dies kann z. B. in seiner `load()` Methode geschehen. Wie bei den anderen Extensions auch, kann das Plugin zu seiner Laufzeit beliebig Event-Listener an- und abmelden. Ein bestimmter Listener kann mittels `unregisterForEvent(eventName, listener)` deregistriert werden. Alle Listener des Plugins für ein bestimmtes Event können mit `unregisterForEvent(eventName)` abgemeldet werden. Um alle Listener des Plugins abzumelden, genügt der Aufruf `unregisterForAllEvents()` (dies wird automatisch auch beim Entladen des Plugins getan, man muss seine Listener also nicht manuell entfernen). ```kotlin class MyPlugin : Plugin() { override fun load() { registerForEvent("example.tool.test-event", MyEventListener()) } } ```