Adventures in JDBC and the PostgreSQL JDBC driver: Part 6 - Deploying the PostgreSQL JDBC driver into Wildfly
Adventures in JDBC and the PostgreSQL JDBC driver: Part 6 - Deploying the PostgreSQL JDBC driver into Wildfly
In this article I will show you how to add PostgresSQL into Wildfly as the data source provider.
Wildfly contains a datasources subsystem, and here is the configuration in standalone/configuration/standalone.xml:
<subsystem xmlns="urn:jboss:domain:datasources:4.0">
<datasources>
<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
<connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
<driver>h2</driver>
<security>
<user-name>sa</user-name>
<password>sa</password>
</security>
</datasource>
<drivers>
<driver name="h2" module="com.h2database.h2">
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
</subsystem>
The above XML data is the configuration of the urn:jboss:domain:datasources subsystem. The datasource is bound to its jndi-name. Wildfly provides an example datasource, and its jndi-name is java:jboss/datasources/ExampleDS.
In addition, we can see the driver used by the example datasource is h2, and this driver is defined in drviers section.
In the h2 driver definition, we can see its module is com.h2database.h2. The Wildfly application server is designed to be modular (See An introduction to the JBoss Modular Service Container: Part 1 - Basic architecture of the container
), so the users can add or remove modules into the server, and the com.h2database.h2 module is provided by Wildfly by default. The com.h2database.h2 module contains the H2 database JDBC driver jar file. We can see the module in Wildfly modules directory:
$ pwd
/Users/weli/projs/jboss/wildfly10/wildfly-10.1.0.Final
$ ls modules/system/layers/base/com/h2database/h2/main/
h2-1.3.173.jar module.xml
From the above command output, we can see contents of com.h2database.h2 module. It has a module.xml, which is the module descriptor; and it has the h2-1.3.173.jar, which is the JDBC driver of the H2 database.
Now we go back to the driver definition of the module, and we can see the xa-datasource-class definition. In this article, I won’t explain the meaning of the xa-datasource-class in this article. For now you can just ignore this configuration, and actually it can be removed and Wildfly can still load the JDBC driver correctly. It will scan the driver module and load the JDBC driver automatically(I will write another article on this topic).
After checking the datasource configuration, we can start the Wildfly in standalone mode. Here is the command to start the server:
$ ./standalone.sh
After executing the above command, the server will startup and print log to the screen. From the server output, we can see the related part with the H2 JDBC driver. Here is the relative part of the log:
23:47:34,019 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 33) WFLYJCA0004: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
23:47:34,030 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-3) WFLYJCA0018: Started Driver service with driver-name = h2
From the above log output, we can see Wildfly has found the driver class of H2 database, which is org.h2.Driver, and Wildfly will use it to communicate with the underlying H2 database system.
After understanding the Wildfly datasource configuration, now we can add our own PostgreSQL JDBC driver into Wildfly as our datasource provider. The plan is to add a postgresql module into Wildfly, and put the compiled PostgreSQL JDBC driver file into the module.
Firstly, we need to create a directory for the postgresql module. We need to go to the home directory of our Wildfly. Here is the home path of the wildfly server on my local machine:
$ pwd
/Users/weli/projs/jboss/wildfly10/wildfly-10.1.0.Final
To create the postgresql module, I need to create a directory like this:
$ mkdir -p modules/system/layers/base/org/postgresql/main
The above command will create the full path of the directories that will be used to store the files of our postgresql module.
The next step is to copy the jar file into the module directory. Here is the command:
$ cp ~/.m2/repository/org/postgresql/postgresql/42.0.1-SNAPSHOT/postgresql-42.0.1-SNAPSHOT.jar \
modules/system/layers/base/org/postgresql/main/
The above command will copy our compiled PostgreSQL JDBC driver into the module directory.
Then we need to create a module descriptor file into the postgresql module, and the file name should be module.xml. Here is the content of the module.xml:
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
<resources>
<resource-root path="postgresql-42.0.1-SNAPSHOT.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>
The above XML data contains the definition of our org.postgresql module. It defines the name of the module, the resources of the module, and the dependencies of the module. We can see the name of the module is org.postgresql, the resource is postgresql-42.0.1-SNAPSHOT.jar, and the dependencies are javax.api and javax.transaction.api(The dependencies are provided by relative Wildfly modules).
After creating the module.xml and copying the jar file, we have prepared the module for Wildfly to load it. Here are the file contents in Wildfly module directory:
$ pwd
/Users/weli/projs/jboss/wildfly10/wildfly-10.1.0.Final/modules/system/layers/base/org/postgresql/main
$ ls
module.xml postgresql-42.0.1-SNAPSHOT.jar
After the module is prepared, we need to put the postgresql module as a data source into the datasources subsystem section of the standalone/configuration/standalone.xml. The configuration is similar to the existing h2 datasource.
First we need to put a new driver entry into the drivers section. Here are the contents of the entry:
<driver name="postgresql" module="org.postgresql">
</driver>
The above configuration adds our org.postgresql module as a database driver. We don’t have to define the driver class to use in the module, and Wildfly will find it intelligently(As I said, I’ll write another article for this topic).
After adding the driver, we need to add a datasource to use the driver. Here is the definition of the datasource:
<datasource jndi-name="java:jboss/datasources/weli" pool-name="weli" enabled="true" use-java-context="true">
<connection-url>jdbc:postgresql://localhost/weli</connection-url>
<driver>postgersql</driver>
<security>
<user-name>weli</user-name>
<password></password>
</security>
</datasource>
From the above configuration, we can see the name of our datasource is java:jboss/datasources/weli, and the driver we use is postgresql. The connection-url is used to connect to our created database, and we will use our weli database created in previous articles as the datasource. In security section we need to provide the user-name and the password to connect to our database.
Until now we have finished all the configuration, and we can restart the Wildfly server to test its correctness. We even don’t need to start our postgresql database server, because Wildfly will just lazily connect to the underlying database system until there are applications explicitly using the datasource. So for now we can stop the Wildfly server and then restart it in standalone mode. We should see the postgresql datasource is loaded. Here is the relative log output:
00:33:01,593 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 33) WFLYJCA0005: Deploying non-JDBC-compliant driver class org.postgresql.Driver (version 42.0)
00:33:01,594 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-3) WFLYJCA0018: Started Driver service with driver-name = postgresql
00:33:01,885 INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-3) WFLYJCA0001: Bound data source [java:jboss/datasources/weli]
From the above log output, we can see Wildfly automatically found the org.postgresql.Driver from our driver module, and it bounds the java:jboss/datasources/weli datasource correctly. Please note I haven’t started my PostgreSQL database server at this point, and Wildfly won’t really use the JDBC driver to connect to database server until there are deployed applications starting to use the datasource.
In this article, I have taught you to add database source into Wildfly. In next article, I’d like to guide you to see the datasource loading process of Wildfly.