Une base de données relationnelle embarquée dans Apache TomEE et sans prise de tête? Allons faire un petit tour du côté de HSQLDB

HSQLDB ou la base de données facile

Introduction

Dans le cadre d’un side-project, j’avais besoin d’une base de données relationnelle. Au départ, je voulais utiliser PostgreSql, mais l’application devant fonctionner sur un Raspberry 3+, j’ai revu mon choix et j’ai opté pour une base embarquée (“Embedded database”).

Embarquée vs Autonome

D’un côté, on trouve les serveurs de bases de données à installer (comme MariaDB, PostgreSql, Oracle, etc) et de l’autre on trouve des serveurs qui fonctionnent dans un serveur applicatif (par exemple Tomcat).

Les deux approches sont intéressantes et bien sûr chaque solution possède des avantages et des inconvénients.

Le principal avantage des bases embarquées est qu’elles démarrent avec en même temps que Tomcat et les autres applications.

Bases candidates

  • H2: base plutôt fiable mais la console d’administration est très pauvre.
  • Apache Derby: grosse déception! Ne fonctionne tout simplement pas avec Apache Deltaspike.
  • HSQLDB (HyperSql DataBase): intégration sans histoire avec Apache Deltaspike et gérable avec un client Sql tel que dBeaver.

Deux modes de fonctionnement

HSQLDB propose deux modes de fonctionnement: “in process” et “server”. Le mode “in process” consiste a inclure le jar HSQLDB dans l’application. Le mode “server” est plus intéressant puisqu’il permet d’héberger plusieurs bases dans un même serveur applicatif. Je vais présenter un exemple d’application appliquant le mode “server”.

Application HSqlServer

L’application s’articule autour d’une seule classe, nommée ici HSqlServer. Cette classe permet de configurer le port de connexion ainsi que la ou les bases exposées.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

package ch.gobothegeek.hsqlsrv;

import org.apache.deltaspike.core.api.config.ConfigResolver;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.hsqldb.Server;
import javax.servlet.*;
import java.io.IOException;

public class HSqlServerApp implements Servlet {
    private static final Logger logger = LogManager.getLogger(HSqlServerApp.class);

    private Server hServer;

    @Override
    public void init(ServletConfig servletConfig) throws ServletException {
        String[] arDbsCfg;
        String[] arDbInfo;

        logger.info("Starting HSqlServer");
        this.hServer = new Server();
        this.hServer.setPort(Integer.parseInt(ConfigResolver.getPropertyValue("application.port")));
        arDbsCfg = ConfigResolver.getPropertyValue("application.databases").split(";");
        for (int posDb = 0; posDb < arDbsCfg.length; posDb++) {
            if (0 < arDbsCfg[posDb].indexOf(":")) {
                arDbInfo = arDbsCfg[posDb].split(":");
                this.hServer.setDatabaseName(posDb, arDbInfo[0]);
                this.hServer.setDatabasePath(posDb, arDbInfo[1]);
            }
        }
        this.hServer.start();
    }

    @Override
    public ServletConfig getServletConfig() {
        return null;
    }

    @Override
    public void service(ServletRequest servletRequest, ServletResponse servletResponse) throws ServletException, IOException {
    }

    @Override
    public String getServletInfo() {
        return null;
    }

    @Override
    public void destroy() {
        logger.info("Destroying HSqlServer");
        this.hServer.stop();
    }
}

Le reste du projet se compose de fichiers de configuration. Le projet complet est téléchargeable ici et consultable sur mon GitHub.

Connexion et utilisation dans une application

Configurer pom.xml

Il faut en premier lieu inclure le jar HSqlDB via Maven dans le pom.xml:

1
2
3
4
5

<dependency>    
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>2.6.1</version>
</dependency>

Configurer Persistence.xml

Ensuite, il faut ajouter le fichier de persistance src/main/resources/META-INF/persistence.xml. En jaune, il s’agit des deux informations à adapter à son projet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<persistence
    version="2.0"
    xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
    <persistence-unit name="myDbUnit" transaction-type="RESOURCE_LOCAL">
        <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
        <non-jta-data-source>myDS</non-jta-data-source>
        <properties>
            <property name="openjpa.Log" value="SQL=Trace" />
            <property name="openjpa.ConnectionFactoryProperties" value="PrintParameters=true" />
            <property name="openjpa.jdbc.DBDictionary" value="hsql" />
        </properties>
    </persistence-unit>
</persistence>

A noter que j’ai activé l’affichage des requêtes (“SQL=Trace”) et des paramètres (“PrintParameters=true”) afin de faciliter la mise au point de mon application.

Configurer Resources.xml

Il faut maintenant configurer la datasource en ajoutant le fichier src/WebContent/WEB-INF/resources.xml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?xml version="1.0" encoding="iso-8859-1" ?>
<resources>
    <Resource id="myDB" type="javax.sql.DataSource">
        UserName SA
        Password
        jtaManaged false
        JdbcDriver org.hsqldb.jdbcDriver
        JdbcUrl jdbc:hsqldb:hsql://localhost:9001/projet
    </Resource>
</resources>

En jaune, on trouve les informations à adapter:

  • myDB: nom de la datasource.
  • SA: nom de l’utilisateur permettant d’accéder aux données.
  • localhost: le nom DNS du serveur sur lequel est accessible la base de données.
  • 9001: la port de connexion à la base de données.
  • projet: le nom de la base elle-même.

Configurer Web.xml

Le point suivant consiste à exposer la datasource nécessaire au bon fonctionnement de Deltaspike. Pour cela, on complète le fichier src/WebContent/WEB-INF/web.xml:

1
2
3
4
5
6

<resource-ref>
        <res-ref-name>myDB</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
        <res-sharing-scope>Shareable</res-sharing-scope>
    </resource-ref>

En jaune, “myDB” est le nom de la datasource et doit être identique à celui configuré dans le fichier resources.xml.

Définir un “Entity Manager”

Et pour terminer, il faut définir un “Entity Manager” qui va effectuer les requêtes produites par le ou les repositories.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

@ApplicationScoped
public class MyEntityManagerProducer implements Serializable {
    @PersistenceUnit(name = "MyDbUnit") private EntityManagerFactory entityManagerFactory;

    // return an EntityManager use to access data
    @Produces
    @TransactionScoped
    public EntityManager create() {
        return this.entityManagerFactory.createEntityManager();
    }

    // close current entity manager
    public void close(@Disposes EntityManager em)
    {
        if (em.isOpen()) { em.close(); }
    }

    // getter/setter for EntityManagerFactory
    public EntityManagerFactory getEntityManagerFactory() { return entityManagerFactory; }
    public void setEntityManagerFactory(EntityManagerFactory entityManagerFactory) { this.entityManagerFactory = entityManagerFactory; }
}

En jaune, on retrouve le nom de l’unité de persistance définie dans le fichier src/main/resources/META-INF/persistence.xml.

Et voilà, HSqlDB est prêt à l’emploi!

Conclusion

Il est assez facile et rapide d’ajouter un serveur HSqlDB et l’utiliser dans ses projets.

Commentaires

C’est par ici