Guide de démarrage sur %JSON et les entités dynamiques dans IRIS pour les utilisateurs débutants

Les entités dynamiques (objets et tableaux) dans IRIS sont extrêmement utiles lorsque vous devez transformer des données JSON en un modèle d'objet pour les stocker dans la base de données, comme dans les points de terminaison API REST hébergés dans IRIS. En effet, ces objets et tableaux dynamiques peuvent facilement servir de point de conversion d'une structure de données à une autre.

Entités dynamiques

Les objets dynamiques ressemblent beaucoup au modèle d'objet ObjectScript classique que vous obtenez lorsque vous créez une nouvelle instance d'un objet de classe, mais ils présentent quelques différences importantes:

• Les objets dynamiques sont sans type réel, hormis le fait qu'ils sont des DynamicObject ou des DynamicArray
• Ils ne peuvent pas hériter ou être transformés directement en objet de classe
• Ils sont beaucoup plus faciles à créer et sont fournis avec une multitude de fonctions intégrées permettant de les gérer et de les manipuler

La création d'un objet dynamique est très simple, il suffit de:

set obj = {}

Nous avons maintenant un objet dynamique "obj". Si vous avez déjà utilisé Javascript/Typescript, cela vous semblera très similaire. Ce lien avec Javascript devient très important lorsque nous aborderons les tableaux plus tard.

Avec notre nouvel objet dynamique, nous pouvons ajouter et manipuler les propriétés de cet objet comme nous le ferions avec des objets de classe, avec en plus la flexibilité de ne pas avoir à prédéfinir les propriétés que l'objet peut utiliser.

set obj.message = "This is a test message"
set obj.num = 4
set obj.test = 1

Jusque là, tout cela ressemble au modèle ObjectScript classique. Mais voici où les choses deviennent intéressantes:

set obj.subobj = {}

Nous avons maintenant créé un objet dynamique entièrement nouveau au sein de notre objet dynamique existant, avec toutes les mêmes fonctionnalités que ce dernier.

set obj.subobj.message = "This is a message on the sub-object."

Comme vous pouvez le constater, nous pouvons enchaîner la notation par points pour accéder aux propriétés des sous-objets d'un objet dynamique. Nous pouvons également attribuer des objets dynamiques en tant que sous-objets d'un objet existant:

set obj1 = {}
set obj1.message = "This is object 1"
set obj2 = {}
set obj2.message = "This is a different object, object 2"
// La propriété "subobj" de obj1 est définie pour l'objet complet obj2
set obj1.subobj = obj2

// Définissez "obj1" sur l'objet "obj" d'origine comme étant l'objet "obj1" dans son intégralité, qui
// comprend désormais également "obj2"
set obj.obj1 = obj1

Vous pouvez également utiliser les méthodes %Set(), %Get(), ey %Remove() sur l'objet (et les tableaux) pour manipuler les données stockées dans les propriétés de l'objet, ce qui est particulièrement utile pour les propriétés qui portent des noms longs. %Remove() est le seul moyen réel de supprimer une propriété ou un élément d'un objet ou d'un tableau dynamique.

Tableaux dynamiques

Nous avons déjà abordé le sujet des objets dynamiques, mais qu'en est-il des tableaux dynamiques?

Ils fonctionnent de manière très similaire aux objets. Pour créer un tableau dynamique:

set array = [1,2,"three",true]

Notez qu'au lieu de créer d'abord un tableau vide puis d'y ajouter des éléments, je lui ai attribué une valeur initiale. Cela peut également être fait avec des objets:

set test = {"message":"Test message","num":4}

Notez également que lorsque vous définissez des objets de cette manière, les noms des propriétés doivent être mis entre guillemets, sinon vous obtiendrez une erreur de syntaxe.

REMARQUE: Il est ESSENTIEL de comprendre que les tableaux dynamiques sont indexés à partir de 0, contrairement aux tableaux IRIS classiques qui sont indexés à partir de 1. Tous les tableaux dynamiques commencent à l'index 0.

Pour en revenir aux tableaux, une fois que vous disposez d'un tableau, vous avez accès à certaines méthodes standard pour interagir avec ce tableau, notamment:

• %Push(element) - Pour ajouter un nouvel élément à la fin du tableau existant
• %Pop() - Pour supprimer et renvoyer le dernier élément du tableau
• %Size() - Pour obtenir le nombre d'éléments actuellement présents dans le tableau
• %IsDefined(element number) - Pour indiquer si la clé donnée (numéro d'index du tableau) existe ou non dans le tableau.

 

Combinaison d'objets et de tableaux

Comme c'est la norme dans JSON, vous pouvez avoir un objet avec des propriétés contenant des tableaux et des tableaux contenant un ensemble d'objets. Comme indiqué ci-dessus lors de la définition de sous-objets d'autres objets, vous pouvez faire de même pour les tableaux dynamiques.

Ajout d'un tableau à un objet:

set obj = {"message":"This is a message"}
set array = [1,2,3,4,5]

set obj.array = array

Ajout d'un objet à un tableau:

set newobj = {"message1":"Message 1", "message2":"Message 2"}
set newarray = [1,2,3]
do newarray.%Push(newobj)

 

 Conversion et formatage JSON

Dans la réalité, ces entités sont très probablement assez volumineuses et il est difficile de se rappeler quelles propriétés se trouvent où et ce que contient un tableau.

Supposons, par exemple, que nous ayons le code suivant:

set testObj = {}
set testObj.message = "This is a test message"
set testObj.num = 4
set subobj = {}
set subobj.message = "This is a message on the sub-object."
set testObj.subobj = subobj

set array = [1,2,3,4,5]
set newobj = {"six":6}
do array.%Push(newobj)

set testObj.array = array

Il y a beaucoup de choses qui se passent ici, avec un mélange de tableaux et d'objets qui rendent difficile une représentation logique. Pour faciliter cela, nous pouvons utiliser la méthode intégrée %ToJSON() qui convertira l'objet en une chaîne JSON correctement formatée:

write testObj.%ToJSON()

Le résultat sera le suivant:

{"message":"This is a test message","num":4,"subobj":{"message":"This is a message on the sub-object."},"array":[1,2,3,4,5,{"six":6}]}

C'est un bon début, mais ce n'est pas très compréhensible. Jetons un coup d'œil à la classe %JSON.Formatter clas, qui dispose d'une méthode Format. Pour l'utiliser, nous pouvons créer une nouvelle instance de %JSON.Formatter, puis appeler la méthode Format qui prend la chaîne JSON en entrée.

set formatter = ##class(%JSON.Formatter).%New()
do formatter.Format(testObj.%ToJSON())

Ce qui nous donne un affichage JSON bien développé et correctement formaté:

{
  "message":"This is a test message",
  "num":4,
  "subobj":{
    "message":"This is a message on the sub-object."
  },
  "array":[
    1,
    2,
    3,
    4,
    5,
    {
      "six":6
    }
  ]
}

 

 

Comment utiliser les valeurs Vrai/Faux dans les objets dynamiques

En général, IRIS standard ne comprend pas les mots-clés "vrai" ou "faux". Pour représenter ces valeurs dans IRIS ObjectScript, nous devons utiliser 1 ou 0. 

Cependant, lorsque vous travaillez avec des entités dynamiques, vous entrez davantage dans le domaine de Javascript qui utilise "vrai" et "faux" sans problème, mais il existe certaines limitations.

Lorsque vous définissez un objet ou un tableau, si vous travaillez avec une valeur ou un ensemble de valeurs contenues entre [ ] ou { }, vous pouvez sans problème définir les propriétés ou les éléments comme "vrais" ou "fausses". Ces valeurs seront représentées comme la représentation Javascript de vrai et faux lorsqu'elles sont définies de cette manière. En dehors de ce contexte, IRIS convertira ces valeurs en 1 ou 0 lors de leur affichage dans un contexte ObjectScript.

Si, toutefois, vous utilisez la syntaxe à points pour définir manuellement une propriété sur un objet, vous ne pouvez utiliser que la syntaxe IRIS 1 ou 0, sinon IRIS générera une erreur de syntaxe. Cela a pour effet secondaire regrettable que la représentation Javascript considère 1 et 0 comme des valeurs valides, mais avec une signification très différente de celle qui est souhaitée.

Pour résoudre ce problème, vous pouvez utiliser la méthode %Set(key, default, type) qui prend la clé que vous souhaitez définir (propriété d'objet ou élément de tableau), une valeur par défaut facultative, et ensuite une valeur de type chaîne, qui peut être de type “null”, “string”, “number” (nulle, chaîne, nombre) ou, plus important encore, “boolean” (bouléen). Lorsque vous utilisez la méthode %Set() avec un type “boolean“, les valeurs 1 et 0 sont alors converties en représentation Javascript de “vrai” et “faux”. La méthode %Push() sur les tableaux dynamiques peut également prendre un paramètre type de la même manière. Les tableaux disposent également de la méthode %Set() pour définir une valeur d'un index de tableau donné.

Pour plus de détails, consultez la documentation sur %Set() et %Push().

 

Conversion d'une chaîne JSON en tableau ou objet dynamique

Tout cela est très bien lorsque nous voulons créer un objet JSON à envoyer en réponse à une requête API REST. Il suffit de configurer un objet dynamique avec toutes les propriétés appropriées, de l'écrire, et le système en aval le considérera comme un objet JSON approprié.

Mais qu'en est-il de la requête initiale qui a un corps POST au format JSON? Comment peut-elle être convertie à partir de la chaîne JSON en un tableau ou objet dynamique?

Tout comme la méthode %ToJSON() que nous avons utilisée précédemment, il existe également une méthode %FromJSON() qui prend la chaîne JSON comme paramètre et configure l'objet/le tableau selon la définition JSON.

Par exemple, si nous utilisons la même chaîne JSON que nous avons obtenue précédemment:

set jsonString = {"message":"This is a test message","num":4,"subobj":{"message":"This is a message on the sub-object."},"array":[1,2,3,4,5,{"six":6}]}

Nous pouvons convertir cela en un objet en procédant comme suit:

set obj = {}.%FromJSON(jsonString)

Cette opération définit la variable "obj" comme étant la représentation dynamique de l'objet à partir du JSON donné.

Supposons maintenant que nous ayons un tableau de livres à traiter:

[
    {
        "id": 1,
        "title": "ObjectScript for Dummies",
        "type": "paperback"
    },
    {
        "id": 2,
        "title": "Intermediate ObjectScript",
        "type": "paperback",
    },
    {
        "id": 3,
        "title": "Advanced ObjectScript",
        "type": "hardback",
    },
    {
        "id": 4,
        "title": "IRIS Embedded Python and You",
        "type": "paperback",
    },
]

 Comme nous obtenons ces données à partir d'un autre système, nous n'avons aucun moyen de savoir combien d'éléments cette liste contiendra lorsque nous la recevrons. Heureusement, les tableaux dynamiques et les objets sont itérables! 

Nous pouvons utiliser la méthode %GetIterator() associée à la méthode %GetNext(.key,.value) pour parcourir chaque objet du tableau ou chaque propriété de niveau supérieur d'un objet afin d'accéder aux données individuelles.

set booksJSON = set booksJSON = "[{""id"": 1,""title"": ""ObjectScript for Dummies"",""type"": ""paperback""},{""id"": 2,""title"": ""Intermediate ObjectScript"",""type"": ""paperback""},{""id"": 3,""title"": ""Advanced ObjectScript"",""type"": ""hardback""},{""id"": 4,""title"": ""IRIS Embedded Python and You"",""type"": ""paperback""}]"
set booksArray = [].%FromJSON(booksJSON)

set bookIter = booksArray.%GetIterator()

while bookIter.%GetNext(.key,.value) {
    write !,"Book ",value.id,": ",value.title," (",value.type,")"
}

Ce qui présente notre requête dans une liste d'affichage suivante très sympa:

Book 1: ObjectScript for Dummies (paperback)
Book 2: Intermediate ObjectScript (paperback)
Book 3: Advanced ObjectScript (hardback)
Book 4: IRIS Embedded Python and You (paperback)

 

Documentation

Pour plus d'informations sur la manière par laquelle ces entités peuvent être utilisées, veuillez consulter les guides IRIS et la documentation de classe:

Création et modification d'entités dynamiques
%Library.DynamicObject
%Library.DynamicArray