Transition Jakarta (versions 5.20 et +)

Table des matières

Contexte
1. Bibliothèques d’envoi de mails
2. Fichier ROOT.xml
3. Montée de version en 5.21
Résolution des problèmes courants

L’objectif de ce document est de présenter les adaptations techniques à réaliser sur vos serveurs lors du passage à GEEF / Virtualia 5.20 et versions suivantes, ainsi que la procédure de montée de version vers la 5.21.

Contexte

À partir de la version 5.20, GEEF / Virtualia s’appuie sur Jakarta EE en remplacement de Java EE (javax.*). Pour rappel (voir la note de version 5.20) :

Java 21 (ou supérieur) est obligatoire ;
Tomcat 10.1.x est obligatoire (Tomcat 8, 8.5 et 9 ne sont plus compatibles ; Tomcat 11 est possible avec quelques risques résiduels).

Ce changement impose trois adaptations sur le serveur :

le remplacement des bibliothèques d’envoi de mails ;
l’ajout du convertisseur Jakarta dans le fichier ROOT.xml (version 5.20.x uniquement) ;
la mise à jour de la ressource mail dans le fichier ROOT.xml.

Sans ces adaptations, l’application peut ne pas démarrer ou ne plus envoyer de mails.

1. Bibliothèques d’envoi de mails

Tomcat doit être arrêté pendant toute cette étape.

Bibliothèques à ajouter

Télécharger les 4 bibliothèques suivantes :

Bibliothèque	Version	Téléchargement
Jakarta Mail API	2.1.3	jakarta.mail-api-2.1.3.jar
Angus Mail (implémentation)	2.0.3	angus-mail-2.0.3.jar
Jakarta Activation API	2.1.3	jakarta.activation-api-2.1.3.jar
Angus Activation (implémentation)	2.0.2	angus-activation-2.0.2.jar

Les déposer dans le dossier lib de Tomcat :

Serveur Windows : dossier lib du répertoire d’installation d’Apache Tomcat, par exemple C:\Program Files\Apache Software Foundation\Tomcat 10.1\lib ;
Serveur Linux : dossier tomcat/lib (selon l’installation, par exemple /opt/tomcat/lib, ou /usr/share/tomcat10/lib pour les paquets Debian / Ubuntu).

A noter : si votre instance Tomcat utilise un répertoire d’instance distinct du répertoire d’installation (CATALINA_BASE différent de CATALINA_HOME, cas fréquent sous Windows avec plusieurs instances Prod / Test / Form), les bibliothèques peuvent être placées dans l’un ou l’autre dossier lib, mais pas dans les deux.

Bibliothèques à supprimer

Supprimer du (ou des) dossier(s) lib de Tomcat les anciennes bibliothèques javax, quel que soit leur numéro de version :

mail : javax.mail.jar, javax.mail-x.y.z.jar, mail.jar, javax.mail-api-x.y.z.jar ou équivalent ;
activation : javax.activation.jar, javax.activation-x.y.z.jar, activation.jar, javax.activation-api-x.y.z.jar ou équivalent.

Ne pas supprimer les fichiers commençant par jakarta. ou angus- ajoutés ci-dessus.

Le contenu du dossier lib doit ressembler à ceci (extrait) :

lib/
├── angus-activation-2.0.2.jar
├── angus-mail-2.0.3.jar
├── jakarta.activation-api-2.1.3.jar
├── jakarta.mail-api-2.1.3.jar
├── catalina.jar
├── ...                          (bibliothèques Tomcat et driver JDBC)

Paramètre applicatif

Dans GEEF, vérifier que le paramètre mail.smtp.api a la valeur JAKARTA (et non JAVAX).

A noter : à partir de la version 5.21, la valeur JAVAX est automatiquement considérée comme JAKARTA.

2. Fichier ROOT.xml

Le fichier ROOT.xml se trouve dans le dossier conf/Catalina/localhost/ de Tomcat (de CATALINA_BASE si l’instance est distincte).

Faire une copie de sauvegarde du fichier avant toute modification.

Convertisseur Jakarta (version 5.20.x)

En 5.20 et 5.20.x, la ligne suivante doit être ajoutée juste avant la balise fermante </Context> :

<Loader jakartaConverter="TOMCAT"/>

À partir de la version 5.21, ce convertisseur n’est plus nécessaire (voir la note de version 5.21, EO15). Une fois la version 5.21 installée et validée, retirer cette ligne : le convertisseur ralentit le démarrage de Tomcat.

Ressource mail

La ressource mail/Session doit être déclarée sur le modèle suivant (le type passe de javax.mail.Session à jakarta.mail.Session) :

<Resource
    name="mail/Session"
    auth="Container"
    type="jakarta.mail.Session"
    mail.smtp.host="localhost"
    mail.transport.protocol="smtp"
    mail.port="25"
    mail.debug="false"
    mail.smtp.auth="false"
  />

Adapter mail.smtp.host, mail.port et mail.smtp.auth à votre serveur SMTP.

Exemple complet (5.20.x)

<?xml version="1.0" encoding="UTF-8"?>
<Context>

  <!-- ... autres ressources (DataSource, etc.) ... -->

  <Resource
      name="mail/Session"
      auth="Container"
      type="jakarta.mail.Session"
      mail.smtp.host="localhost"
      mail.transport.protocol="smtp"
      mail.port="25"
      mail.debug="false"
      mail.smtp.auth="false"
    />

  <Loader jakartaConverter="TOMCAT"/>
</Context>

Cohérence de la DataSource

Profiter de cette intervention pour vérifier que la DataSource déclarée dans ROOT.xml est cohérente : la classe du driver (driverClassName) et le préfixe de l’URL (url) doivent correspondre au même driver JDBC présent dans le dossier lib.

Base	`driverClassName`	Préfixe de `url`
MariaDB (driver MariaDB)	`org.mariadb.jdbc.Driver`	`jdbc:mariadb://`
MySQL (driver MySQL 8+)	`com.mysql.cj.jdbc.Driver`	`jdbc:mysql://`
Oracle	`oracle.jdbc.OracleDriver`	`jdbc:oracle:thin:@`

Une combinaison mixte (par exemple com.mysql.jdbc.Driver avec une URL jdbc:mariadb://) est à corriger.

3. Montée de version en 5.21

La version cible recommandée est la 5.21.1.

Prérequis

La montée de version en 5.21 doit se faire depuis une version 5.20 ou 5.20.1.

les adaptations des sections 1 et 2 ci-dessus sont réalisées ;
la 5.20 / 5.20.1 est installée et le processus d’optimisation BD est complété (plus aucun script restant dans « Outils > Optimisation BD > Vérification »).

Il est recommandé :

d’effectuer une sauvegarde complète de la base de données avant de commencer ;
d’activer le paramètre Outils > Paramètres > Paramètres > Sécurité > Sécurité - Maintenance en cours pendant l’opération (voir Installer une nouvelle version) ;
de réaliser l’opération d’abord sur l’environnement de test.

Installer ensuite la version 5.21 / 5.21.1 selon la procédure habituelle (Installer une nouvelle version), puis dérouler les étapes ci-dessous.

Étapes communes

1- Démarrer Tomcat.

2- Aller dans Outils > Optimisation BD et cliquer sur le bouton « Vérification ».

Ne pas utiliser le bouton « Mise à niveau » à cette étape.

3- Copier le script généré et regarder son début.

S’il commence par un grand nombre d’instructions CREATE TABLE : ne pas faire ce premier essai, passer directement à l’étape 4.

A noter : ces CREATE TABLE apparaissent lorsque l’application n’a pas pu lire la structure de la base, notamment lorsqu’un traitement est bloqué (deadlock). Les tables existent bien : ces lignes ne doivent jamais être exécutées, et un premier essai resterait probablement bloqué lui aussi.

Sinon, exécuter ce script une première fois :

soit via Outils > Importation > Base, après l’avoir enregistré dans un fichier .txt ;
soit directement dans votre client SQL (modalités selon votre base : voir l’étape 7 ci-dessous ; sous Oracle, terminer par COMMIT;).

Refaire ensuite l’étape 2 (bouton « Vérification ») :

si le script est passé sans erreur et que plus rien n’est généré : la mise à niveau de la base est terminée, passer directement à Après la montée de version ;
si le script est très long, échoue / plante, ou si un script est encore généré : poursuivre avec les étapes suivantes.

4- Copier et conserver le dernier script généré par « Vérification » dans un fichier texte (par exemple script_5.21.sql).

S’il commence par un grand nombre d’instructions CREATE TABLE, supprimer ces lignes jusqu’à ce qu’il n’y en ait plus : la première ligne du script à exécuter doit commencer par :

INSERT INTO TYPES_CONV_EMP

5- Arrêter Tomcat. Si un premier essai lancé à l’étape 3 depuis un client SQL est toujours en cours, l’annuler également.

L’objectif est d’interrompre le traitement en cours sur la table UV_PROGRESS, qui bloquerait l’exécution du script.

Les étapes suivantes dépendent de votre base de données.

Bases MySQL / MariaDB

6- Dans l’invite de commande mysql (ou votre client SQL), connecté à la base GEEF, lister les processus en cours :

SHOW FULL PROCESSLIST;

Ou, pour filtrer directement :

SELECT ID, USER, TIME, STATE, INFO
FROM information_schema.PROCESSLIST
WHERE INFO LIKE 'INSERT INTO UV_PROGRESS%';

6.a- Si un processus INSERT INTO UV_PROGRESS est présent dans la liste, l’arrêter :

KILL <ID>;

avec <ID> l’identifiant du processus (colonne Id). Sinon, passer directement à l’étape 7.

7- Coller le script conservé à l’étape 4 et le laisser s’exécuter jusqu’au bout.

Pour un script volumineux, il est préférable de l’exécuter depuis le fichier :

mysql -u <utilisateur> -p <base_geef> < script_5.21.sql

ou, depuis l’invite mysql :

SOURCE /chemin/vers/script_5.21.sql;

8- Refaire les étapes 1 et 2. Si un script est à nouveau présent, utiliser cette fois le bouton « Mise à niveau » : il permet de repérer si une erreur est encore présente.

Bases Oracle

Les étapes 6 et 6.a nécessitent un compte disposant des vues V$SESSION / V$SQLAREA et du privilège ALTER SYSTEM : elles doivent être réalisées par votre DBA.

6- Dans SQL*Plus ou SQL Developer, rechercher les sessions travaillant sur la table UV_PROGRESS :

SELECT s.sid, s.serial#, s.username, s.status, s.program, q.sql_text
FROM v$session s
JOIN v$sqlarea q ON q.sql_id = s.sql_id
WHERE UPPER(q.sql_text) LIKE 'INSERT INTO UV_PROGRESS%';

Puis vérifier qu’aucune session ne conserve de verrou sur cette table :

SELECT s.sid, s.serial#, s.username, s.status, s.program
FROM v$locked_object l
JOIN dba_objects o ON o.object_id = l.object_id
JOIN v$session s ON s.sid = l.session_id
WHERE o.object_name = 'UV_PROGRESS';

6.a- Si une session est remontée par l’une de ces requêtes, l’arrêter :

ALTER SYSTEM KILL SESSION '<SID>,<SERIAL#>' IMMEDIATE;

avec <SID> et <SERIAL#> les valeurs des colonnes SID et SERIAL#. Sinon, passer directement à l’étape 7.

7- Connecté avec le compte (schéma) de l’application GEEF, exécuter le script conservé à l’étape 4 et le laisser s’exécuter jusqu’au bout :

SQL Developer : coller le script dans une feuille de calcul et utiliser « Exécuter le script » (F5) et non « Exécuter l’instruction » (Ctrl+Entrée) ;
SQL*Plus : @/chemin/vers/script_5.21.sql

Terminer impérativement par un COMMIT; : sous Oracle, les instructions INSERT / UPDATE du script ne sont pas validées automatiquement.

COMMIT;

8- Refaire les étapes 1 et 2. Si un script est à nouveau présent, utiliser cette fois le bouton « Mise à niveau » : il permet de repérer si une erreur est encore présente.

Après la montée de version

Une fois la 5.21 validée :

arrêter Tomcat ;
retirer la ligne <Loader jakartaConverter="TOMCAT"/> du fichier ROOT.xml ;
redémarrer Tomcat et vérifier le bon démarrage de l’application ainsi que l’envoi d’un mail de test ;
désactiver le paramètre « Sécurité - Maintenance en cours ».

Résolution des problèmes courants

Symptôme	Cause probable	Action
L’application ne démarre pas, erreur `ClassNotFoundException` / `NoClassDefFoundError` sur `javax.mail` ou `javax.servlet` (5.20.x)	Convertisseur Jakarta absent	Ajouter `<Loader jakartaConverter="TOMCAT"/>` dans `ROOT.xml` (section 2)
Erreur au démarrage sur la ressource `mail/Session`	Type `javax.mail.Session` encore déclaré, ou bibliothèques Jakarta absentes	Passer le type à `jakarta.mail.Session` et vérifier les 4 bibliothèques dans `lib` (section 1)
Les mails ne partent plus	Anciennes bibliothèques `javax.mail` / `activation` encore présentes, ou paramètre `mail.smtp.api` à `JAVAX`	Supprimer les anciennes bibliothèques, passer `mail.smtp.api` à `JAKARTA`
Le script de mise à niveau 5.21 reste bloqué / ne se termine pas	Traitement `UV_PROGRESS` toujours actif	Reprendre les étapes 5 à 6.a (section 3)
Sous Oracle, le script revient à l’identique après exécution	`COMMIT` non effectué	Relancer le script puis exécuter `COMMIT;`
Un script est toujours présent après l’étape 8	Erreur résiduelle dans la structure	Utiliser « Mise à niveau », puis transmettre le message d’erreur et le script via un ticket Mantis