Utiliser %JSON.Adaptor

Dans cet article, je passe en revue la classe %JSON.Adaptor.

Cette classe est extrêmement utile pour exporter des données en JSON sérialisé, importer les objets JSON et les enregistrer dans un objet de classe.

Je vais commencer par les paramètres de l'addaptor %JSON. Les paramètres constituent un élément crucial des opérations d’importation et d’exportation JSON.

Si le nom de votre propriété n'est pas le même que le nom réel de la clé JSON pour l'exportation vers un externe ou pour charger les données dans un objet via l'importation, vous devez utiliser le paramètre %JSONFIELDNAME pour définir le nom d’alias. Si ce n'est pas le cas, cela produit un « champ inattendu » dans l'erreur de saisie au moment de l'importation.

Class Samples.TestJSONAdaptor Extends (%Persistent, %JSON.Adaptor)
{
    Property Name As %String(%JSONFIELDNAME = "First_Name");
ClassMethod ExportToJSON()
{
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(1)
    Do obj.%JSONExport() 
}
}
Output
LEARNING>Do ##class(Samples.TestJSONAdaptor).ExportToJSON()
{"First_Name":"myFirstName"}

Dans certaines situations, vous ne souhaiterez peut-être pas exposer ou ignorer certaines propriétés et propriétés définies par un mot clé interne (Remarque : la propriété sera exposée en JSON même si elle est définie comme un mot clé interne) dans la sortie JSON. Afin d'éviter que le terrain ne soit exposé au monde extérieur, vous pourriez utiliser le paramètre %JSONINCLUDE (valeur par défaut : INOUT)

1. 1. INPUTONLY - Il acceptera uniquement les entrées et n’exportera pas les données vers le monde extérieur.
   2. OUTPUTONLY - Il montre les valeurs du monde extérieur. Cependant, les valeurs Null ne peuvent être stockées que si ce paramètre a été mentionné dans cette propriété. Soyez prudent lorsque vous utilisez ce paramètre.
   3. NONE - La sortie ou l’entrée JSON ne doit jamais être stockée et récupérée.

Class Samples.TestJSONAdaptor Extends (%Persistent, %JSON.Adaptor)
{
    Property Name As %String(%JSONFIELDNAME = "First_Name");
    Property Phone As %Integer(%JSONINCLUDE = "INPUTONLY");
    Property IsActive As %Boolean(%JSONINCLUDE = "OUTPUTONLY");
ClassMethod ExportToJSON()
{
    #; JSON Export ouput
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(1)
    Do obj.%JSONExport() 
    #; output >> {"First_Name":"myFirstName","IsActive":true}
    #; Object ouput
    Write obj.Phone 
    #; output >> 9639639636
}

Output
LEARNING>Do ##class(Samples.TestJSONAdaptor).ExportToJSON()
 {"First_Name":"myFirstName","IsActive":true} 
9639639636

Généralement, l'instance ne contient aucune valeur dans les propriétés qui ne font pas partie de l'exportation JSON. Afin d'inclure ces propriétés dans l'export JSON, il est nécessaire d'inclure le paramètre %JSONNUL. La sortie aura la valeur par défaut de null. De plus, vous pouvez définir cette option de paramètre globalement dans votre définition de classe spécifique au lieu d'un champ spécifique. Cela sera applicable à tous les domaines.

Class Samples.TestJSONAdaptor Extends (%Persistent, %JSON.Adaptor)
{

    Property Name As %String(%JSONFIELDNAME = "First_Name");
    Property Phone As %Integer(%JSONINCLUDE = "INPUTONLY");
    Property IsActive As %Boolean(%JSONINCLUDE = "OUTPUTONLY");
    /// This field is available in JSON export
    Property JSONNULLDeclared As %String(%JSONNULL = 1);
    /// This field is not available in JSON export
    Property JSONNULLNotDeclared As %String;
ClassMethod ExportToJSON()
{
    #; JSON Export 
    #; JSONNULLDeclared and JSONNULLDeclared - values are empty in object
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(1)
    Do obj.%JSONExport() 
    #; output >> {"First_Name":myFirstName"","IsActive":true,"JSONNULLDeclared":null}
}
}
Output
LEARNING>Do ##class(Samples.TestJSONAdaptor).ExportToJSON()
{"First_Name":myFirstName"","IsActive":true,"JSONNULLDeclared":null}

Fondamentalement, les chaînes vides dans l'entrée JSON sont stockées sous $c(0). S'il y a des valeurs de script d'objets "" dans la propriété, elles ne seront pas affichées dans le JSON car %JSONIGNORENULL. Vérifiez que les conditions de chaîne vide sont remplies et exportez les données en activant %JSONIGNORENULL = 1. De plus, vous pouvez définir et utiliser cette option de paramètre globalement.

Class Samples.TestJSONAdaptor Extends (%Persistent, %JSON.Adaptor)
{

    Parameter %JSONNULL = 1; ///declared globally
    Property Name As %String(%JSONFIELDNAME = "First_Name");
    Property Phone As %Integer(%JSONINCLUDE = "INPUTONLY");
    Property IsActive As %Boolean(%JSONINCLUDE = "OUTPUTONLY");
    Property JSONNULLDeclared As %String(%JSONNULL = 1);
    Property JSONNULLNotDeclared As %String(%JSONIGNORENULL = 1);
ClassMethod ExportToJSON()
{
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(1)
    Do obj.%JSONExport() 
}
}
Output
LEARNING>Do ##class(Samples.TestJSONAdaptor).ExportToJSON()
{"First_Name":"myFirstName","IsActive":true,"JSONNULLDeclared":null,"JSONNULLDeclared":null,"JSONNULLNotDeclared":""}

De nombreuses classes de référence persistantes ou série sont liées dans une définition de classe. Ainsi, si vous exportez la classe au format JSON, tous les champs de la classe de référence sont également exportés au format JSON. Si vous préférez exporter uniquement les identifiants au lieu de la valeur entière, vous pouvez utiliser
%JSONREFERENCE.

Class Samples.TestJSONAdaptor Extends (%Persistent, %JSON.Adaptor)
{

    Parameter %JSONNULL = 1;
    Property Name As %String(%JSONFIELDNAME = "First_Name");
    Property Phone As %Integer(%JSONINCLUDE = "INPUTONLY");
    Property IsActive As %Boolean(%JSONINCLUDE = "OUTPUTONLY");
    Property JSONNULLDeclared As %String(%JSONNULL = 1);
    Property JSONNULLNotDeclared As %String(%JSONIGNORENULL = 1);
    Property SubClass As Samples.TestJSONAdaptor.SubClass(%JSONREFERENCE = "ID");
ClassMethod ExportToJSON()
{
    #; JSON Export 
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(1)
    Do obj.%JSONExport() 
}
}

output
LEARNING>d ##class(Samples.TestJSONAdaptor).ExportToJSON()
   {"First_Name":"Ashok","IsActive":true,"JSONNULLDeclared":null,"JSONNULLNotDeclared":"","SubClass":{"RefId":"a3295","TestProperty":"Test1"}} ; %JSONREFERENCE = "OBJECT"
LEARNING>d ##class(Samples.TestJSONAdaptor).ExportToJSON()
    {"First_Name":"myFirstName","IsActive":true,"JSONNULLDeclared":null,"JSONNULLDeclared":null,"JSONNULLNotDeclared":"","SubClass":"a321"} ; %JSONREFERENCE = "ID"

L'un des paramètres les plus cruciaux. Lorsque vous chargez l'objet JSON dans un objet de classe, une modification peut entraîner l'ajout de champs inattendus au JSON. Une erreur est générée si le paramètre %JSONIGNOREINVALIDFIELD n'est pas utilisé. L'activation de ce paramètre dans la définition de votre classe est très bénéfique.

///Before enabling %JSONIGNOREINVALIDFIELD
Class Samples.TestJSONAdaptor1 Extends (%Persistent, %JSON.Adaptor)
{
    Property Name As %String(%JSONFIELDNAME = "First_Name");
    Property IsActive As %Boolean;
ClassMethod TestJSONImport()
{
    Set json = {"Name":"MytestNewName","IsActive":true}
    Set obj = ..%New()
    Set st = obj.%JSONImport(json)
    If $$$ISERR(st) w $SYSTEM.OBJ.DisplayError(st)
    Write obj.%Save()
}
}
output
LEARNING>Do ##class(Samples.TestJSONAdaptor1).TestJSONImport()
 
ERROR #9404: Unexpected field in input, Name, using class base mapping.11{"First_Name":null}
LEARNING>

///After enabling %JSONIGNOREINVALIDFIELD
Class Samples.TestJSONAdaptor1 Extends (%Persistent, %JSON.Adaptor)
{
    Parameter %JSONIGNOREINVALIDFIELD As BOOLEAN = 1;
    Property Name As %String(%JSONFIELDNAME = "First_Name");
    Property IsActive As %Boolean;
ClassMethod TestJSONImport()
{
    Set json = {"Name":"MytestNewName", "Phone":9639631236, "IsActive":true, "unspecified":"" }
    Set obj = ..%New()
    Set st = obj.%JSONImport(json)
    If $$$ISERR(st) w $SYSTEM.OBJ.DisplayError(st)
    Write "Save : ",obj.%Save(),!
    Do obj.%JSONExport()
}
}
LEARNING>Do ##class(Samples.TestJSONAdaptor).TestJSONImport()
Save : 1
{"First_Name":null,"IsActive":null,"JSONNULLDeclared":null,"JSONNULLNotDeclared":"","SubClass":null,"GblCharStrm":null,"GblBinStrm":null,"Decimal":null}
 

 

De plus, certains des paramètres rarement utilisés comme %JSONENABLED. Si vous ne souhaitez pas générer le JSON, les générateurs de méthodes de classe Adaptor ne produisent pas de méthode exécutable, la valeur par défaut est 1.

Méthodes API natives pour l'adaptor JSON

%JSONImport

Il s'agit d'une méthode pour importer l'objet JSON dans l'objet de classe actuel. Cette méthode vérifie tous les types de données de propriétés avec le type de données clé-valeur JSON et déclare la valeur dans la propriété. Vous pouvez consulter les exemples de codes ci-dessus pour l'importation JSON.

• N'oubliez pas que le type de données JSON doit être le même que le type de données de propriété lors de l'importation de données. Sinon, cela lancera une erreurLes valeurs du type de données booléen 0 ou 1 ne sont pas identiques au type de données JSON Boolean true ou false. Donc, JSON doit avoir vrai/faux au lieu de 0 ou 1
• Utilisez toujours le bloc JSONFIELDNAME ou XDataMapping pour éviter une erreur inattendue de non-concordance de champ.
• Il est préférable d'utiliser le paramètre %JSONIGNOREINVALIDFIELD pour éviter une erreur de champ inattendue.

%JSONExport

Une méthode typique pour écrire le JSON sérialisé sur le périphérique actuel. Chaque fois que vous exportez et importez le nombre à virgule flottante avec des zéros à droite, ceux-ci ne font pas partie de la sortie JSON. Parce que les types numériques ObjectScript Decimal et IEEE Binary ne gardent pas la trace des zéros de fin. vous pouvez vous référer aux exemples de codes ci-dessus pour l'exportation JSON.

%JSONExportToStream

Des options d'exportation supplémentaires sont disponibles dans %JSON.Adaptor. Vous pouvez exporter votre JSON en tant qu'objet de flux, en utilisant %JSONExportToStream.

ClassMethod TestEXportToStream()
{
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(12)
    Do obj.%JSONExportToStream(.stream) 
    Write stream,!
    If $IsObject(stream) {
        Write stream.Read($$$MaxLocalLength)
    }
    Return
}

Output
EARNING>d ##class(Samples.TestJSONAdaptor).TestEXportToStream()
3@%Library.FileCharacterStream
{"First_Name":"TestNameSetMethod","IsActive":true,"JSONNULLDeclared":null,"JSONNULLNotDeclared":"","SubClass":"a3256","GblCharStrm":"Test string added as the global character stream","Decimal":12}

%JSONExportToString 

Vous pouvez exporter l'objet JSON sous forme de chaîne à l'aide de la méthode %JSONExportToString.

ClassMethod TestEXportToString()
{
    Set obj = ##class(Samples.TestJSONAdaptor).%OpenId(12)
    Do obj.%JSONExportToString(.string) 
    Write string
    Return
}
output
LEARNING>d ##class(Samples.TestJSONAdaptor).TestEXportToString()
{"First_Name":"TestSetMethod","IsActive":true,"JSONNULLDeclared":null,"JSONNULLNotDeclared":"","SubClass":"a3256","GblCharStrm":"Test string added as the global character stream","Decimal":12}