Document IRIS Cloud – Guide du débutant et exemple : Partie II – Exemple d'application Java (Dockerisée)

Ceci est la deuxième partie d’une série de deux articles dans laquelle je vous présente :

• Partie I - Introduction et visite rapide (l’article précédent)
  • Qu’est-ce que c’est ?
  • Démarrer un déploiement InterSystems IRIS Cloud Document
  • Faire une visite rapide du service via l’interface utilisateur du service
• Partie II - Exemple d’application Java conteneurisée (cet article)
  • Récupérer les détails de connexion et le certificat TLS
  • Examiner un exemple Java simple qui crée une collection, insère des documents et les interroge
  • Configurer et exécuter l’exemple Java conteneurisé de bout en bout

Comme mentionné, l’objectif est de vous offrir une première expérience fluide.

Précédemment, nous avons créé un déploiement IRIS Cloud Document (et effectué une visite rapide), voyons maintenant comment interagir avec lui depuis une application Java.

Si vous souhaitez essayer par vous-même et passer à la pratique, vous aurez besoin de Docker et de Git, et devrez commencer par aller sur l’application Open Exchange, puis cloner le dépôt GitHub.

4. Notez les détails de connexion

Une fois le déploiement en cours d’exécution, ouvrez-le et consultez la page Overview. Vous y trouverez un tableau intitulé Making External Connections qui liste :

Gardez ces valeurs à portée de main ; nous les utiliserons dans la démo Java.

• Nom d’hôte (par exemple k8s-your-hostname.elb.us-east-1.amazonaws.com)
• Port (devrait être 443)
• Namespace (devrait être USER)
• Nom d’utilisateur SQL (devrait être SQLAdmin)
• Mot de passe (que vous avez défini lors de la création ou de la configuration de l’accès)

(Cette documentation peut aussi vous être utile)

1. Activer les connexions externes
   • Assurez-vous que l’accès externe est activé, soit pour toutes les adresses IP, soit pour votre IP client (ou votre plage d’IP) autorisée dans les paramètres du pare-feu du déploiement.
   • Cela se fait dans le portail Cloud Services lors de la création du service, ou dans la section mentionnée ci-dessus.
2. Télécharger le certificat TLS
   • Cloud Document requiert TLS. Depuis la vue d’ensemble du déploiement, un lien permet de télécharger un certificat X.509 auto-signé pour votre déploiement. Vous utiliserez ce certificat côté client pour établir une connexion TLS de confiance. Enregistrez-le sous un nom comme : certs/certificateSQLaaS.pem

C’est tout ce dont nous avons besoin depuis le portail : hôte, port, namespace, identifiants et fichier de certificat.

5. Examen de l’exemple d’accès à Cloud Document depuis Java

En général, le schéma ressemble à ceci :

1. Établir une connexion sécurisée (Connexion - Documentation) - Configurer DataSource (serveur, port, namespace, utilisateur, mot de passe, TLS).
2. Ingérer des données (Utilisation des documents et collections - Documentation) - Récupérer une Collection par nom (créée automatiquement lors de la première utilisation). Construire des objets JSONObject/JSONArray, puis les insérer comme Documents.
3. Interroger / récupérer les données (Requêtes - Documentation) - Interroger avec une ShorthandQuery (chaîne qui se comporte comme une clause WHERE appliquée à la collection).

Si vous avez déjà utilisé d’autres bases de données documentaires, cela devrait vous sembler familier.

Le pilote Java pour Cloud Document se trouve dans le package com.intersystems.document. Il fournit trois éléments principaux :

• DataSource – un pool de connexions vers le serveur Cloud Document.
• Document – classe de base pour les documents JSON ; en général, vous utiliserez ses sous-classes :
  • JSONObject – objet JSON avec des méthodes put() pour les paires clé/valeur.
  • JSONArray – tableau JSON avec des méthodes add().
• Collection – représente une collection nommée ; vous pouvez insert, get, getAll, drop et exécuter des requêtes.

Le code et les données utilisés dans cet exemple sont directement basés sur les exemples fournis dans notre documentation.

5.1 Établir la connexion

Commençons par les éléments nécessaires pour une connexion de base :

• Nom d’hôte, port, namespace, utilisateur, mot de passe – à récupérer dans les informations de « connexions externes » du déploiement.
• Le certificat X.509 du déploiement, importé dans un keystore Java.
• Un petit fichier SSLConfig.properties pour que le pilote sache quel keystore utiliser.

Création d’un DataSource avec TLS activé

Voici un exemple compact centré sur la connexion elle-même :

import com.intersystems.document.DataSource;
import com.intersystems.document.Document;

    // 1. Créer et configurer le DataSource (pool de connexions)
    pool = DataSource.createDataSource();
    pool.setServerName(serverName);
    pool.setPortNumber(port);
    pool.setDatabaseName(namespace);
    pool.setUser(user);
    pool.setPassword(password);

    // Exiger TLS – connectionSecurityLevel 10 active TLS.
    pool.setConnectionSecurityLevel(10);

    pool.preStart(5);
    pool.getConnection();  // forcer la création du pool

Si SSLConfig.properties et keystore.jks sont correctement configurés, l’appel à createDataSource() devrait établir une connexion TLS vers votre déploiement Cloud Document.

Le pilote Java Cloud Document recherche ce fichier SSLConfig.properties et l’utilise lorsque vous définissez connectionSecurityLevel de façon à exiger TLS.

Voici à quoi ce fichier peut ressembler :

# SSL/TLS configuration for InterSystems Java client
# This file MUST be named SSLConfig.properties and be in the application's working directory.
# The Docker image will create /app/keystore.jks at container startup.
debug=false
protocol=TLS
trustStore=keystore.jks
trustStorePassword=changeit

Dans l’exemple Docker que j’ai fourni, un script s’en charge pour vous.

Si vous exécutez vos propres exemples, vous pouvez utiliser une ligne comme celle-ci :

keytool -importcert -file /path/to/certs/cloud-document.pem -keystore keystore.jks

• Répondez yes lorsqu’on vous demande si vous voulez faire confiance au certificat.
• Définissez un mot de passe et retenez-le.

Dans l’exemple Docker, notre script fait ceci :

echo "Importing certificate into keystore..."
keytool -importcert -noprompt -alias "$ALIAS_NAME" -file "$CERT_PATH" -keystore "$KEYSTORE_PATH" -storepass "$KEYSTORE_PASSWORD"

5.2 Ingérer des données depuis Java

Une fois que nous avons un DataSource, nous travaillons avec des collections et des documents.

• Collection est le conteneur nommé, comme colors ou demoPeople.
• Un document est un JSONObject ou un JSONArray qui étend Document.

Voici un petit exemple d’ingestion qui reprend le fichier JSON colors que nous avons importé dans l’interface précédemment.

    // 2. Récupérer (ou créer) la collection
    Collection people = Collection.getCollection(pool, collectionName);
    if (people.size() > 0) {
        System.out.println("\nCollection '" + people.getName() + "' already has "
            + people.size() + " documents. Dropping them for a clean demo...");
        people.drop();
    }
    System.out.println("Using collection: " + people.getName());

    // 3. Insérer un document tableau très simple
    Document docOne = new JSONArray()
        .add("Hello from Cloud Document (Docker demo)");
    
    String id1 = people.insert(docOne);
    System.out.println("\nInserted docOne (JSONArray) with id " + id1);

    // 4. Insérer un document JSONObject
    Document docTwo = new JSONObject()
        .put("name", "John Doe")
        .put("age", 42)
        .put("city", "Boston");

    String id2 = people.insert(docTwo);
    System.out.println("Inserted docTwo (JSONObject) with id " + id2);

    // 5. Insertion en lot de plusieurs documents JSONObject
    List<Document> batch = new ArrayList<>();
    batch.add(new JSONObject()
        .put("name", "Jane Doe")
        .put("age", 20)
        .put("city", "Seattle"));
    batch.add(new JSONObject()
        .put("name", "Anne Elk")
        .put("age", 38)
        .put("city", "London"));

    BulkResponse bulk = people.insert(batch);
    System.out.println("Bulk insert completed. New ids: " + bulk.getIds());

Quelques remarques :

• Collection.getCollection(pool, name) créera la collection lors de la première utilisation si elle n’existe pas.
• insert() renvoie l’identifiant du document attribué par Cloud Document.
• insert(List<Document>) effectue une écriture en lot et renvoie tous les identifiants dans un BulkResponse.

C’est le même schéma de base que vous utiliseriez dans une application qui ingère du JSON depuis un fichier, une file ou une API.

5.3 Interroger et récupérer les données

Côté Java, vous avez principalement deux options :

1. Utiliser les API centrées sur les collections (getAll, createShorthandQuery, etc.).
2. Utiliser du SQL classique (par exemple via JDBC directement) et JSON_TABLE lorsque vous voulez des projections SQL riches.

Pour une première prise en main, les API de collection suffisent généralement.

Lister tous les documents d’une collection et en rechercher certains

            // 6. Récupérer et afficher tous les documents de la collection
            System.out.println("\nAll documents in collection '" + collectionName + "':");
            List<Document> allDocuments = people.getAll();
            for (Document d : allDocuments) {
                System.out.println("  " + d.getID() + ": " + d.toJSONString());
            }
            System.out.println("Collection size reported by server: " + people.size());

            // 7. Exécuter une requête shorthand
            String shorthand = "name > 'H' AND age >= 21";
            System.out.println("\nRunning shorthand query: " + shorthand);

            ShorthandQuery query = people.createShorthandQuery(shorthand);
            Cursor results = query.execute();

            System.out.println("Shorthand query returned " + results.count() + " result(s).");
            while (results.hasNext()) {
                Document d = results.next();
                System.out.println("  " + d.toJSONString());
            }

Ce qui se passe ici :

• getAll() vous donne tous les documents de la collection sous forme d’objets Document.
• createShorthandQuery("name > 'H'") crée une requête conceptuellement similaire à WHERE name > 'H' en SQL.
• Cursor vous permet d’itérer sur les résultats et aussi d’en obtenir le nombre.

Si vous souhaitez ensuite basculer dans le monde SQL, les mêmes collections manipulées ici peuvent être interrogées avec JSON_TABLE dans l’interface SQL ou via JDBC. C’est l’un des aspects agréables de Cloud Document : vous n’avez pas à choisir entre « API documentaire » et « SQL » ; vous avez les deux.

6. Configurer et exécuter l’exemple

Comme indiqué, je fournis un exemple conteneurisé avec Docker afin de garantir une expérience aussi fluide que possible, sans vous demander de télécharger et d’installer manuellement divers composants. Mais si vous le souhaitez, vous pouvez utiliser le même exemple et l’exécuter par vos propres moyens.

Open Exchange ainsi que le dépôt GitHub associé contiennent des instructions détaillées pour l’exécution, mais au niveau général cela revient simplement à :

6.1 Mettre à jour le fichier .env et placer le certificat TLS

Voici à quoi pourrait ressembler votre fichier de variables d’environnement après modification :

# Copy this file to .env and fill in your values

# Cloud Document connection settings
IRIS_HOST=k8s-e8c99d11-a90ppp7q-333333jj22-2222o11o111oo1o1.elb.us-east-1.amazonaws.com
IRIS_PORT=443
IRIS_NAMESPACE=USER
IRIS_USER=SQLAdmin
IRIS_PASSWORD=verySECRETpassword12345*

# Optional: collection name (override default)
COLLECTION_NAME=demoPeople

# Absolute path on your host to the Cloud Document X.509 certificate
CERT_FILE_HOST_PATH=./cert/certificateSQLaaS.pem

6.2 Exécuter docker compose

Il vous suffit d’exécuter docker compose up --build et l’exemple se lancera.

en coulisses, nous allons :

• Étape 1 : utiliser une image Maven + JDK pour construire un JAR autonome.
• Étape 2 : utiliser une image JDK légère, copier le JAR et SSLConfig.properties, créer un keystore à partir de votre certificat au démarrage du conteneur, puis exécuter le JAR.

Voici une courte vidéo qui le montre :

Pour conclure

Si vous êtes nouveau chez InterSystems mais pas nouveau dans le développement, le chemin de base vers une bonne première expérience avec IRIS Cloud Document est le suivant :

1. Mettre le service en route : créer un déploiement, noter l’hôte/le port/le namespace/les identifiants, télécharger le certificat.
2. Faire un premier essai dans le portail web : téléverser un fichier JSON, l’importer dans une collection, le parcourir avec le navigateur de collections et exécuter une requête SQL simple avec JSON_TABLE.
3. Le brancher à Java :
   
   • créer un DataSource avec TLS activé (avec SSLConfig.properties + keystore),
   • utiliser Collection et Document pour ingérer des données,
   • puis interroger avec getAll et des requêtes shorthand.

À partir de là, vous pouvez évoluer vers des choses plus intéressantes : mises à jour, suppressions, requêtes plus riches, combinaison de données Cloud Document avec des données relationnelles, ou utilisation d’autres pilotes comme .NET.

Mais si vous avez suivi jusqu’ici et vu vos propres documents JSON revenir depuis le code Java, vous avez déjà franchi l’étape la plus importante : vous êtes opérationnel dans l’écosystème InterSystems.

Bonne découverte !