Aufbau der plugin.xml

Die Datei plugin.xml ist notwendiger Bestandteil eines jeden Jameica-Plugins. Sie wird auch Manifest genannt und enthält alle relevanten Meta-Informationen, die Jameica zum Initialisieren des Plugins benötigt. In ihr sind z.Bsp. die zu startenden Services sowie die Menupunkte und Navigationselemente definiert.

Der Aufbau dieser Datei ist stark an das Format der „plugin.xml“ von Eclipse-Plugins angelehnt. Unter http://www.willuhn.de/schema/jameica-plugin-1.0.xsd befindet eine XML-Schema-Datei, welche eine technische Beschreibung des XML-Formats liefert. Wird diese Schema-Datei wie im folgenden Beispiel mittels „xsi:noNamespaceSchemaLocation“ referenziert, kann die Syntax der plugin.xml (abhängig vom verwendeten XML-Editor) sofort geprüft werden. Ggf. steht dann auch eine Text-Vervollständigung zur Verfügung.

Beispiel Hibiscus:

<?xml version="1.0" encoding="ISO-8859-1"?>
 
<plugin name="hibiscus" version="1.7" class="de.willuhn.jameica.hbci.HBCI" shared="true"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.willuhn.de/schema/jameica-plugin-1.3.xsd">
 
 
  <description>HBCI-Onlinebanking-Plugin für Jameica</description>
  <homepage>http://www.willuhn.de/projects/hibiscus</homepage>
  <license>GPL - http://www.gnu.org/copyleft/gpl.html</license>
 
  <requires jameica="1.7+">
    <import plugin="Name des benoetigten Plugins"/>
    <import plugin="Name des benoetigten Plugins2" version="1.2-"/>
    <import plugin="Name des benoetigten Plugins3" version="2.0" required="false"/>
    ...
  </requires>
 
  <classfinder>
    <include>hibiscus\.jar</include>
    <include>hbci_passport_.*\.jar</include>
    <include>.*\.class</include>
  </classfinder>
 
  <menu>
    <item id="hibiscus.menu" name="Hibiscus">
      <item id="hibiscus.menu.settings" name="Einstellungen"
            action="de.willuhn.jameica.hbci.gui.action.Settings" />
      <item name="-" />
      [...]
    </item>
  </menu>
 
  <navigation>
    <item id="hibiscus.navi" name="Hibiscus"
          icon-close="folder.gif"
          icon-open="folderopen.gif">
      <item id="hibiscus.navi.accounts" name="Konten"
            icon-close="page.gif"
            icon-open="page.gif"
            action="de.willuhn.jameica.hbci.gui.action.KontoList" />
      [...]
      <item id="hibiscus.navi.transfer" name="Transfer"
            icon-close="folder.gif"
            icon-open="folderopen.gif">
        <item id="hibiscus.navi.transfer.ueb" name="Einzelüberweisungen"
              icon-close="page.gif"
              icon-open="page.gif"
              action="de.willuhn.jameica.hbci.gui.action.UeberweisungList" />
        <item id="hibiscus.navi.transfer.sammelueb" name="Sammelüberweisungen"
              icon-close="page.gif"
              icon-open="page.gif"
              action="de.willuhn.jameica.hbci.gui.action.DauerauftragList" />
        [...]
      </item>
      [...]
    </item>
  </navigation>
 
  <services>
    <service name="database" depends="" autostart="true"
             class="de.willuhn.jameica.hbci.rmi.HBCIDBService" />
  </services>
 
  <messaging>
    <consumer queue="mein.queue.name" class="implementierung.eines.MessageConsumer" />
    <message queue="jameica.scripting.add">
      <![CDATA[
        ${manifest.pluginDir}/meinscript.js
      ]]>
    </message>
  </messaging>
</plugin>

Die Sektionen im Einzelnen

<plugin name="hibiscus" version="1.7" class="de.willuhn.jameica.hbci.HBCI" shared="true">
name Legt den Namen des Plugins fest. Dieser muss in Jameica eindeutig sein. Er sollte keine Leerzeichen enthalten
version Versionsnummer bestehend aus Major- und Minor-Number.
class „Plugin-Activator“. Die hier angegebene Klasse muss von *de.willuhn.jameica.plugin.AbstractPlugin* abgeleitet sein. Bei der Initialisierung des Plugins wird eine Instanz erzeugt und die Methode *init()* bzw. ggg. *update()* oder *install()* aufgerufen
shared Legt fest, ob die Klassen dieses Plugins auch für andere Plugins sichtbar sein sollen (Default=true). Wert kann auf „false“ gesetzt werden, wenn das Plugin beispielsweise JAR-Bibliotheken mitbringt, welche mit anderen Plugins kollidieren.

About

  <description>HBCI-Onlinebanking-Plugin für Jameica</description>
  <homepage>http://www.willuhn.de/projects/hibiscus</homepage>
  <license>GPL - http://www.gnu.org/copyleft/gpl.html</license>
description Optionale Beschreibung des Plugins. Wird z.Bsp. unter Datei→Einstellungen→Installierte Plugins angezeigt
homepage Homepage des Plugins/Herstellers
license Bezeichnung der Lizenz des Plugins

Dependencies

Der Pluginloader löst Abhängigkeiten zwischen Plugins selbst auf und lädt die Plugins in der gewünschten Reihenfolge. Existiert eine der Abhängigkeiten nicht oder kam es dort bei der Initialisierung zu einem Fehler, wird auch das betreffende Plugin nicht geladen um Folgefehler zu vermeiden.

  <requires jameica="1.7+">
    <import plugin="Name des benoetigten Plugins"/>
    <import plugin="Name des benoetigten Plugins2" version="1.2-"/>
    <import plugin="Name des benoetigten Plugins3" version="2.0" required="false"/>
    ...
  </requires>
requires Container für die Liste der Abhängigkeiten
jameica Versionsnummer der benötigten Jameica-Version (optional)
import Ein benötigtes Plugin
plugin Name des benötigten Plugins. Das ist der Wert des Attributes *<plugin name=…„* des benötigten Plugins
version Versionsnummer der benötigten Plugin-Version (optional)
required Legt fest, ob die Abhängigkeit erfüllt sein muss oder nicht (default=„true“). Ist eine Abhängigkeit mit „required=false“ als optional markiert, kann das Plugin auch dann gestartet werden, wenn die Abhängigkeit nicht erfüllt ist. Ist das abhängige Plugin jedoch installiert, dann stellt Jameica sicher, dass es vor dem Plugin geladen wird.

Versionsnummern können in den folgenden Formaten angegeben werden:

Beispiel Bemerkung
2.0 Plugin/Jameica wird exakt in dieser Version benötigt
1.2- Plugin/Jameica wird in einer Version benötigt, die älter als 1.2 ist
1.7+ Plugin/Jameica wird in einer Version benötigt, die neuer als 1.7 ist

Classfinder

Ein elementares Feature von Jameica ist die Möglichkeit, anhand eines vorgegebenen Interfaces nach konkreten Implementierungen suchen zu können. Ein Plugin kann beispielsweise ein Interface *Printer* vorgeben. Existieren nun in irgendeinem Plugin oder in Jameica Implementierungen dieses Interfaces, werden sie gefunden. Insofern sie dem Classfinder bekannt gemacht wurden:

  <classfinder>
    <include>hibiscus\.jar</include>
    <include>hbci_passport_.*\.jar</include>
    <include>.*\.class</include>
  </classfinder>
include Regulärer Ausdruck für einen Dateinamen/Pfad. Alle dort gefundenen Klassen werden automatisch im Classfinder registriert und können anschliessend durchsucht werden

Definiert die im Jameica-Menu (unterhalb des Menupunktes „Plugins“) anzuzeigenden Elemente.

  <menu>
    <item id="hibiscus.menu" name="Hibiscus">
      <item id="hibiscus.menu.settings" name="Einstellungen" action="de.willuhn.jameica.hbci.gui.action.Settings" enabled="true" />
      <item name="-" />
      [...]
    </item>
  </menu>
menu Container für die Menuelemente
item Ein einzelnes Menuelement. Können beliebige verschachtelt werden, um Untermenus zu erzeugen
id Eindeutige ID für diesen Menupunkt für eventuelle Erweiterung mittels Extension-System
name Bezeichnung des Menuelementes
action Name der Java-Klasse, die beim Klick auf das Menuelement ausgelöst wird. Muss das Interface „*de.willuhn.jameica.gui.Action* implementieren
enabled Legt fest, ob das Menuelement aktiv oder inaktiv (grau) sein soll. Default: true

Definiert die im Navigationsbaum (links in Jameica) anzuzeigenden Elemente. Der Aufbau ist analog zu *<menu>*.

  <navigation>
    [...]
    <item id="hibiscus.navi.accounts" name="Konten"
            icon-close="page.gif"
            icon-open="page.gif"
            action="de.willuhn.jameica.hbci.gui.action.KontoList"
            expanded="true"
            enabled="true" />
    </item>
  </navigation>
navigation Container für die Navigations-Elemente
item Ein einzelnes Menuelement. Können beliebige verschachtelt werden, um Untermenus zu erzeugen
id Eindeutige ID für diesen Menupunkt für eventuelle Erweiterung mittels Extension-System
name Bezeichnung des Menuelementes
icon-close Optionale Angabe eines Icons, welches angezeigt wird, wenn der Knoten geschlossen ist
icon-open Optionale Angabe eines Icons, welches angezeigt wird, wenn der Knoten geöffnet ist
action Name der Java-Klasse, die beim Klick auf das Element ausgelöst wird. Muss das Interface „*de.willuhn.jameica.gui.Action* implementieren
expanded Optionales Attribut, welches festlegt, ob das Element auf- oder zugeklappt sein soll. Standardmäßig ist es aufgeklappt.
enabled Legt fest, ob das Navigations-Element aktiv oder inaktiv (grau) sein soll. Default: true

Services

Services in RMI-taugliche Java-Objekte, die typischerweise Infrastruktur-Dienste anbieten. Das kann die Verbindung zu einer Datenbank sein, ein Druck- oder Mail-Service oder ähnliches. Sie müssen das Interface *de.willuhn.datasource.Service* implementieren und besitzen somit u.a. eine *start()* und *stop()* Funktion. Ist der Autostart des Dienstes aktiviert, wird die *start()*-Methode beim Initialisieren des Plugins automatisch durch Jameica ausgeführt. Beim Beenden von Jameica werden alle Dienste in umgekehrter Reihenfolge durch Aufruf der Funktion *stop()* beendet.

Dienste können Abhängkeiten untereinander besitzen. Somit ist sichergestellt, dass Dienst B bereits existiert, wenn Dienst A startet.

Da Jameica-Services RMI-tauglich sind, können sie auch von eineren Jameica-Installation auf einem anderen Rechner genutzt werden. Hierzu muss die „dienstanbietende“ Jameica-Installation im Server-Modus laufen und der Hostname des Servers auf der Client-Installation definiert sein.

  <services>
    <service name="database" depends="" autostart="true"
             class="de.willuhn.jameica.hbci.rmi.HBCIDBService" />
    <service name="foo" depends="database" autostart="true"
             class="Klassenname" share="false" />
  </services>
services Container für die Liste der Dienste
service Ein einzelner Service
name Eindeutiger Name innerhalb des Plugins. Sollte keine Leerzeichen enthalten
depends Optionale kommaseparierte Liste von Dienstnamen, die zum Start benötigt werden
autostart Legt fest, ob Jameica den Dienst automatisch starten soll
class Name der Java-Klasse oder eines Interfaces, welches *de.willuhn.datasource.Service* implementiert. Ist die zugehörige Implementierung dem Classfinder bekannt, wird sie automatisch gefunden
share Legt fest, ob der Dienst im Server-Betrieb via RMI erreichbar sein soll

Messaging

Das Messaging ist eine elegante Möglichkeit, Plugins innerhalb von Jameica miteinander kommunizieren zu lassen. Ein „Message-Consumer“ ist eine Klasse, die das Interface *de.willuhn.jameica.messaging.MessageConsumer* implementiert und auf einer Queue mit frei gewähltem Namen registriert werden kann. Anschließend können (sowohl das eigene Plugin als auch andere) Messages an diese Queue gesendet werden, die der Message-Consumer empfängt. Ein Message-Consumer kann sowohl mittels Java-Code für eine Queue registriert werden als auch direkt im Manifest. Im Beispiel wird eine Klasse mit dem Namen „implementierung.eines.MessageConsumer“ auf die Queue „mein.queue.name“ registriert. Außerdem können in diesem Abschnitt des Manifests auch direkt Messages versendet werden. Das ist z.Bsp. für Plugins sinnvoll, die keinen eigenen Java-Code mitbringen aber dennoch eine Message versenden wollen. Die Message wird immer beim Start von Jameica versendet. Der Content des XML-Elements „message“ wird als „Payload“ gesendet. Die Variable „${manifest.pluginDir}“ wird hierbei gegen den Pfad ersetzt, in dem das Plugin installiert ist.

  <messaging>
    <consumer queue="mein.queue.name" class="implementierung.eines.MessageConsumer" />
    <message queue="jameica.scripting.add">
      <![CDATA[
        ${manifest.pluginDir}/meinscript.js
      ]]>
    </message>
  </messaging>