Module.xml und web.xml

Die Datei module.xml enthält die Definition des Treiber-Moduls und muss nach dem folgenden Beispiel aufgebaut sein. Das Grundgerüst ist dabei immer gleich, einige Tags und Parameter variieren je nach eingesetzter Datenbank und -version.

Das folgende Beispiel stellt exemplarisch den Aufbau einer module.xml für eine PostgreSQL 9.3-Datenbank dar:

<module>
   <name>JDBC_PostgreSQL_9_3</name>
   <displayname>Database Driver PostgreSQL 9.3</displayname> 
    <version>9.3.1102</version>
   <description>JDBC 4.1 driver for PostgreSQL 9.3 databases</description>
   <vendor>PostgreSQL Global Development Group</vendor>

   <resources>
      <resource scope="module"> lib/postgresql-9.3-1102.jdbc41.jar</resource>
   </resources>

   <components>
            <web-app>
               <name>WebApp_PostgreSQL_9_3</name>
               <displayname>WebApp PostgreSQL 9.3</displayname>                
                <description>Provides the JDBC Driver in a web application.
                </description>
               <web-xml>web.xml</web-xml>
               <web-resources>
                  <resource scope="module"
                    name="postgresql"
                    version="9.3.1102"
                    minVersion="9.3.1"
                    maxVersion="9.3.9999">lib/postgresql-9.3-102.jdbc41.jar
                  </resource>
               </web-resources>
            </web-app>
   </components>

   <configuration>           
        <DRIVER>org.postgresql.Driver</DRIVER>
        <layerclass>de.espirit.or.impl.postgres.PostgreSQLLayer</layerclass>
   </configuration>

</module>

Das Modul ist zweigeteilt: ein Teil definiert die Ressourcen für den FirstSpirit-Server, der andere für Webanwendungen (innerhalb des <web-app>-Tags). Dieser JDBC-Treiber kann somit im FirstSpirit-Server und in Webanwendungen genutzt werden. Wird der Treiber nur für den Server benötigt, kann die <web-app>-Definition entfallen.

Für den Einsatz der FirstSpirit-Webapplikationen wird eine Servlet-Engine benötigt, die die Servlet API in der Version 3.0 implementiert

<name>

Über dieses Tag muss ein eindeutiger, technischer Name für die Komponenten vergeben werden. Dabei dürfen nur Groß- bzw. Kleinbuchstaben (A-Z, a-z) und Zahlen (0-9) verwendet werden. Der Name wird beim Installieren des Moduls validiert. Module, die dieser Konvention nicht entsprechen, können nicht installiert werden.                     
Der technische Name wird beispielsweise zur Anzeige in der FirstSpirit Projekt- und Serverkonfiguration (sofern kein Anzeigename für das Modul definiert wurde), zur Überprüfung des Moduls bei der Aktualisierung und der Installation und zum Anlegen von Dateien und Ordnern auf der Festplatte verwendet. Der für die Server-Komponente vergebene Name muss auch in der Datenbank-Layer-Konfiguration angegeben werden (siehe Datenbank-Layer-Konfiguration).

<displayname>

Über dieses Tag kann ein optionaler Anzeigename für das Modul vergeben werden. Sofern ein Anzeigename definiert ist, wird dieser in allen FirstSpirit-Oberflächen angezeigt, beispielsweise in der Modul-Übersicht des FirstSpirit-Servers (siehe Abbildung auf der Seite Installation des JDBC-Treiber-Moduls). Der für die Webanwendungs-Komponente vergebene Anzeigename wird auch in den Projekt-Eigenschaften, Bereich „Web-Komponenten“ verwendet (siehe Abbildung auf der Seite Bei Verwendung in Webanwendungen). Das Pflicht-Attribut <name> wird weiterhin als eindeutiger, technischer Name verwendet. Ist kein Anzeigename definiert, wird der technische Name in den Oberflächen angezeigt.

<description>

Über dieses Tag kann eine Beschreibung zur Komponente angegeben werden.

<resources> / <resource>

Über diese Tags wird der Pfad zur JAR-Datei des JDBC-Treibers angegeben.

scope

Innerhalb des <resources> / <resource>-Tags sollte für diesen Parameter der Wert module angegeben werden. Er sorgt dafür, dass die JAR-Datei für das JDBC-Treiber-Modul und nicht den gesamten Server gilt.

<webresources> / <resource>

Über diese Tags wird innerhalb der Webanwendungs-Komponente der Pfad zur JAR-Datei des JDBC-Treibers angegeben. Folgende Parameter sollten zusätzlich verwendet werden:

<configuration>

Enthält Angaben zur Layer-Klasse und zum Klassennamen des verwendeten JDBC-Treibers.

<DRIVER>

Enthält den vollständigen Klassennamen des verwendeten JDBC-Treibers, beispielsweise org.postgresql.Driver für PostgreSQL. (Siehe auch Parameter DRIVER auf Seite Beschreibung der Pflichtparameter sowie die Seite mit den datenbanktyp-spezifischen Beispielkonfigurationen.)

<layerclass>

Über dieses Tag wird die Klasse angegeben, die den Datenbank-Layer für dieses spezielle Datenbanksystem implementiert, beispielsweise:

<layerclass>de.espirit.or.impl.postgres.PostgreSQLLayer</layerclass>

für PostgreSQL oder

<layerclass>de.espirit.or.impl.oracle.OracleLayer</layerclass>

für Oracle.
(Siehe auch Parameter layerclass unter Beschreibung der Pflichtparameter sowie die Seite mit den datenbanktyp-spezifischen Beispielkonfigurationen.)

Soll der JDBC-Treiber in einer Webanwendung zur Verfügung stehen, ist die Datei web.xml erforderlich (vgl. Module.xml und web.xml):

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="JDBC_PostgreSQL_9_3"
         version="3.0"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee"
 http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"/>

Der Wert des Parameters id sollte den Namen des JDBC-Moduls (Server-Komponente) angeben.

Soll die integrierte Derby-Datenbank in den Webanwendungen eines Tomcat-Web-Servers verwendet werden, wird ebenfalls eine module.xml-Datei benötigt. Eine exemplarische module.xml könnte so aussehen:

<module>
   <name>JDBC_Derby_10</name>
   <version>10.11.1.1</version>
   <description>JDBC Driver for Derby 10 databases</description>
   <vendor>Apache Software Foundation</vendor>

   <resources>
       <resource scope="module">lib/derbyclient.jar</resource>
   </resources>

   <components>
       <web-app>
         <name>WebApp_Derby_10</name>
         <description>Provides the JDBC Driver in a web application.</description>
         <web-xml>web.xml</web-xml>
         <web-resources>
            <resource scope="module"
                name="derby"
                version="10.11.1.1"  
                minVersion="10.1"
                maxVersion="10.99">lib/derbyclient.jar</resource>
         </web-resources>
       </web-app>
  
    </components>
  
    <configuration>
       <DRIVER>org.apache.derby.jdbc.ClientDriver</DRIVER>
       <layerclass>de.espirit.or.impl.derby.DerbyLayer</layerclass>
   </configuration>
</module>

Der Server-Komponententeil ist nur dann notwendig, wenn ein externer Tomcat-Web-Server eingesetzt wird.

Die Datei web.xml ist ebenfalls erforderlich. Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="JDBC_Derby_10"
         version="3.0"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee"
 http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"/>

Wird ein externer Webserver eingesetzt, ist der Datenbank-Layer anzupassen (siehe Installation und Konfiguration des JDBC-Treiber-Moduls).

Oracle-Beispiel

Für Oracle Database 19c sieht eine Beispielkonfiguration mit Treiber-Version 19.7.0.0 folgendermaßen aus:

• module.xml (hier als module-isolated.xml für den Isolated Mode, siehe Modulentwicklung "Isolated" (→Leitfaden Isolated Mode))
• web.xml

Eine Erläuterung der meisten der hier verwendeten Tags kann auch im FirstSpirit-Entwicklerhandbuch für Komponenten nachgeschlagen werden.