第一章 Caché JSON 简介

简介

Caché 和 Caché ObjectScript现在提供了对JSON的集成支持，一组快速、简单、强大的新特性允许像处理对象或表一样轻松地处理JSON数据结构:

• 两个新类%Library.DynamicObject 和 %Library.DynamicArray 。提供一种简单、有效的方法来封装和处理标准JSON数据结构。这些类的实例称为动态实体。
• 使用新的JSON Caché ObjectScript语法，可以使用标准的Caché ObjectScript赋值语句而不是方法调用来在运行时创建和更改动态实体。对象属性和数组元素的值可以指定为JSON字符串文本，也可以指定为Caché ObjectScript动态表达式。
• 动态实体包含用于JSON序列化(在动态实体和规范JSON格式之间进行转换)、迭代、数据类型、创建/读取/更新/删除操作和其他有用功能的方法。

Caché JSON功能

下面是一些新的JSON功能的例子:

在运行时创建和操作动态实体

可以创建动态实体，并定义一个任意的模式为他们在运行时:

/// d ##class(PHA.OP.MOB.Test).TestJson()
ClassMethod TestJson()
{
   set dynObject2 = ##class(%DynamicObject).%New()
   set dynObject2.SomeNumber = 42
   set dynObject2.SomeString = "a string"
    
   set dynObject1 = ##class(%DynamicObject).%New()
   set dynObject1.SomeNumber = 42
   set dynObject1.SomeString = "a string"
   w dynObject1.%ToJSON(),!
   set dynObject1.SomeArray = ##class(%DynamicArray).%New()
   set dynObject1.SomeArray."0" = "an array element"
   set dynObject1.SomeArray."1" = 123
   set dynObject1.SomeArray."2" =dynObject2
   w dynObject1.%ToJSON(),!
}

DHC-APP>d ##class(PHA.OP.MOB.Test).TestJson()
{"SomeNumber":42,"SomeString":"a string"}
{"SomeNumber":42,"SomeString":"a string","SomeArray":["an array element",123,{"SomeNumber":42,"SomeString":"a string"}]}
 
DHC-APP>

使用字符串JSON构造函数创建动态实体

还可以通过分配一个文字JSON字符串来创建一个动态实体。文字JSON构造函数{}和[]可以用来代替%New()构造函数。例如，可以使用set x=[]而不是set x=##class(%DynamicArray)来创建一个动态数组。与%New()不同，文字JSON构造函数也可以接受指定属性或元素的JSON文字字符串。这意味着可以用这些简单的赋值语句创建一个与前一个例子中的dynObject1相同的对象:

   set dynObject2 = {"SomeNumber":42,"SomeString":"a string"}
   set dynObject2.SomeArray = ["an array element",123]

本例为每个构造函数使用了一个语句，但是数组构造函数可以简单地嵌套在对象构造函数中。

为了证明dynObject1和dynObject2是相同的，我们可以将它们显示为由%ToJSON()方法返回的序列化JSON字符串:

   write "object 1: "_dynObject1.%ToJSON(),!,"object 2: "_dynObject2.%ToJSON()

object 1: {"SomeNumber":42,"SomeString":"a string","SomeArray":["an array element",123]}
object 2: {"SomeNumber":42,"SomeString":"a string","SomeArray":["an array element",123]}

使用Caché动态表达式定义值

包含在文字构造函数{}和[]中的文本必须使用有效的JSON语法，但有一个例外。对于元素或属性的值，可以使用圆括号中的Caché表达式，而不是JSON文本。这个ObjectScript动态表达式(相当于set语句的右侧)将在运行时计算并转换为有效的JSON值。本例中的动态表达式包含对Caché $ZDATE函数的调用:

set dynObj = { "Date":($ZD($H,3)) }

当我们检索dynObject.Date时，动态表达式的计算值就会显示出来。

 write "Value of dynamic expression is: "_dynObject.Date

Value of dynamic expression is: 2016-07-27

/// d ##class(PHA.OP.MOB.Test).TestJson()
ClassMethod TestJson()
{
   set dynObject2 = ##class(%DynamicObject).%New()
   set dynObject2.SomeNumber = 42
   set dynObject2.SomeString = "a string"
   set dynObj = { "Date":($ZD($H,3)) }
     
   set dynObject1 = ##class(%DynamicObject).%New()
   set dynObject1.SomeNumber = 42
   set dynObject1.SomeString = "a string"
   w dynObject1.%ToJSON(),!
   set dynObject1.SomeArray = ##class(%DynamicArray).%New()
   set dynObject1.SomeArray."0" = "an array element"
   set dynObject1.SomeArray."1" = 123
   set dynObject1.SomeArray."2" =dynObject2
   set dynObject1.SomeArray."2" =dynObj
   w dynObject1.%ToJSON(),!
}

DHC-APP>d ##class(PHA.OP.MOB.Test).TestJson()
{"SomeNumber":42,"SomeString":"a string"}
{"SomeNumber":42,"SomeString":"a string","SomeArray":["an array element",123,{"Date":"2020-02-09"}]}

在动态实体和规范JSON字符串之间进行转换

动态实体有序列化方法，允许将对象转换为JSON字符串。在下面的示例中，使用文字构造函数创建动态对象，并调用对象的%ToJSON()方法将其序列化为myJSONstring:

set myJSONstring = {"aNumber":(21*2),"aDate":($ZD($H,3)),"anArray":["string",123]}.%ToJSON()

这个序列化的JSON对象可以像任何其他字符串一样存储和检索。类方法%FromJSON()可以从任何源获取有效的JSON字符串并将其转换为动态对象。下面的代码将myJSONstring反序列化为动态对象myObject，并使用%ToJSON()来显示它:

 set myObject = ##class(%DynamicAbstractObject).%FromJSON(myJSONstring)
   write myObject.%ToJSON()

{"aNumber":42,"aDate":"2016-08-29","anArray":["string",123]}

链动态实体法

一些动态实体方法可以被链接。本例创建了一个包含两个元素的动态数组，然后将%Push()方法链接起来，以向数组的末尾添加另外三个元素。最后一个链调用%ToJSON()显示序列化的字符串:

 set dynArray = ["a","b"]
   write dynArray.%Push(12).%Push({"a":1,"b":2}).%Push("final").%ToJSON()

["a","b",12,{"a":1,"b":2},"final"]

迭代和数据类型发现

还提供了动态实体方法，用于迭代和数据类型发现等目的。这个例子创建了两个JSON字符串，将其中一个反序列化为dynEntity(任何一个都可以)，然后为dynEntity获取一个迭代器:

    set arrayStr = [12,"some string",[1,2]].%ToJSON()
    set objectStr = {"a":12,"b":"some string","c":{"x":1,"y":2},"d":true,"e":1.1}.%ToJSON()
    set dynEntity = {}.%FromJSON(objectStr)
    set itr = dynEntity.%GetIterator()
    while itr.%GetNext(.key,.val) {write !,key_": "_"/"_val_"/, type: "_dynEntity.%GetTypeOf(key)}

对于while循环的每次迭代，%GetNext()将在key中返回属性名或数组索引，在val中返回成员值。

   while itr.%GetNext(.key,.val) {write !,key_": "_"/"_val_"/, type: "_dynEntity.%GetTypeOf(key)}

a: /12/, type: number
b: /some string/, type: string
c: /5@%Library.DynamicObject/, type: object
d: /1/, type: boolean
e: /1.1/, type: number

动态实体方法概述

动态实体方法可分为以下几类:

创建、读取、更新、删除

• %Set() 可以更改现有动态实体成员(属性或元素)的值，也可以创建新成员并为其赋值。
• %Remove() 删除现有成员
• %Get() 检索成员的值

迭代和数组

• %GetIterator() 返回一个迭代器，其中包含指向动态实体每个成员的指针。
• %GetNext() 返回迭代器标识的成员的键和值，并将光标移到下一个成员。
• %Size() 返回成员数(包括数组中未分配的元素)。
• %IsDefined() 测试成员是否具有指定的值。

堆栈的功能

• %Push() 将新元素添加到动态数组的末尾。
• %Pop() 删除数组的最后一个元素并返回其值。这些方法不适用于动态对象，因为对象属性不是按可预测的顺序存储的。

JSON序列化和反序列化

• %FromJSON() 将JSON字符串转换为动态实体。
• %ToJSON() 将动态实体序列化为规范JSON字符串。

数据类型信息

• %GetTypeOf() 返回一个字符串，该字符串指示指定成员值的数据类型。%Set()和%Push()提供一个可选的第三个参数来显式地指定值的数据类型。