Documentation

This document in English.

L’utilisation de ce logiciel vous soumet à nos Conditions d’utilisation.

version 1.1.8

Introduction:

HyperSQLOOo fait partie d’une Suite d’extensions LibreOffice et/ou OpenOffice permettant de vous offrir des services inovants dans ces suites bureautique.

Cette extension vous permet:

• De surmonter le dysfonctionnement 139538 pour les utilisateurs de LibreOffice sur Linux.
• D’utiliser la base de données HyperSQL en mode intégré, rendant la base de donnée portable (un seul fichier odb).
• De profitez des améliorations offertes par l’extension jdbcDriverOOo:
  • La gestion des utilisateurs et des rôles (groupes).
  • La gestion des nanosecondes et des fuseaux horaires.
  • La gestion de java.sql.Array, java.sql.Blob, java.sql.Clob…
• De remplacer le pilote HsqlDB 1.8 intégré fourni par LibreOffice / OpenOffice, une version qui aura bientôt plus de 20 ans, par une version HsqlDB récente et à votre choix.
• De supporter les propriétés ACID de la base de données HsqlDB sous jancente.

Attention : Si vous souhaitez migrer des fichiers odb créés avec LibreOffice ou OpenOffice et HsqlDB version 1.8, il est impératif d’utiliser la version 1.1.2 ou supérieure de HyperSQLOOo sinon il y a un grand risque de perte de données. La procédure de migration est donnée dans la section Comment migrer une base de données intégrée. Quoi qu’il arrive, gardez vos sauvegardes à jour.

Etant un logiciel libre je vous encourage:

• A dupliquer son code source.
• A apporter des modifications, des corrections, des améliorations.
• D’ouvrir un dysfonctionnement si nécessaire.

Bref, à participer au developpement de cette extension.
Car c’est ensemble que nous pouvons rendre le Logiciel Libre plus intelligent.

---

Prérequis:

L’extension HyperSQLOOo utilise l’extension jdbcDriverOOo pour fonctionner.
Elle doit donc répondre aux prérequis de l’extension jdbcDriverOOo.

Cette extension ne peut pas être installée avec l’extension SQLiteOOo.
C’est l’une ou l’autre, mais pour le moment, elles ne peuvent pas fonctionner ensemble (voir dysfonctionnement #156471).

Sous Linux et macOS les paquets Python utilisés par l’extension, peuvent s’il sont déja installé provenir du système et donc, peuvent ne pas être à jour.
Afin de s’assurer que vos paquets Python sont à jour il est recommandé d’utiliser l’option Info système dans les Options de l’extension accessible par:
Outils -> Options -> Pilotes Base -> Pilote HsqlDB intégré -> Voir journal -> Info système
Si des paquets obsolètes apparaissent, vous pouvez les mettre à jour avec la commande:
pip install --upgrade <package-name>

Pour plus d’information voir: Ce qui a été fait pour la version 1.1.0.

---

Installation:

Il semble important que le fichier n’ait pas été renommé lors de son téléchargement.
Si nécessaire, renommez-le avant de l’installer.

• Installer l’extension jdbcDriverOOo.oxt

  Cette extension est nécessaire pour utiliser HsqlDB version 2.7.2 avec toutes ses fonctionnalités.

• Installer l’extension HyperSQLOOo.oxt version

Redémarrez LibreOffice après l’installation.
Attention, redémarrer LibreOffice peut ne pas suffire.

• Sous Windows pour vous assurer que LibreOffice redémarre correctement, utilisez le Gestionnaire de tâche de Windows pour vérifier qu’aucun service LibreOffice n’est visible après l’arrêt de LibreOffice (et tuez-le si ç’est le cas).
• Sous Linux ou macOS vous pouvez également vous assurer que LibreOffice redémarre correctement, en le lançant depuis un terminal avec la commande soffice et en utilisant la combinaison de touches Ctrl + C si après l’arrêt de LibreOffice, le terminal n’est pas actif (pas d’invité de commande).

---

Utilisation:

Comment créer une nouvelle base de données:

Dans LibreOffice aller à: Fichier -> Nouveau -> Base de données…:

A l’étape: Sélectionner une base de données:

• selectionner: Créer une nouvelle base de données
• Dans: Base de données intégrée: choisir: Pilote HsqlDB intégré
• cliquer sur le bouton: Suivant

A l’étape: Enregistrer et continuer:

• ajuster les paramètres selon vos besoins…
• cliquer sur le bouton: Terminer

Maintenant à vous d’en profiter…

Comment importer des données depuis un fichier Calc:

LibreOffice vous offre la possibilité d’importer des données depuis Calc directement dans une table existante ou créée pour cet import. Voici la procédure à suivre:

• Vous devez d’abord créer une nouvelle base de données HsqlDB comme décrit dans la section précédente.
• Dans Calc sélectionner une plage de cellules puis: Edition -> Copier. Lors de la création d’une nouvelle table, il est possible de mettre dans la première ligne les noms des colonnes telles qu’elles seront importées dans cette nouvelle table.
• Dans Base (ie: la nouvelle base de données HsqlDB), après avoir sélectionné Tables dans le volet Base de données, faites un clic droit dans le volet Tables puis: Coller et suivez l’assistant proposé par LibreOffice. Il est important de nommer la table avec un nom complet (ie: PUBLIC.PUBLIC.Table1). Voir la documentation HsqlDB sur le catalogue et le schéma par défaut.

Comment migrer une base de données intégrée:

Si vous souhaitez migrer une base de données intégrée (HsqlDB version 1.8.0) vers une version plus récente (par exemple 2.7.2), procédez comme suit:

1. Faite une copie (sauvegarde) de votre base de données (fichier odb).
2. Si elles ne sont pas déjà installées, installez cette extension et l’extension jdbcDriverOOo.
3. Changez l’archive du pilote HsqlDB dans: Outils -> Options -> Pilotes Base -> Pilote JDBC -> Options des pilotes JDBC -> Archive -> Changer, par une version 1.8.1.10.
4. Redémarrer LibreOffice / OpenOffice aprés le changement du pilote (hsqldb.jar).
5. Ouvrir le fichier odb dans Base (double clique sur le fichier odb).
6. Dans Base allez à: Outils -> SQL et tapez la commande SQL: SHUTDOWN COMPACT ou SHUTDOWN SCRIPT.

• Recommencez cette procédure à l’étape 3 en utilisant une version 2.4.0 ou 2.4.1 ou 2.5.0.
• Recommencez cette procédure à l’étape 3 en utilisant la version 2.7.2.

---

Comment ça marche:

HyperSQLOOo est un service com.sun.star.sdbc.Driver UNO écrit en Python.
Il s’agit d’une surcouche à l’extension jdbcDriverOOo permettant de stocker la base de données HsqlDB dans un fichier odb (qui est, en fait, un fichier compressé).

Son fonctionnement est assez basique, à savoir:

• Lors d’une demande de connexion, plusieurs choses sont faites:
  • S’il n’existe pas déjà, un sous-répertoire avec le nom: . + nom_du_fichier_odb + .lck est créé à l’emplacement du fichier odb dans lequel tous les fichiers HsqlDB sont extraits du répertoire database du fichier odb (décompression).
  • L’extension jdbcDriverOOo est utilisée pour obtenir l’interface com.sun.star.sdbc.XConnection à partir du chemin du sous-répertoire + /hsqldb.
  • Si la connexion réussi, un DocumentHandler est ajouté en tant que com.sun.star.util.XCloseListener et com.sun.star.document.XStorageChangeListener au fichier odb.
  • Si la connexion échoue et que les fichiers ont été extraits lors de la phase 1, le sous-répertoire est supprimé.
• Lors de la fermeture ou du changement de nom (Enregistrer sous) du fichier odb, si la connexion a réussi, le DocumentHandler copie tous les fichiers présents dans le sous-répertoire dans le (nouveau) répertoire database du fichier odb (zip), puis supprime le sous-répertoire.

Le but principal de ce mode de fonctionnement est de profiter des caractéristiques ACID de la base de données sous-jacente en cas de fermeture anormale de LibreOffice. En contre partie, la fonction: fichier -> Sauvegarder n’a aucun effet sur la base de données sous jacente. Seul la fermeture du fichier odb ou son enregistrement sous un nom different (Fichier -> Enregistrer sous) effectura la sauvegarde de la base de donnée dans le fichier odb.

---

A été testé avec:

• LibreOffice 24.2.1.2 (x86_64)- Windows 10

• LibreOffice 7.3.7.2 - Lubuntu 22.04

• LibreOffice 24.2.1.2 - Lubuntu 22.04

• LibreOffice 24.8.0.3 (X86_64) - Windows 10(x64) - Python version 3.9.19 (sous Lubuntu 22.04 / VirtualBox 6.1.38)

Je vous encourage en cas de problème
de créer un dysfonctionnement
J’essaierai de le résoudre

---

Historique:

Ce qui a été fait pour la version 0.0.1:

• La rédaction de ce pilote a été facilitée par une discussion avec Villeroy, sur le forum OpenOffice, que je tiens à remercier, car la connaissance ne vaut que si elle est partagée…

• Utilisation de l’ancienne version de HsqlDB 1.8.0 (peut être facilement mise à jour).

• Ajout d’une boîte de dialogue permettant de mettre à jour le pilote (hsqldb.jar) dans: Outils -> Options -> Pilotes Base -> Pilote HsqlDB intégré

• Beaucoup d’autres correctifs…

Ce qui a été fait pour la version 0.0.2:

• Maintenant, le pilote divise automatiquement un odb lorsqu’il est ouvert… Cela permet la conversion des fichiers odb produits par le pilote LibreOffice / OpenOffice HsqlDB intégré

• Beaucoup d’autres correctifs…

Ce qui a été fait pour la version 0.0.3:

• Je tiens particulièrement à remercier fredt à hsqldb.org pour:

  • Son accueil pour ce projet et sa permission d’utiliser le logo HsqlDB dans l’extension.

  • La qualité de sa base de données HsqlDB.

• Fonctionne désormais avec OpenOffice sous Windows.

• Lors de la décompression, un conflit de nom de fichier affiche désormais une erreur précise.

• Gère désormais correctement les espaces dans les noms de fichiers et les chemins.

• Beaucoup d’autres correctifs…

Ce qui a été fait pour la version 0.0.4:

• Modification de Driver.py afin de rendre possible l’utilisation du service Uno: com.sun.star.sdb.RowSet.

• Beaucoup d’autres correctifs…

Ce qui a été fait pour la version 0.0.5:

• Ecriture d’un DocumentHandler responsable:
  • De l’extraction des fichiers de base de données contenus dans le fichier odb à la connexion.
  • De la sauvegarde des fichiers de base de données dans le fichier odb lors de sa fermeture.
• Réécriture de Driver.py afin de permettre:
  • Son fonctionnement avec le nouveau pilote JDBC fourni par l’extension jdbcDriverOOo version 0.0.4.
  • La prise en charge du nouveau DocumentHandler afin de rendre les fichiers odb portables tels qu’ils étaient dans LibreOffice / OpenOffice avec la version 1.8 de HsqlDB.
• Beaucoup d’autres correctifs…

Ce qui a été fait pour la version 1.0.0:

• Renommage de l’extension de HsqlDBembeddedOOo en HsqlDriverOOo.

• Integration de HyperSQL version 2.7.2.

Ce qui a été fait pour la version 1.0.1:

• Renommage de l’extension de HsqlDriverOOo en HyperSQLOOo.

• Résolution du dysfonctionnement 156511 survenant lors de l’utilisation de l’interface com.sun.star.embed.XStorage. Le contournement consiste à utiliser la méthode copyElementTo() au lieu de moveElementTo(). Les versions de LibreOffice 7.6.x et supérieures deviennent utilisables.

Ce qui a été fait pour la version 1.0.2:

• L’absence ou l’obsolescence de l’extension jdbcDriverOOo nécessaires au bon fonctionnement de HyperSQLOOo affiche désormais un message d’erreur.

• Encore plein d’autres choses…

Ce qui a été fait pour la version 1.1.0:

• Tous les paquets Python nécessaires à l’extension sont désormais enregistrés dans un fichier requirements.txt suivant la PEP 508.
• Désormais si vous n’êtes pas sous Windows alors les paquets Python nécessaires à l’extension peuvent être facilement installés avec la commande:
  pip install requirements.txt
• Modification de la section Prérequis.

Ce qui a été fait pour la version 1.1.1:

• Prise en charge des nouvelles fonctionnalités de jdbcDriverOOo 1.1.2.

Ce qui a été fait pour la version 1.1.2:

• Prise en charge de la dernière version de jdbcDriverOOo 1.3.1.
• Lors de l’enregistrement sous un nom différent, la base de données si ouverte sera fermée correctement.
• Lors de l’ouverture d’un fichier odb, si la connexion échoue, pour éviter la destruction des données, la recompression des fichiers de la base de données n’aura pas lieu. Merci à Robert d’avoir su détecter ce dysfonctionnement.

Ce qui a été fait pour la version 1.1.3:

• Utilisation du nouveau format de données implémenté dans la version 1.1.2. Par conséquent, si vous devez ouvrir des fichiers odb créés avec une version inférieure à 1.1.2, vous devez d’abord les ouvrir avec la version 1.1.2, sinon une erreur sera générée.

Ce qui a été fait pour la version 1.1.4:

• Mise à jour du paquet Python packaging vers la version 24.1.
• Mise à jour du paquet Python setuptools vers la version 72.1.0.
• L’extension vous demandera d’installer l’extensions jdbcDriverOOo en version 1.4.2 minimum.

Ce qui a été fait pour la version 1.1.5:

• Correction du problème n°2 qui semble être une régression liée à la sortie de JaybirdOOo. Merci à TeddyBoomer de l’avoir signalé.
• Mise à jour du paquet Python setuptools vers la version 73.0.1.
• Les options de l’extension sont désormais accessibles via: Outils -> Options… -> LibreOffice Base -> Pilote HsqlDB intégré

Ce qui a été fait pour la version 1.1.6:

• La journalisation accessible dans les options de l’extension s’affiche désormais correctement sous Windows.
• Les modifications apportées aux options de l’extension, qui nécessitent un redémarrage de LibreOffice, entraîneront l’affichage d’un message.
• Support de LibreOffice version 24.8.x.

Ce qui a été fait pour la version 1.1.7:

• Nécessite la dernière version de jdbcDriverOOo 1.4.4.
• Dans les options de l’extension il est possible de définir les options: Afficher les tables système, Utiliser les signets et Forcer le mode SQL qui seront spécifiques à ce pilote.

Ce qui a été fait pour la version 1.1.8:

• L’extension vous demandera d’installer l’extensions jdbcDriverOOo en version 1.4.6 minimum.
• Modification des options de l’extension accessibles via : Outils -> Options… -> LibreOffice Base -> Pilote HsqlDB intégré afin de respecter la nouvelle charte graphique.

Que reste-t-il à faire pour la version 1.1.8:

• Ajouter de nouvelles langue pour l’internationalisation…

• Tout ce qui est bienvenu…