CIB webdesk technischer Leitfaden

6. Konfiguration CIB webdesk

6.1. Funktionsweise der Konfiguration

Allgemein
Das Plugin-Konzept von CIB webdesk
Einsteuern von Konfigurationseigenschaften mit Hilfe eines Plugins

Allgemein

CIB webdesk wird mit Hilfe einer beim Start der Webapplikation eingelesenen Properties-Datei konfiguriert, welche im ausgelieferten WAR-Archiv enthalten ist.

Die CIB webdesk Properties Datei kann an folgenden Orten abgelegt werden

Im Classpath
Im „user.home“ Verzeichnis
In einem beliebigen Verzeichnis, das über die Tomcat Aufrufparameter (z.B. in /etc/default/tomcat8 oder in CATALINA_HOME/bin/setenv.sh) „-DWBD_CONFIG_DIR“ gesetzt werden kann

CIB webdesk verfügt über einen Plugin-Mechanismus, der es erlaubt, die Applikation mit einer eigenen Komponente zu erweitern, die sich in den Einlesevorgang der Konfigurationsdatei einklinkt und beliebige Konfigurationsschlüssel übersteuert. Alternativ kann die im WAR enthaltene Konfigurationsdatei vor dem Deployment manuell oder per Skript angepasst werden.

Das Plugin-Konzept von CIB webdesk

Grundsätzlich werden dafür nur Standardmechanismen für Web-Applikationen genutzt.

Intern verwendet CIB webdesk das Spring Framework, das auch für die Implementierung des Plugin-Mechanismus verwendet wurde. Ein Plugin für CIB webdesk besteht daher mindestens aus einer Spring Konfigurationsdatei, in welcher Beans definiert werden, die vom Spring Framework beim Startup der Applikation automatisch erzeugt werden. In der Regel beinhaltet ein Plugin außerdem eigene Klassen, die in einem JAR-Archiv bereitgestellt werden können.

Die Konfigurationsdatei des Plugins ist eine XML-Datei, deren Dateiname auf „-config.xml“ enden muss. Sie muss zudem in das Verzeichnis WEB-INF/plugins unterhalb des Deployment-Verzeichnisses von CIB webdesk kopiert werden. In dieser Datei werden Beans definiert, die dann bei Initialisierung der Webapplikation vom Spring Framework instanziiert werden. Ein Beispiel für eine einfache Bean-Definition kann dem folgenden Listing entnommen werden.

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
            http://www.springframework.org/schema/context
         http://www.springframework.org/schema/context/spring-context-2.5.xsd">
       <bean class="com.example.MyBeanClass" scope="singleton">
            <property name="foo" value="bar" />
      </bean>
</beans>

Diese Konfiguration erzeugt beim Hochfahren des Spring Application Context, was bei der Initialisierung von CIB webdesk geschieht, ein Objekt vom Typ com.example.MyBeanClass und setzt die Property „foo“ dieser Bean auf den Wert „bar“. Der Wert „singleton“ des scope-Attributs legt dabei fest, dass die Bean nur einmal im Application Context abgelegt wird und alle Anfragen auf die Bean dieselbe Instanz zurückliefern.

Eine umfassende Erläuterung würde den Rahmen dieses Dokuments sprengen. Es sei deshalb auf die Dokumentation des Spring Frameworks verwiesen.

Wenn CIB webdesk Plugin-spezifische Klassen beinhalten soll, müssen diese in einem JAR-Archiv im Verzeichnis WEB-INF/lib unterhalb des Deployment-Verzeichnisses von CIB webdesk zur Verfügung gestellt werden. Um das Beispiel aus dem obigen Listing aufzugreifen, müsste hier also ein JAR-Archiv bereitgestellt werden, welches (mindestens) das Paket com.example und darin die Klasse MyBeanClass enthält.

Wichtig: Achten Sie darauf, dass die in der XML-Konfiguration definierten Properties Ihrer Beans korrekt geschrieben und öffentlich (public) sichtbar sind. Wenn die Konfiguration fehlerhaft ist, kann CIB webdesk nicht ordnungsgemäß gestartet werden.

Einsteuern von Konfigurationseigenschaften mit Hilfe eines Plugins

Ein Plugin zur Einsteuerung von externen Konfigurationsparametern in CIB webdesk muss eine Bean im Singleton-Scope ablegen, die das Interface de.cib.webdesk.configuration.application.ExternalConfigPlaceholderResolver implementiert. Dieses Interface definiert eine einzige Methode namens resolvePlaceholder, die einen Wert für einen als Parameter übergebenen Schlüssel zurückliefert. So kann ein Plugin entwickelt werden, das z.B. Werte aus einem externen Web Service oder einer KonfigurationsDatenbank zurückliefert.

Wenn CIB webdesk auf seine Konfiguration zugreift und ein solches Konfigurationsplugin vorhanden ist, ruft die Anwendung zunächst die resolvePlaceholder-Methode des Plugins. Erst wenn diese keinen Wert (d.h. null) zurückliefert, wertet CIB webdesk den Wert aus seiner internen Konfigurationsdatei aus. So können existierende Werte für Parameter in der im WAR enthaltenen Konfiguration mit externen Werten überladen werden.

Die verfügbaren Konfigurationsparameter, die auf diese Weise externalisiert werden können, werden im Abschnitt Konfigurationsparameter beschrieben. Alle in diesem Abschnitt als erforderlich gekennzeichneten Parameter müssen für den erfolgreichen Betrieb von CIB webdesk zwingend über das kundenspezifische Konfigurationsplugin (oder direkt in der enthaltenen Konfigurationsdatei) gesetzt werden.