1. Configuration des librairies de fonctions

Une librairie Ontomantics est un ensemble de fonctions Java. Elles sont stockées dans des fichiers nommés NOM_DE_LA_LIB.jar.

Il existe deux types de librairies dans la plate-forme :

les librairies fournies par défaut avec Ontomantics
les librairies utilisateurs.

Elles sont toutes situées dans le répertoire : .../ontomantics/wildfly/standalone/OntomanticsLibrary.

Le fichier Library.jar contient toutes les librairies fournies avec la plateforme Ontomantics.

1.1. Utilisation des librairies sur la plateforme Ontomantics

Présentation

L’ensemble des librairies détectées par la plate-forme est répertorié dans l’écran Configuration Gérer les librairies de fonction accessible à travers le module Manager.

L’ensemble des librairies de fonctions est listé sur la gauche de l’écran. Pour chacune d’elles, il est possible de visualiser les fonctions contenues ainsi qu’une description :

Rechargement

Le bouton Recharger les librairies de fonction accessible en cliquant sur le bouton permet de :

détecter les nouvelles librairies en cas d’ajouts
prendre en compte dynamiquement une modification de librairie.

Le bouton Nettoyer les librairies de fonction accessible en cliquant sur le bouton permet de :

supprimer les librairies supprimées d’un fichier .jar.

Si une librairie est utilisée dans une application, une tâche planifiée, un service métier ou un service Web, mais qu’elle n’est plus disponible, alors la plateforme signale l’erreur en changeant le logo de la librairie.

Import de librairie

Il est possible d’importer des librairies depuis un fichier .jar, en cliquant sur le bouton (Importer des librairies de fonction).

Sélectionner le fichier .jar depuis la machine de l’utilisateur. Si la plateforme détecte une librairie existante, elle la met à jour après une série de tests et de vérifications de fonctionnement. Si elle n’existe pas, la plateforme la créé.

Utilisation

Une librairie peut être utilisée :

À travers une expression

À travers une action : Exécuter une fonction

1.2. Développement d’une librairie

1.2.1. Présentation

Une librairie de fonction Ontomantics est un fichier .jar contenant différentes classes Java. Ce fichier .jar possède certaines caractéristiques supplémentaires qui permettent son utilisation au sein de la plateforme Ontomantics.

Il est donc possible de créer un projet Java classique pour générer une librairie de fonction Ontomantics dans un IDE standard tel que Netbeans ou Eclipse.

Toutefois, Ontomantics fournit un export d’un projet Eclipse nommé ExempleLibrary.zip qui permet un développement simplifié en mettant à disposition du développeur la structure de base d’une librairie de fonction Ontomantics.

La suite de la documentation se basera sur l’utilisation de l’IDE Eclipse pour décrire la procédure de développement de la librairie.

1.2.2. Import du projet de base dans Eclipse

Dans l’IDE Eclipse, importer le projet ExempleLibrary.zip en effectuant les manipulations suivantes :

Menu File/Import,
Sélectionner la source General/Existing Projects in Workspace, puis Next,
Sélectionner la case à cocher Select archive file:,
Cliquer sur Browse… pour sélectionner le fichier ExempleLibrary.zip,
Cliquer sur Finish. Le projet est importé.

1.2.3. Structure du projet

À la racine du projet, le dossier lib permet d’inclure des librairies qui ne seront pas intégrées au .jar de la librairie de fonction, mais qui peuvent être nécessaires pour tester les classes dans Eclipse. Cela permet d’utiliser des librairies qui sont déjà intégrées à Ontomantics sans les inclure dans le .jar pour éviter les conflits.

L’élément suivant à la racine du projet est le fichier build.xml. Ce fichier permet de lancer une tâche Ant qui générera le fichier .jar de la librairie.

Le dernier élément à la racine du projet est le dossier src qui est le dossier habituel contenant les sources du projet.

Dans le dossier src, il existe plusieurs éléments. Tout d’abord, le package lib qui, contrairement au dossier lib, va contenir les librairies qui doivent être intégrées au .jar de librairie de fonction, ces dernières n’étant pas présentes dans la plate-forme Ontomantics.

Pour finir, le dossier src contient aussi un dossier META-INF qui contient lui même un fichier library.xml. C’est ce fichier qui décrit la façon dont Ontomantics doit interagir avec la librairie de fonction.

La suite de cette documentation expliquera en détail le fonctionnement des différents fichiers.

1.2.4. Le fichier `build.xml`

Le fichier build.xml, situé à la racine du projet, permet de lancer une tâche Ant pour compiler la librairie.

Avant de l’utiliser, il est nécessaire de l’éditer afin de configurer le nom de la librairie.

Voici le contenu du fichier build.xml :

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

<!-- ========================================== -->
<!-- Fichier de compilation ANT de la librairie -->
<!-- ========================================== -->

<project name="GenerateLibrary" default="generateLibraryJAR" basedir=".">

	<!-- Spécifier le nom de la librairie à ce niveau -->
    <property name="library.name" value="Exemple" />

    <property environment="env" />
	<!-- Répertoire source et binaire -->
    <property name="src.dir" value="${basedir}/src" />
    <property name="build.classes.dir" value="${basedir}/bin" />

    <!-- Build classpath -->
    <path id="build.classpath">
		<!-- Libraries inclus dans le JAR final doivent être mises dans le répertoire /src/lib -->
        <fileset dir="${src.dir}/lib">
            <include name="*.jar" />
        </fileset>
		<!-- Libraries utilisées uniquement pour la compilation doivent être mises dans le répertoire /lib (tels que log4j, slf4j) -->
        <fileset dir="./lib">
            <include name="*.jar" />
        </fileset>
    </path>

    <!-- ======================== -->
    <!-- Nettoyage et préparation -->
    <!-- ======================== -->
    <target name="prepare">
        <delete dir="${build.classes.dir}" failonerror="false" />
        <delete dir="${basedir}/${library.name}.jar" failonerror="false" />
        <mkdir dir="${build.classes.dir}" />
    </target>
    
    <!-- ======================= -->
    <!-- Compilation des sources -->
    <!-- ======================= -->
    <target name="compileLibrary" depends="prepare">
        <echo> 
            Compilation des sources de ${library.name}
        </echo>
        <javac source="11" target="11" srcdir="${src.dir}" destdir="${build.classes.dir}"
            includeantruntime="false" debug="on" deprecation="on" includes="**">
            <classpath refid="build.classpath" />
        </javac>
    </target>

    <!-- ========================= -->
    <!-- Generation du fichier JAR -->
    <!-- ========================= -->
    <target name="generateLibraryJAR" depends="compileLibrary">
        <echo> 
            Generation du fichier ${library.name}.jar
        </echo>
        <jar jarfile="${basedir}/${library.name}.jar">
            <fileset dir="src">
                <include name="**/*.jar" />
                <include name="META-INF/library.xml" />
            </fileset>
            <fileset dir="bin">
                <include name="**/*.class" />
            </fileset>
        </jar>
    </target>

</project>

Pour personnaliser le nom de la librairie, il suffit d’éditer la ligne 9 du fichier pour remplacer la value de l’élément Property, qui est par défaut Exemple, par le nom souhaité de la librairie.

	<!-- Spécifier le nom de la librairie à ce niveau -->

Pour compiler la librairie de fonction, il faut exécuter la tâche Ant correspondante. L’exécution d’une tâche Ant dans Eclipse nécessite l’utilisation de la vue Ant. Cette vue est disponible en passant par le menu Window/Show View/Ant. Une fois que la vue Ant est affichée, il faut glisser le fichier build.xml dans cette vue pour rendre l’exécution des tâches disponible.

Pour compiler la librairie, il suffit de double-cliquer sur GenerateLibrary dans la vue Ant.

1.2.5. Le fichier library.xml

Présentation

Le fichier library.xml, situé dans le répertoire src/META-INF du projet, permet de spécifier à la plateforme Ontomantics les fonctions mises à disposition.

Voici le contenu du fichier library.xml tel qu’il est fourni dans le projet de base :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library SYSTEM "https://www.ontomantics.com/DTD/Library-1.1.dtd">

<library>

    <!-- Chaque élément "library-unit" correspond à une classe Java -->
    <library-unit>
        <!-- Le nom de la librairie tel qu'il est affiché dans Ontomantics -->
        <name>ExempleLibrary</name>
        <!-- La description de la librairie -->
        <description>Un exemple de librairie de fonction pour Ontomantics</description>
        <!-- Fait référence au nom complet d'une classe situé dans le projet -->
        <class></class>
        <!-- Renseigne l'auteur de la librairie -->
        <author></author>
        <!-- Renseigne la version de la librairie -->
        <version>1.0.0</version>
        <!-- Renseigne la date de création/édition -->
        <date>01-01-2022</date>
        
        
        <!-- Chaque élément "library-parameter" décrit un paramètre situé dans
            le fichier de configuration des librairies -->
        <!-- <library-parameter> -->
            <!-- Le nom du paramètre qui doit correspondre au nom de la propriété dans la classe Java -->
            <!-- <name>name</name> -->
            <!-- Le nom du paramètre dans le fichier de configuration -->
            <!-- <config-value>exemple.library.name</config-value> -->
            <!-- La valeur par défaut du paramètre si il n'est pas présent dans le fichier de configuration -->
            <!-- <value>Ontomantics</value> -->
            <!-- Le type Java du paramètre -->
            <!-- <type>String</type> -->
            <!-- La description du paramètre -->
            <!-- <description>Le nom de l'entreprise</description> -->
        <!-- </library-parameter> -->
        
        
        <!-- Chaque élément "function" décrit une fonction de la librairie -->
        <function>
            <!-- Le nom de la fonction dans la classe Java -->
            <name>abs</name>
            <!-- La description de la fonction pour Ontomantics -->
            <description>Retourne la valeur absolue de l'argument passé en paramètre</description>
            
            <!-- Chaque élément "parameter" correspond à un paramètre de la fonction -->
            <!-- <parameter> -->
                <!-- Le nom du paramètre de la fonction dans la classe Java -->
                <!-- <name>arg</name> -->
                <!-- Le type java du paramètre -->
                <!-- <type>double</type> -->
                <!-- La description du paramètre -->
                <!-- <description>L'argument dont on souhaite calculer la valeur absolue</description> --> 
            <!-- </parameter> -->
            
            <!-- Le type java du retour de la fonction -->
            <!-- <return-type>double</return-type> -->
        </function>
    </library-unit>
</library>

Les types de données Java gérés par Ontomantics

Ontomantics gère un certain nombre de types de données qu’il est donc possible d’utiliser dans le fichier library.xml.

Parmi ces différents types se trouvent :

boolean : Le type primitif boolean,
char : Le type primitif char,
byte : Le type primitif byte,
short : Le type primitif short,
int : Le type primitif int,
long : Le type primitif long,
float : Le type primitif float,
double : Le type primitif double,
Boolean : Le wrapper java.lang.Boolean,
Character : Le wrapper java.lang.Character,
Byte : Le wrapper java.lang.Byte,
Short : Le wrapper java.lang.Short,
Integer : Le wrapper java.lang.Integer,
Long : Le wrapper java.lang.Long,
Float : Le wrapper java.lang.Float,
Double : Le wrapper java.lang.Double,
String : La classe java.lang.String,
Date : La classe java.util.Date,
File : La classe java.io.File,
URL : La classe java.net.URL,
List<T> : L’interface java.util.List,
Set<T> : L’interface java.util.Set,
Collection<T> : L’interface java.util.Collection.

Pour utiliser un de ces types dans le fichier library.xml, il faut donc utiliser le nom en gras dans cette liste, par exemple Integer pour la classe java.lang.Integer.

Pour les types paramétrés tels que List<T>, Set<T> et Collection<T> il est nécessaire de paramétrer le type avec un des autres types gérés par Ontomantics. Il est par exemple possible d’utiliser un Set<Integer>.

Tous ces types sont utilisables à la fois pour les paramètres des fonctions et pour les types de retour. Il est aussi possible d’utiliser un type spécifique en plus pour les types de retour qui est le type void, ce qui permet d’utiliser des fonctions qui ne retournent rien.

<library> et <library-unit>

Le fichier library.xml est constitué à la racine d’une balise obligatoire <library>.

La balise <library> possède un ou plusieurs fils <library-unit>. Chacun de ces éléments correspond à une classe Java qui doit être rendue accessible par la plateforme Ontomantics.

La durée de vie de l’instanciation d’une classe correspond à la durée de vie du comportement dans Ontomantics.

Les balises de base de <library-unit>

La balise <library-unit> possède toujours les balises suivantes :

<name> Le nom de la librairie tel qu’il est affiché dans la plateforme Ontomantics. Ce nom ne doit pas être modifié, car c’est lui qui est utilisé pour faire le lien entre les applications qui utilisent les librairies de fonctions et les librairies de fonctions.
<description> La description de la librairie pour la plateforme Ontomantics.
<class> Le nom complet de la classe située dans le projet qui sera liée à cette <library-unit>.
<author> L’auteur de la librairie.
<version> La version de la librairie.
<date> La date de création/modification de la librairie.

Voici un exemple de librairie de fonction basique :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library SYSTEM "https://www.ontomantics.com/DTD/Library-1.1.dtd">

<library>

    <library-unit>
        <!-- Le nom de la librairie tel qu'affiché dans Ontomantics -->
        <name>SurfaceLibrary</name>
        <!-- La description de la librairie -->
        <description>Permet de calculer différentes surfaces de figures
            géométriques</description>
        <!-- Fait référence au nom complet d'une classe dans le projet -->
        <class>com.ontomantics.library.Surface</class>
        <!-- Renseigne l'auteur de la librairie -->
        <author>Ontomantics</author>
        <!-- Renseigne la version de la librairie -->
        <version>1.0.0</version>
        <!-- Renseigne la date de création/édition -->
        <date>01-01-2012</date>
    </library-unit>

</library>

Et la classe Java qui va avec :

package com.ontomantics.library;

public class Surface
{}

Déclaration d’une fonction dans <library-unit>

La balise <library-unit> peut aussi posséder une ou plusieurs balises <function>. La balise <function> permet de déclarer une fonction qui sera visible et utilisable dans la plateforme Ontomantics. Cette fonction doit appartenir à la classe qui est liée à la balise <library-unit> correspondante.

Les fonctions rendues accessibles dans Ontomantics doivent l’être de l’extérieur de leur classe en étant public et ne doivent pas être static.

La balise <function> possède toujours les fils suivants :

<name> Le nom de la fonction dans la classe Java. Ce nom sera aussi utilisé pour identifier la fonction dans la plateforme Ontomantics.
<description> La description de la fonction qui sera affichée dans la plateforme Ontomantics.

De plus, la balise <function> peut aussi posséder une ou plusieurs balises <parameter>. La balise <parameter> permet de spécifier un paramètre de la fonction. Cette balise possède toujours les fils suivants :

<name> Le nom du paramètre dans la fonction de la classe Java.
<type> Le type Java du paramètre. (voir la rubrique Les types de données Java gérés par Ontomantics pour plus de détails sur les types utilisables)
<description> La description de l’argument qui sera affichée dans la plateforme.

Pour finir, la balise <function> peut aussi posséder une balise de type <return-type>. Cette balise sert à spécifier le type de retour de la fonction Java. (voir la rubrique Les types de données Java gérés par Ontomantics pour plus de détails sur les types utilisables).

Voici le précédent exemple de librairie de fonction basique complété :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library SYSTEM "https://www.ontomantics.com/DTD/Library-1.1.dtd">

<library>

    <!-- Librairie permettant de calculer des surfaces -->
    <library-unit>
        <name>SurfaceLibrary</name>
        <description>Permet de calculer différentes surfaces de figures
            géométriques</description>
        <class>com.ontomantics.library.Surface</class>
        <author>Ontomantics</author>
        <version>1.0.0</version>
        <date>01-01-2012</date>

        <!-- Fonction permettant de calculer la surface d'un carré -->
        <function>
            <name>surfaceCarre</name>
            <description>Fonction permettant de calculer la surface d'un
                carré</description>

            <parameter>
                <name>largeur</name>
                <type>int</type>
                <description>La largeur du carré</description>
            </parameter>

            <return-type>int</return-type>
        </function>

        <!-- Fonction permettant de calculer la surface d'un rectangle -->
        <function>
            <name>surfaceRectangle</name>
            <description>Fonction permettant de calculer la surface d'un
                rectangle</description>

            <parameter>
                <name>largeur</name>
                <type>int</type>
                <description>La largeur du rectangle</description>
            </parameter>

            <parameter>
                <name>longueur</name>
                <type>int</type>
                <description>La longueur du rectangle</description>
            </parameter>

            <return-type>int</return-type>
        </function>
    </library-unit>

</library>

Et la classe Java complétée qui va avec :

package com.ontomantics.library;
 
 /**
  * Classe permettant de calculer différentes surfaces
  */
 public class Surface
 {
     /**
      * Permet de calculer la surface d'un carré
     *
     * @param largeur La largeur du carré
     *
     * @return La surface du carré
     */
    public surfaceCarre(int largeur) {
        return largeur * largeur;
    }

    /**
     * Permet de calculer la surface d'un rectangle
     *
     * @param largeur  La largeur du rectangle
     * @param longueur La longueur du rectangle
     *
     * @return La surface du rectangle
     */
    public surfaceRectangle(int largeur, int longueur) {
        return largeur * longueur;
    }
}

Déclaration d’un paramètre de librairie dans <library-unit>

La balise <library-unit> peut aussi posséder une ou plusieurs balises <library-parameter>. La balise <library-parameter> permet de déclarer un paramètre de librairie. Les paramètres de librairie sont des variables qui sont chargées depuis le fichier de configuration ontomanticsLibraryConfig.properties qui est lui même situé dans le répertoire .../ontomantics/wildfly/standalone/configuration. Pour utiliser les paramètres de librairie, il suffit donc de déclarer un paramètre dans ce fichier avec un système de clé/valeur.

La balise <library-parameter> possède toujours les fils suivants :

<name> Le nom du paramètre qui doit correspondre au nom de la propriété dans la classe Java.
<config-value> Le nom du paramètre dans le fichier de configuration.
<value> La valeur par défaut du paramètre s’il n’est pas présent dans le fichier de configuration.
<type> Le type Java du paramètre. (voir la rubrique Les types de données Java gérés par Ontomantics pour plus de détails sur les types utilisables)
<description> La description du paramètre qui sera affichée dans la plateforme Ontomantics.

La variable de la classe Java liée au paramètre de la librairie ne doit pas être static, et il faut que la plate-forme Ontomantics puisse y accéder à travers ces getters et setters.

Voici le précédent exemple de librairie de fonction basique complété :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library SYSTEM "https://www.ontomantics.com/DTD/Library-1.1.dtd">

<library>

    <!-- Librairie permettant de calculer des surfaces -->
    <library-unit>
        <name>SurfaceLibrary</name>
        <description>Permet de calculer différentes surfaces de figures
            géométriques</description>
        <class>com.ontomantics.library.Surface</class>
        <author>Ontomantics</author>
        <version>1.0.0</version>
        <date>01-01-2012</date>

        <!-- Paramètre permettant de spécifier la valeur de pi -->
        <library-parameter>
            <name>pi</name>
            <config-value>library.surface.pi</config-value>
            <value>3.14</value>
            <type>float</type>
            <description>Paramètre permettant de spécifier la valeur de pi
                </description>
        </library-parameter>

        <!-- Fonction permettant de calculer la surface d'un cercle -->
        <function>
            <name>surfaceCercle</name>
            <description>Fonction permettant de calculer la surface d'un
                Cercle</description>

            <parameter>
                <name>rayon</name>
                <type>float</type>
                <description>Le rayon du cercle</description>
            </parameter>

            <return-type>float</return-type>
        </function>

        <!-- Fonction permettant de calculer la surface d'un carré -->
        <function>
            <name>surfaceCarre</name>
            <description>Fonction permettant de calculer la surface d'un
                carré</description>

            <parameter>
                <name>largeur</name>
                <type>int</type>
                <description>La largeur du carré</description>
            </parameter>

            <return-type>int</return-type>
        </function>

        <!-- Fonction permettant de calculer la surface d'un rectangle -->
        <function>
            <name>surfaceRectangle</name>
            <description>Fonction permettant de calculer la surface d'un
                rectangle</description>

            <parameter>
                <name>largeur</name>
                <type>int</type>
                <description>La largeur du rectangle</description>
            </parameter>

            <parameter>
                <name>longueur</name>
                <type>int</type>
                <description>La longueur du rectangle</description>
            </parameter>

            <return-type>int</return-type>
        </function>
    </library-unit>

</library>

La classe Java complétée qui va avec :

package com.ontomantics.library;

/**
 * Classe permettant de calculer différentes surfaces
 */
public class Surface
{
    /** La valeur de pi chargé du fichier de configuration */
    private float pi;

    /**
     * Permet de calculer la surface d'un cercle
     *
     * @param rayon Le rayon du cercle
     *
     * @return La surface du cercle
     */
    public surfaceCercle(float rayon) {
        return this.pi * rayon * rayon;
    }

    /**
     * Permet de calculer la surface d'un carré
     *
     * @param largeur La largeur du carré
     *
     * @return La surface du carré
     */
    public surfaceCarre(int largeur) {
        return largeur * largeur;
    }

    /**
     * Permet de calculer la surface d'un rectangle
     *
     * @param largeur  La largeur du rectangle
     * @param longueur La longueur du rectangle
     *
     * @return La surface du rectangle
     */
    public surfaceRectangle(int largeur, int longueur) {
        return largeur * longueur;
    }

    /**
     * Getter de pi
     *
     * @return La valeur de pi
     */
    public float getPi() {
        return this.pi;
    }

    /**
     * Setter de pi
     *
     * @param pi La valeur de pi
     */
    public void setPi(float pi) {
        this.pi = pi;
    }
}

Et le contenu du fichier ontomanticsLibraryConfig.properties :

library.surface.pi = 3.1415

1.2.6. Mise en place de la nouvelle librairie

Après avoir compilé la librairie avec la tâche Ant GenerateLibrary, il faut récupérer le fichier .jar à la racine du projet et le copier dans le répertoire .../ontomantics/wildfly/standalone/OntomanticsLibrary.

Sur l’écran Configuration Gérer les librairies de fonction, cliquer sur Recharger les librairies de fonction permet de voir apparaître la nouvelle librairie et ainsi pouvoir l’utiliser.

1. Configuration des librairies de fonctions

1.1. Utilisation des librairies sur la plateforme Ontomantics

Présentation

Rechargement

Import de librairie

Utilisation

1.2. Développement d’une librairie

1.2.1. Présentation

1.2.2. Import du projet de base dans Eclipse

1.2.3. Structure du projet

1.2.4. Le fichier build.xml

1.2.5. Le fichier library.xml

Présentation

Les types de données Java gérés par Ontomantics

Les balises de base de <library-unit>

Déclaration d’une fonction dans <library-unit>

Déclaration d’un paramètre de librairie dans <library-unit>

1.2.6. Mise en place de la nouvelle librairie

No Comments

1.2.4. Le fichier `build.xml`