module.xml and web.xml

The file module.xml contains the definition of the driver module and must be composed according to the following example. The basic framework is always the same, some tags and parameters vary depending on the used database type and version.

The following example represents the design of a module.xml file for a PostgreSQL 9.3 database:

<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>

The module consists of two parts: one part defines the resources for the FirstSpirit Server, the other part for the web applications (within the <web-app> tag). Thus, this JDBC driver can be used in the FirstSpirit Server and in web applications. If the driver is required only for the server, the definition within <web-app> can be omitted.

For the use of the FirstSpirit web applications a servlet engine is required which implements the servlet API in the Version 3.0.

<name>

This tag must be used for assigning a unique technical name for the components. Only the following characters are allowed: capital and lower case letters (A-Z, a-z) and figures (0-9). This name will be validated when installing the module. Modules which do not comply with this convention can not be installed.   
This technical name will be used for example for the display in the FirstSpirit ServerManager (in case where no display name was defined for the module), for checking the module when updating and installing and for creating files and folders on the hard disk. The name which is assigned to the server component must be indicated in the database layer configuration, too (see Configuration of the database layer).

<displayname>

This tag can be used for assigning an optional display name for the module. If a display name is defined this will be shown in all FirstSpirit user interfaces, for example in the overview of modules of the FirstSpirit server (see Figure on page Installation of the JDBC driver module). The display name which is assigned to the web application component will also be used in the Project properties, are “Web components” (see Figure on page Usage in web applications). The mandatory attribute <name> will still be used as unique technical name. If no display name is defined the technical name will be shown in the user interfaces.

<description>

This tag can be used to specify a description for the component.

<resources> / <resource>

Use these tags to indicate the path to the JAR file of the JDBC driver.

scope

The value module should be used for this parameter within the <resources> / <resource> tags. This ensures that the JAR file applies only to the JDBC driver module and not for the whole server.

<webresources> / <resource>

Use these tags to indicate the path to the JAR file of the JDBC driver within the web application component. The following parameters should be used in addition:

<configuration>

Contains information about the layer class and about the class name of the used JDBC driver.

<DRIVER>

Contains the complete class name of the used JDBC driver, e.g. org.postgresql.Driver for PostgreSQL. (See also parameter DRIVER on page Description of the obligatory parameters and the page with the database specific sample configurations.)

<layerclass>

Use this tag to indicate the class which implements the database layer for this special database system, e.g.

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

for PostgreSQL or

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

for Oracle.
(See also parameter layerclass under Description of the obligatory parameters and the page with the database specific sample configurations)

If the JDBC driver should be available in a web application, the file web.xml is required (see module.xml and 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"/>

The value of the parameter id should be the name of the JDBC module (server component).

If the integrated Derby database is to be used in the web applications of a Tomcat web server, you need also a module.xml file. An exemplary module.xml could look like this:

<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>

The part for the server component is only then required if an external Tomcat web server is used.

The file web.xml is required as well. Example:

<?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"/>

If an external webserver is used, the database layer must be adjusted (see Installation and configuration of the JDBC driver module).

Oracle Example

For Oracle Database 19c an example configuration with driver version 19.7.0.0 looks like this:

• module.xml (here as module-isolated.xml for Isolated Mode, see Module development "Isolated" (→Isolated Mode Guide))
• web.xml

An explication for the most tags used in these examples can be looked up also in the FirstSpirit Manual for Developers (Components) (German only).