Skip to content

Commit dcb28fe

Browse files
jtsaltenjtsalten
committed
2 parents c3d49a3 + d348063 commit dcb28fe

1 file changed

Lines changed: 60 additions & 30 deletions

File tree

‎README.md‎

Lines changed: 60 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ _(Example assumes that your classname is `SampleApps.Serialize.MapTesting`, that
2424
From the terminal,in the name space where your class exists :
2525

2626
```javascript
27+
2728
Set obj = ##class(SampleApps.Serialize.MapTesting).%OpenId(1)
2829
Set objJSON = obj.Export()
2930
Do objJSON.%ToJSON()
@@ -62,60 +63,89 @@ Code | Category | Description
6263
During map generation, by default, the Adaptor sets export and Import conversion methods for dates and streams (which are exported as a stream in base64).
6364

6465
---
65-
**MAP0 structure**
66+
** MAPS / MAPSREV globals' structure**
67+
68+
^MAP("*classname*","*mapname*",_GroupType[1..6]_,"_Source Property Name_") = *List Element*
6669

67-
MAP0("*classname*",_GroupType[1..6]_,"_Source Property Name_") = *List Element*
6870
*List Element*:
69-
> Pos 1 *Target Property Name*
70-
> Pos 2
71-
> Pos 3
72-
> Pos 4
71+
72+
[1] *Target Property Name*
73+
74+
[2] *Convert Method*
75+
76+
[3] *Drill down*
77+
78+
[4] *Class of referenced object(s)*
79+
80+
[5] *Template Class that implement export/import logic*
81+
82+
[6] *Method Class to dispatch for export/import*
7383

7484
---
7585

7686
### How could we configure our mapping for serialization?
7787

78-
We can have as much mapping definitions for a class as we need. An easy way to start to define our customized maps is exporting the default MAP0 and importing it again with a different name, then we can make changes in the map regarding the properties that should be exported /imported, names, conversor methods to apply (***)
79-
(***) See OPNLIB.SERIALIZE.ADAPTOR.Serialize.Util library for tools to export/import maps, get / set property mappings,etc…)
88+
We can have as much mapping definitions for a class as we need. An easy way to start to define our customized maps is exporting the default MAP0 and importing it again with a different name, then we can make changes in the map regarding the properties that should be exported /imported, names, conversor methods to apply. To do this, we can modify directly in the global, or do it programatically (See `OPNLib.Serialize.Util` class for tools to export/import maps, get / set property mappings,etc…)
89+
90+
---
91+
**Example:**
92+
93+
```javascript
94+
set tClassName = "SampleApps.Serialize.MapTesting"
95+
;Assuming the class has only 1 map: MAP0, used in ^MAPS and ^MAPSREV
96+
set json = ##class(OPNLib.Serialize.Util).ExportMapsToJSON(tClassName)
97+
98+
;change name of map from MAP0 to MAP1
99+
set json.maps.%Get(0).map = "MAP1" //change mapname entry in corresponding to ^MAPS
100+
set json.maps.%Get(1).map = "MAP1" //change mapname entry corresponding to ^MAPSREV
80101

81-
We also have the possibility of changing a bit the way in which default map MAP0 is generated :
82-
• Change the name of default map.
83-
○ Use parameter EXPTDEFAULTMAP to indicate a name for default map before compiling the class
84-
• Excluding properties
85-
○ if we don't want to export some properties, we should include them in the parameter : EXPTEXCLUDEPROP before compiling the class (the properties will be in a comma separated list)
86-
• include object references
87-
○ Even when we decide not to drill down through referenced objects, we still have the chance to export the object reference itself if we set the parameter EXPTINCLUDEOREF to 1.
88-
• Drill down levels
89-
○ To indicate up to what number of levels we want the export mechanism to drill down through object references. 0 means no drill down. A positive number(n) means to drill down n times through the chain of references.
102+
;Overwrite map (2) of SampleApps.Serialize.MapTesting with map in object:json
103+
set tSC = ##class(OPNLib.Serialize.Util).ImportMapsFromJSON(json,2,tClassName)
90104

91-
Example:
105+
;Get settings of one of the properties. They are returned in a json object
106+
set propExprt = ##class(SampleApps.Serialize.MapTesting).GetMappedPropSettings("code","MAP1",tClassName,1)
92107

93-
<<<create MAP1 from MAP0 >>>
108+
;We change the targetPropertyName setting
109+
set $ListUpdate(propExprt.settings,1) = "codeAccepted"
110+
do ##class(SampleApps.Serialize.MapTesting).SetMappedPropSettings("code",propExprt,"MAP1",tClassName,1)
94111

95-
<<<USING MAP0 and MAP1 from the same object instance >>>
112+
;Now we open and object and export it using new mapping
113+
set obj = ##class(SampleApps.Serialize.MapTesting).%OpenId(1)
114+
set objJSON = obj.Export(,,,,"MAP1")
115+
do objJSON.%ToJSON()
96116

97-
How did it work the default mechanism?
117+
```
98118

99-
Both methods, export and Import will call the generated methods: exportStd and imoortStd respectively. These two methods will go through the global ^MAPS and ^MAPSREV respectively, looking for the properties to export /import and applying the required conversions.
100-
Both methods work over an already instantiated method. This is particularly important for import, as we can have an object in memory with some data already and import the rest of the data from a serialized object. The import mechanism will replace with the new content the properties contained in the serialization but will preserve other properties already set in the instance that are not included in the serialization that we import.
119+
We also have the possibility of changing a bit the way in which default map `MAP0` is generated :
120+
* Change the name of default map.
121+
* Use parameter `EXPTDEFAULTMAP` to indicate a name for default map before compiling the class
122+
* Excluding properties
123+
* if we don't want to export some properties, we should include them (comma separated list) in the parameter : `EXPTEXCLUDEPROP` before compiling the class
124+
* include object references
125+
* Even when we decide not to drill down through referenced objects, we still have the chance to export the object reference itself if we set the parameter `EXPTINCLUDEOREF` to 1.
126+
* Drill down levels
127+
* Use `EXPTDRILLDOWN`To indicate up to what number of levels that the export/import logic should follow through object references. 0 means no drill down. A positive number(n) means to drill down n times through the chain of references.
101128

102-
Example:
129+
## How did it work the default mechanism?
103130

104-
<< import a JSON with just some properties in an object where we already have some others set >>>
131+
Both methods, `Export` and `Import` will call the generated methods: `exportStd` and `importStd` respectively. These two methods will go through the global `^MAPS` and `^MAPSREV` respectively, looking for the properties to export /import and applying the required conversions.
132+
Both methods work over an already instantiated method. This is particularly interesting for import, as we can have an object in memory with some data already and import the rest of the data from a serialized object. The import mechanism will replace with the new content the properties contained in the serialization but will preserve other properties already set in the instance that are not included in the serialization that we import.
105133

106-
This way of working give us the flexibility of using different mappings using the same autogenerated code but it can have a penalty in performance if we use it massively in loops or in very high concurrency use cases. Anyway,better test in such scenarios.
134+
This way of working give us the flexibility of using different mappings using the same autogenerated code but it can have a penalty in performance if we use it massively in loops or in very high concurrency use cases. Anyway, better test in such scenarios.
107135

108-
Some considerations about performance
136+
## Some considerations about performance
109137

110-
As we already mentioned, the default mechanism resolve the mapping sets at real time, trasversing a global to set the properties to export/import targets. That means that this mechanism will always be slower than if we already had that settings resolved at compile time. In order to provide that functionality, we can use the Template classes.
138+
As it was already mentioned, the default mechanism resolve the mapping sets at real time, trasversing a global to set the properties to export/import targets. That means that this mechanism will always be slower than if we already had that settings resolved at compile time. In order to provide that functionality, we can use the Template classes.
111139

112-
What are the template classes for?
140+
## What are the template classes for?
113141

114-
The templates classes allow us to generate the logic to export /import at compile time.
142+
The templates classes allow us to generate the logic to export/import at compile time.
115143
This have benefits over performance but comes at the price of having to use a different class for each type of serialization format and mapping.
116144

117145
Anyway, the primary class is not affected and doesn't have to be changed no matter how many templates define to handle the serialization of its objects.
118146

147+
148+
119149
Example :
120150

121151
<<< define and use different template classes, for different maps in JSON and also for different serialization (CSV)

0 commit comments

Comments
 (0)