Home > Models

Contraintes, triggers et fonctions

Les facettes permettent de définir des contraintes sur les Master Data dans les modèles d'adaptation. EBX.Platform supporte les facettes XML Schema et fournit des facettes étendues et programmatiques afin de définir des contrôles avancés.

• Facettes XML Schema supportées
  • Contrainte d'unicité
• Facettes étendues
  • Clés étrangères
  • Contraintes dynamiques
  • Contrainte FacetOResource
  • Contrainte excludeValue
  • Contrainte excludeSegment
  • Facette énumération alimentée par un autre noeud
• Facettes programmatiques
  • Contraintes programmatiques
  • Contraintes programmatiques de type Enumération
  • Contraintes programmatiques de type Nomenclature
  • Contrainte sur valeur nulle
  • Contraintes sur tables
• Triggers et fonctions
  • Valeurs calculées
  • Triggers
  • Valeurs auto incrémentées
• Controles des Entrées Utilisateurs
  • Contrôle de la saisie d'une valeur nulle
  • Gestion des espaces sur les types de données par EBX.Platform

Facettes XML Schema supportées

Notes :

• (1) La facette whiteSpace peut être définie, mais n’est pas interprétée par EBX.Platform.

• (2) Dans XML Schema, les facettes ‘boundary’ ne sont pas autorisées sur le type string, néanmoins EBX.Platform les autorise en tant que extensions.

• (3) Le type resource supporte une seule facette (obligatoire) EBX, FacetOResource (cf Facettes Etendues).

• (4) D’autres types supportent les mêmes facettes que le type dont ils dérivent. Par exemple, le type integer supporte les mêmes facettes que le type decimal.

Exemple:

Contrainte d'unicité

Il est possible de définir une contrainte d'unicité en utilisant la définition standard XML Schema xs:unique . Cette contrainte permet d'indiquer qu'une valeur doit être unique dans une table.

Dans l'exemple ci-dessous, une contrainte d'unicité est définie sur la table publisher pour le champ cible name (cela signifie que deux occurrences de la table publisher ne peuvent pas avoir le même nom) : 

La contrainte d'unicité doit être définie dans une table et doit comporter les propriétés suivantes :

Limitations :

1. Le champ cible de l'élément xs:field doit être dans une table.

2. La contrainte d'unicité ne peut pas s'appliquer si le champ cible est à l'intérieur d'une liste agrégée.

3. Une seule contrainte d'unicité sur plusieurs champs cible n'est pas supportée.

Facettes étendues

EBX.Platform fournit des contraintes avancées qui ne sont pas définies dans XML Schema mais sont utiles pour le Master Data Management.

Afin de conserver la conformité du document par rapport à la norme XML Schema, ces facettes sont définies sous l’élément annotation/appinfo/otherFacets .

Clés étrangères

Une référence à une clé primaire de table est définie par une facette étendue tableRef . L'élément doit être du type xs:string . 

L'exemple ci-dessous spécifie une référence (clé étrangère) vers une occurrence de l'élément catalog .

Note: Différentes combinaisons peuvent être spécifiées pour définir le libellé d'une clé étrangère. L'ordre de priorité des balises est le suivant : 

1. balise label définissant un libellé programmatique.

2. balise label définissant une expression localisée.

3. balise label définissant une expression par défaut.

La facette tableRef est interprétée comme une énumération. La clé étrangère formatée est la valeur de l'élément (type xs:string ). Le libellé peut être composé en ajoutant les chemins d'autres champs des occurrences référencées par l'élément labelPaths (les chemins sont absolus dans le contexte de l'occurrence).

Voir aussi :

• Extraction des clés étrangères (syntaxe des prédicats XPath)

Contraintes dynamiques

Les facettes suivantes supportent le référencement de la valeur d’un autre noeud :

• length

• minLength

• maxLength

• maxInclusive

• maxExclusive

• minInclusive

• minExclusive

Cette propriété permet de modifier les contraintes du modèle de données dynamiquement, dans les adaptations ou même dans un contexte.

Par rapport aux facettes standards, le nom de l’élément est conservé, cependant l’attribut statique value est remplacé par l’attribut path . 

Exemple :

Dans cet exemple, la borne de la facette minInclusive n’est pas définie statiquement, la valeur de la borne est détenue par le nœud " /domain/Loan/Pricing/AmountMini/amount ".

Contrainte FacetOResource

La facette doit être définie pour chaque type resource. Elle a les attributs suivants :

• moduleName  : indique via un alias quel module contient la ressource. Si c’est le module lui-même qui possède la ressource, alors l’alias doit être "wbp". Sinon, l’alias doit être l’une des valeurs définies dans l’élément <dependencies> du fichier ‘module.xml’;

• resourceType  : désigne le type de la ressource qui peut être : "ext-images", "ext-jscripts", "ext-stylesheets", "ext-html";

• relativePath  : représente le répertoire local où se trouve la ressource, situé juste en-dessous du répertoire correspondant au type de cette ressource ( "resourceType" ). Dans l'exemple ci-après, il s'agit du répertoire www/common/images/ . Ainsi, pour cet exemple, la ressource est située dans le répertoire www/common/images/promotion/ . Notons que le répertoire www/ est au même niveau que le répertoire WEB-INF/ . 

  De plus, pour qu'une ressource définie dans un répertoire régionalisé ( www/fr/ par exemple) soit prise en compte, il faut qu'une ressource de même nom soit définie dans www/common/ . 

Cette facette a le même comportement qu’une facette énumération : l’ensemble des valeurs est obtenu en listant récursivement tous les fichiers situés dans ‘local path’ du répertoire spécifié ‘resource type’ dans le ‘module’ spécifié.

Exemple :

Un aperçu de la structure des répertoires dans un module EBX.Platform (application Web J2EE) est donné dans la section Modules - Structure .

Contrainte excludeValue

Cette facette vérifie qu’une instance est différente d’une valeur donnée.

Exemple :

Ici, la chaîne vide est exclue des valeurs possibles.

Contrainte excludeSegment

Cette facette vérifie qu’une instance n’appartient pas à un segment de valeurs. Les bornes elles-mêmes sont exclues.

Exemple :

Ici, les valeurs comprises entre 20000 et 20999 sont exclues.

Facette énumération alimentée par un autre noeud

Par défaut, une facette énumération est décrite statiquement en XML Schema.

Le contenu de la facette énumération peut être alimenté par un autre nœud du modèle de données.

Alimentation par une liste

En ajoutant l’information suivante, on indique que le contenu de la facette énumération provient du nœud frère CountryList . 

• doit être de même type que le nœud portant la facette énumération.

• doit être multiple ( maxOccurs > 1).

Exemple :

Facettes programmatiques

EBX.Platform propose d'implémenter des contraintes qui ne sont ni spécifiées par XML Schema, ni proposées en extension par EBX.Platform, via une simple déclaration de classe Java dans le schéma.

Afin de conserver la conformité du document par rapport à la norme XML Schema, ces facettes sont définies sous l’élément

annotation/appinfo/otherFacets . 

Contraintes programmatiques

Une facette programmatique est définie par une classe Java implémentant l'interface Java Constraint . 

Il est possible d'associer des paramètres à la facette. Par conséquent, la classe Java implémentée doit être conforme au protocole JavaBean. Dans l'exemple ci-dessous, elle doit définir les méthodes :  getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Exemple :

Voir aussi :

• JavaBeans Specifications

Contraintes programmatiques de type Enumération

Une contrainte énumération ajoute à une contrainte programmatique basique la définition d'une liste ordonnée de valeurs. Pour cela, on définit une classe Java implémentant l'interface ConstraintEnumeration . Cette facette permet la sélection d'une valeur dans une liste.

Exemple :

Contraintes programmatiques de type Nomenclature

Une contrainte nomenclature ajoute à une contrainte programmatique basique la définition d'une liste ordonnée de "valeurs-labels". Pour cela, on définit une classe Java implémentant l'interface ConstraintNomenclature . Cette facette permet la sélection d'une valeur dans une liste.

Notons qu'une contrainte énumération (décrite précédemment) est davantage appropriée lorsque l'on souhaite afficher des "valeurs localisées" ou lorsque le nombre d'éléments de la liste de sélection est important.

Exemple :

Contrainte sur valeur nulle

Parfois une valeur n'est obligatoire que si certaines conditions sont vérifiées (par exemple si un autre champ a une certaine valeur). Cependant l'attribut standard de XML Schema, minOccurs , ne répond pas à un besoin de ce type, puisqu'il est statique.

Pour vérifier si un élément est obligatoire ou non obligatoire selon son contexte : 

1. une contrainte programmatique doit être définie par une classe Java (voir ci-dessus) ; 

2. cette classe doit de plus implémenter l'interface ConstraintOnNull ;

3. enfin les attributs de cardinalité XML Schema doivent spécifier que l'élément est optionnel ( minOccurs="0" et maxOccurs="1").

Note : par défaut, la contrainte sur valeur nulle n'est pas vérifiée lorsque l'utilisateur soumet sa saisie via l'outil EBX.Manager. Pour activer cette vérification à la saisie, il faut définir la propriété checkNullInput et si l'élément est terminal, activer l'instance.

Exemple :

Contraintes sur tables

Une contrainte portant sur une table est définie par une classe Java implémentant l'interface Java ConstraintOnTable . 

Une contrainte portant sur une table peut uniquemement être définie sur un noeud table.

Il est possible d'associer des paramètres à  la contrainte. Par conséquent, la classe Java implémentée doit être conforme au protocole JavaBean. Dans l'exemple ci-dessous, elle doit définir les méthodes :  getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Exemple :

Important: Les contraintes définies au niveau d'une table sont uniquement vérifiées lors d'un appel à  un rapport de validation d'une instance ou d'une table. Autrement dit, pour des raisons de performances, ce type de contrainte n'est pas vérifié lors d'une mise à jour telle que l'insertion, la suppression ou la modification d'un enregistrement sur la table associée à  cette contrainte. Cependant, le mécanisme interne de validation incrémentale optimise le nombre de vérifications de ce type de contrainte si des dépendances sont définies. Pour plus d'information sur le mécanisme de validation incrémentale, voir la section performances .

Voir aussi :

• JavaBeans Specifications

Triggers et fonctions

Valeurs calculées

Par défaut, les valeurs des nœuds d’une adaptation sont lues et persistées dans le référentiel EBX. Néanmoins, il est possible d’alimenter la valeur d’un nœud d’adaptation de manière spécifique.

Par exemple, une valeur peut provenir d’un système de persistance externe (base de données relationnelle, système central, etc.). Elle peut aussi être le résultat d'un calcul. Ce calcul (ou l'accès à la base) peut même prendre en compte des paramètres de l'adaptation courante.

Ceci est rendu possible par l’utilisation d’une fonction .

Une fonction est spécifiée dans le schéma XML au moyen de l’élément osd:function (voir exemple ci-dessous).

• La valeur de l'attribut class doit être le nom qualifié d’une classe Java qui implémente l’interface Java ValueFunction . 

• Des paramètres additionnels peuvent être spécifiés au niveau du schéma, en ce cas la convention des propriétés JavaBean est utilisée.

Exemple:

Triggers

Il est possible d'associer à des instances ou à des occurrences de tables des méthodes qui seront exécutées automatiquement lorsque certaines opérations sont effectuées : création, mise à jour, suppression, etc.

Dans le document XML Schéma, on spécifie ce cas de figure en utilisant la balise osd:trigger dans la balise annotation/appinfo .

Pour la définition de triggers sur des instances d'un schéma, on doit définir dans la balise osd:trigger , une classe Java qui étend la classe abstraite InstanceTrigger . 

Notons que dans le cas de triggers d'instances, il est conseillé de définir les balises annotation/appinfo/osd:trigger juste en dessous de l'élément racine du schéma XML concerné.

Exemple :

Pour la définition de triggers sur des occurrences de tables, on doit définir dans la balise osd:trigger une classe Java qui étend la classe abstraite TableTrigger . 

Dans le cas de triggers sur des occurrences de table, il est conseillé de définir les balises annotation/appinfo/osd:trigger juste en dessous de l'élément définissant la table ou le type de la table concernée.

Exemple :

Sur une table :

ou sur un type associé à une table :

Notons qu'il est possible d'associer des paramètres à un trigger. Par conséquent, la classe Java implémentée doit être conforme au protocole JavaBean. Dans l'exemple ci-dessus, elle doit définir les méthodes :  getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Valeurs auto incrémentées

Il est possible de définir des valeurs auto-incrémentées. Les valeurs auto-incrémentées sont uniquement autorisées à l'intérieur de tables et doivent être de type xs:int ou xs:integer .

Un auto-incrément est spécifié dans le document XML Schéma en utilisant la balise osd:autoIncrement dans la balise annotation/appinfo .

Exemple :

Les deux éléments start et step sont optionnels.

Exemple :

L'attribut start représente la valeur de départ de l'incrément. Si cet attribut n'est pas renseigné, alors la valeur 1 est utilisée par défaut.

L'attribut step indique le pas pour la prochaine valeur de l'auto incrément. Si cet attribut n'est pas renseigné, alors la valeur 1 est utilisée par défaut.

Un champ utilisant la balise osd:autoIncrement a le comportement suivant : 

• Le calcul et l'allocation de la valeur du champ sont effectués chaque fois qu'un nouvel enregistrement est inséré et que la valeur du champ est encore indéfinie.

• Aucune allocation n'est effectuée si l'insertion définit déjà une valeur non nulle. Par exemple, si un import d'archive ou un import XML définit la valeur, celle-ci est préservée. Il est à noter également qu'en conséquence, l'allocation n'est pas non plus effectuée pour l'insertion d'un enregistrement en mode 'overwriting' ou 'occulting'.

• Une valeur nouvellement allouée est, chaque fois que possible, unique dans l'étendue du référentiel. Plus précisément, l'unicité de l'allocation s'étend à toutes les instances et elle s'étend aussi à toutes les branches. Ce dernier cas permet de fusionner une branche avec une garantie raisonnable qu'il n'y aura pas de conflit de fusion si le champ osd:autoIncrement fait aprtie de la clé primaire. Ce principe a une limitation très spécifique : quand une mise à jour en masse et pré-spécifiant les valeurs est exécutée en parallèle d'une transaction allouant une valeur une valeur sur le même champ, il est possible que cette dernière alloue une valeur qui sera aussi affectée dans la première transaction (il n'y a pas de verrou entre plusieurs branches).

En interne, la dernière value d'un auto incrément est stockée dans la table 'Auto Incréments' de l'adaptation ebx-repository . Ce champ est automatiquement mis à jour, de telle sorte qu'il contienne la plus grande valeur ayant été affectée pour le champ osd:autoIncrement associé, et ce dans toute instance et branche du référentiel. Cette valeur est calculée en tenant compte de la plus grande valeur de la colonne auto-incrémentée dans la table en cours de mise à jour.

Dans certaines situations particulières, il peut être souhaitable d'éviter ce comportement (ex: gestion multi-environnement _dev/test/prod, avec des plages d'auto incréments différentes). Ce comportement particulier est supporté en activant la propriété disableMaxTableCheck :

• localement, en définissant l'élément <disableMaxTableCheck>true</disableMaxTableCheck> dans la déclaration de l'auto-incrément,

• pour tous les auto-incréments d'un schéma, en ajoutant l'élément <osd:disableMaxTableCheck="true"> dans la déclaration du schéma ( xs:appinfo ),

• ou globalement, en déclarant la propriété ebx.autoIncrement.disableMaxTableCheck=true dans la configuration principale (ebx.properties).

Remarque : il n'est pas conseillé d'utiliser cette option, les valeurs des auto-incréments générées pouvant entrer en conflit.

Controles des Entrées Utilisateurs

Contrôle de la saisie d'une valeur nulle

Selon la stratégie générale de validation, afin de permettre temporairement la saisie incomplète des données, le contrôle du caractère obligatoire d'un élément n'est pas exécuté lorsque l'utilisateur saisit une valeur nulle via l'outil EBX.Manager, mais lors de la validation globale de l'adaptation. Pour déclencher un contrôle immédiat à la saisie utilisateur, l'élément doit spécifier l'attribut osd:checkNullInput="true" .

Note : le caractère obligatoire d'une valeur n'est vérifié que si le schéma spécifie que l'élément est obligatoire, soit de façon statique ( minOccurs="1"), soit de façon dynamique (au moyen d'une contrainte sur valeur nulle). L'adaptation doit aussi être activée si l'élément obligatoire est terminal.

Exemple:

Voir aussi :

• Contrainte sur valeur nulle
• Gestion des espaces

Gestion des espaces sur les types de données par EBX.Platform

Conformément à XML Schema ( cf. http://www.w3.org/TR/xmlschema-2/#rf-whiteSpace ), la gestion des espaces pour un type donné doit suivre l'une des procédures suivantes : 

• preserve. Aucune normalisation n'est faite, la valeur initiale n'est pas modifiée

• replace. Toutes les occurrences de #x9 (tabulation), #xA (interligne) et #xD (retour chariot) sont remplacées par des occurrences de #x20 (espace)

• collapse. Après un traitement par la procédure replace , toutes les séquences de #x20 (espace) sont remplacées par un seul caractère #x20, et les espaces de début et de fin sont supprimés.

Procédure générale de EBX.Platform

EBX.Platform est conforme à la recommandation XML Schema :

• Pour les noeuds de type xs:string (clés primaires ou non), les espaces sont toujours preservés et la chaîne vide n'est jamais convertie à null . 

• Pour les autres noeuds (différents du type xs:string ), les espaces sont traités en suivant la procédure collapse et la chaîne vide est convertie à null . 

Exceptions : Pour les noeuds de type osd:html ou osd:password , les espaces sont toujours preservés et la chaîne vide est convertie à null . Pour les noeuds de type xs:string définissant la propriété osd:checkNullInput="true" la chaîne vide est considérée comme null lors de la vérification de la saisie utilisateur par EBX.Manager.

Cas spécifique pour la gestion des espaces sur les clés primaires de type string

Pour les colonnes de clé primaire de type xs:string , EBX.Platform définit une contrainte par défaut. Cette contrainte interdit les chaînes vides et les valeurs dont les espaces ne sont pas "collapsés" à la validation.

Cependant, si le noeud de la clé primaire définit une facette xs:pattern , cette dernière remplace la contrainte par défaut de EBX.Platform. Par exemple, un pattern spécifique peut autoriser tout type de chaîne. Ce pattern peut donc avoir la forme suivante :  .* . Ce cas de figure n'est cependant pas recommandé.

La contrainte par défaut permet d'empêcher certaines ambiguïtés. Par exemple, il sera difficile pour un utilisateur final de distinguer entre les chaînes de caractères suivantes : "12 34" et "12  34". Pour les valeurs usuelles cela ne pose pas de problèmes. En revanche, pour les clés primaires, cela peut porter à confusion et provoquer des erreurs.

Note : EBX.Platform permet de définir des tables qui permettent d'organiser et de gérer des Master Data avec des fonctionnalités semblables à celles des bases de données relationnelles.

Home > Models