ORDA – Gérer une logique événementielle lors des opérations sur la base de données

Cette fonctionnalité se poursuit avec un nouveau paradigme : traiter les données de manière événementielle. Le 4D 21 fournit une série complète d’événements liés aux opérations de base de données(sauvegarde ou abandon).

Les événements ORDA peuvent remplacer les déclencheurs et offrent beaucoup plus d’avantages : plus de contrôle, vous permettant de coder votre logique d’entreprise (y compris les tâches fastidieuses telles que l’impression de factures ou le stockage de données externes) directement dans une fonction de classe de données ORDA. Ils répondent à des événements au niveau des données tels que new, modify, save, drop (CRUD).

Les événements ORDA offrent une granularité précise et une gestion sophistiquée des erreurs, conduisant à une forte intégrité des données et à une meilleure organisation du code.

Découvrez comment mettre en œuvre la logique métier appropriée à chaque étape d’une action de sauvegarde ou de dépôt.

HDI_ORDA_Events_Save_Drop

Les événements ORDA – Une valse à plusieurs temps

Dans ce précédent billet de blog, nous avons dévoilé le premier événement d’une longue série : l’événement touché.

Les nouveaux événements d’opération de base de données sont conçus pour être utilisés dans la couche ORDA à travers des entités manipulées avec le mot-clé This ce qui n’est pas possible avec les triggers.

Par rapport aux déclencheurs, ces événements offrent une granularité plus fine pour détecter des étapes spécifiques d’opérations de base de données et une gestion sophistiquée des erreurs qui peut arrêter l’action si nécessaire.

Contrairement aux déclencheurs, les événements ne permettent pas seulement de mettre en œuvre des actions avant les actions de sauvegarde/dépose. Ils peuvent également exécuter des actions pendant et après les opérations de sauvegarde/dépose.

La gestion des erreurs est puissante, vous pouvez renvoyer des erreurs personnalisées avec différentes sévérités et des informations supplémentaires détaillées pour l’utilisateur final.

Auparavant, vous pouviez mettre en œuvre certaines fonctions à cet effet, mais vous deviez les appeler manuellement chaque fois que cela s’avérait nécessaire.

Désormais, cette fonctionnalité offre une logique événementielle complète, qui se déclenche automatiquement au moment opportun. Mettez-la en œuvre une seule fois et laissez le moteur 4D s’en charger au moment de l’exécution :

• Les données incohérentes peuvent être rejetées à l’avance sans impliquer la couche de persistance.
• Les interactions avec les systèmes externes peuvent avoir lieu précisément lorsque les données 4D sont persistées.
• Des actions peuvent être déclenchées en cas d’échec de la sauvegarde/du dépôt.

 

Et bonne nouvelle, contrairement aux triggers, ORDA ne verrouille pas l’ensemble de la table sous-jacente d’une classe de données lors de la sauvegarde/dépose d’une entité. Plusieurs événements peuvent se dérouler en parallèle tant qu’ils impliquent des entités distinctes (i.e. des enregistrements).

Si vous comptez sur un verrouillage complet de la table entière pour gérer des numéros de séquence uniques ou similaires, vous devez le gérer vous-même, par exemple avec des singletons – ce qui vous permet de ne verrouiller que lorsque c’est nécessaire – et d’avoir un contrôle total sur ce processus.

Les différentes phases d’une opération de base de données

Lorsqu’une action de sauvegarde ou d’abandon est exécutée, ces événements vous permettent de mettre en œuvre la logique métier dans trois phases distinctes de l’action :

• Validation de l’action de sauvegarde ou d’abandon : Utile pour vérifier la cohérence des données concernant cette action, par exemple :
  • Le statut de l’entité sur le point d’être supprimée est-il défini sur « TO DELETE » ?
  • La date de départ est-elle < à la date d’arrivée dans une entité de réservation ?

Grâce à cet événement, vous pouvez arrêter l’action de sauvegarde/dépose et renvoyer une erreur à l’utilisateur final. Cela permet de s’assurer que les données sont cohérentes et prêtes avant d’entrer dans l’action de sauvegarde/dépose elle-même.

• Pendant la sauvegarde/le dépôt: Utilisez cette option si vous devez synchroniser les opérations de votre base de données avec un système externe, par exemple:
  • Lors de l’enregistrement d’une entité, écrire des données sur un disque, créer un document sur un Google Drive, etc.

Dans cet événement, vous pouvez renvoyer des erreurs en cas d’échec de l’arrêt de l’action. Ces erreurs peuvent ensuite être traitées dans l’événement suivant décrit ci-dessous.

• Après l’action d’enregistrement ou de dépôt : Ici, vous pouvez prendre des mesures concernant les erreurs potentielles soulevées pendant les actions de sauvegarde/dépose, par exemple:
  • Marquer un produit comme « à vérifier » parce qu’une erreur s’est produite pendant l’action de dépôt.

 

Grâce à ces événements, chaque étape de l’action de sauvegarde ou de dépôt peut avoir sa propre logique métier.

Ces événements sont déclenchés dès que l’opération de base de données est déclenchée à l’aide d’ORDA ou du serveur REST.

La vidéo ci-dessous montre le HDI en action.

 

Voyons cela en action avec des exemples

où implémenter les événements

Les événements ORDA doivent être implémentés dans la classe Entity en utilisant le mot-clé event dans la classe de l’entité.

Les événements de validation

Ces événements sont déclenchés avant l’ action de sauvegarde ou de dépôt et peuvent arrêter l’action en renvoyant une erreur. Dans ce cas, les autres événements décrits ci-dessous (à l’exception de l’événement after) ne sont pas déclenchés.

Ils peuvent être mis en œuvre :

• au niveau de l’attribut : pour vérifier la cohérence d’un attribut spécifique
• au niveau de l’entité : pour vérifier globalement le contenu de l’entité ou comparer des attributs

 

Exemple :

Dans cet exemple, dans la classe ProductsEntity, un événementvalidateSave a été implémenté pour l’attributmargin . L’utilisateur ne peut pas enregistrer un produit dont la marge est inférieure à 50%. Dans ce cas, une erreur est renvoyée afin d’arrêter l’action d’enregistrement et de fournir un retour d’information à l’utilisateur final.

// ProductsEntity class
//
// validateSave event at attribute level
Function event validateSave margin($event : Object) : Object
	
var $result : Object
	
//The user can't create a product whose margin is < 50%
If (This.margin<50)
	$result:={errCode: 1; message: "The validation of this product failed"; \
	extraDescription: {info: "The margin of this product ("+String(This.margin)+") is lower than 50%"}; seriousError: False}
End if 
return $result

La même logique s’applique à l’événementvalidateDrop. Par exemple, vous pouvez empêcher un utilisateur de déposer un produit dont le statut n’est pas « À supprimer ».

Les événements de sauvegarde et de dépôt

Ces événements sont déclenchés précisément lors de l’action de sauvegarde ou de dépôt et peuvent renvoyer des erreurs en cas de problème. Ils peuvent être mis en œuvre

• au niveau de l’attribut : pour surveiller les modifications apportées à des valeurs d’attribut spécifiques
• au niveau de l’entité : pour vérifier globalement le contenu de l’entité ou comparer des attributs

 

Exemple :

Dans cet exemple, dans la classe ProductsEntity, un événement desauvegarde a été mis en œuvre pour l’attributuserManualPath . Lorsqu’un produit est sauvegardé, le document du manuel d’utilisation est créé sur le disque et son chemin d’accès est stocké dans l’attribut userManualPath . Ces deux actions doivent être cohérentes.

En cas d’erreur lors de la création du manuel d’utilisation sur le disque, une erreur est renvoyée afin de fournir un retour d’information et d’être traitée dans l’événement suivant (afterSave) décrit ci-dessous.

Notez que le contenu du fichier est généré précédemment en dehors de l’événement d’enregistrement, car cela peut prendre du temps.

// ProductsEntity class
// saving event at attribute level
Function event saving userManualPath($event : Object) : Object
	
var $result : Object
var $userManualFile : 4D.File
var $fileCreated : Boolean
	
If (This.userManualPath#"")
	$userManualFile:=File(This.userManualPath)
				
	// The user manual document file is created on the disk
	// This may fail if no more space is available
	Try
            // The content of the file has been generated and stored in a map in Storage.docMap previously
	    $docInfo:=Storage.docMap.query("name = :1"; This.name).first()
            $userManualFile.setContent($docInfo.content)
	Catch
		// E.g.: No more space on disk
		$result:={errCode: 1; message: "Error during the save action for this product"; extraDescription: {info: "There is no available space on disk to store the user manual"}}
	End try
End if 
	
return $result

La même logique s’applique à un événement dedépôt. Par exemple, vous pouvez déposer le manuel de l’utilisateur en même temps que le produit.

les événements ultérieurs

Ces événements sont déclenchés après l’action d’enregistrement ou de dépôt. Comme l’action est terminée, ils ne peuvent pas renvoyer d’erreurs. Leur principal objectif est de déclencher la logique de gestion si un échec s’est produit au cours des événements précédents.

Si aucune erreur ne s’est produite, ils peuvent également gérer la logique post-succès – par exemple, l’envoi d’un courrier électronique de confirmation.

Ces événements ne sont mis en œuvre qu’au niveau de l’entité.

Exemple :

Dans cet exemple, un événementafterSave a été implémenté dans la classe ProductsEntity. Si l’attribut userManualPath n’a pas été correctement sauvegardé auparavant, sa valeur est réinitialisée pour être cohérente avec le manuel d’utilisation manquant sur le disque.

// ProductsEntity class
Function event afterSave($event : Object)
	
	If (($event.status.success=False) && ($event.status.errors=Null))  // $event.status.errors is filled if the error comes from the validateSave event
		
		// The userManualPath attribute has not been properly saved
		// Its value is reset
		If ($event.savedAttributes.indexOf("userManualPath")=-1)
			This.userManualPath:=""
			This.status:="KO"
		End if 
		
	End if 

La même logique s’applique à l’événementafterDrop –par exemple, lorsque le dépôt d’un produit échoue, vous pouvez enregistrer l’incident.

Remarque : les opérations longues doivent être évitées autant que possible dans les événements. Si possible, ces opérations doivent être mises en œuvre ailleurs.

N’attendez pas de mettre en œuvre des événements pour vous appuyer sur une forte intégrité des données.

Téléchargez l’IDH pour vous plonger dans les détails de la mise en œuvre des événements ORDA et regardez la vidéo ci-dessous pour avoir plus de détails sur l’exécution de l’IDH.

Ajouter le lien vidéo EN