Streaming JSON: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		[[JSON]] (JavaScript Object Notation) is a text-based, standardized data format. As the name implies, JSON documents are valid JavaScript code and can be directly converted into JavaScript objects. However, JSON can be used for data exchange regardless of the programming language used.
2	2
3	3		This tutorial explains how to load JSON data into a Free Pascal program and process it there. It also explains how to convert data from the program into JSON (eg to send it to a web browser).
4	4
5	5		## General requirements
6	6
7	7		Loading and storing (streaming) objects is done with the fpjsonrtti unit. It also makes sense to use the Classes unit (see below for details).
8	8
9	9		The uses statement should therefore contain at least these two units:
10	10
11	11		``` pascal
12	12		uses Classes, fpjsonrtti;
13	13		```
14	14
15	15		Currently (May 2014) there are some differences between Free Pascal's streaming system and JSON:
16	16
17	17		- JSON is a case-sensitive data format. It follows that the properties of the Free Pascal objects must be written in the same case as the JSON properties.
18	18		- No properties can be defined with DefineProperties. No references to methods (event handlers) can be saved.2
19	19		- [[TCollection]] and [[TStrings]] can used as a replacements for arrays.
20	20
21	21		Demo programs are provided with Free Pascal Compiler source code in the `packages/fcl-json/examples` directory.
22	22
23	23		This JSON structure is used in the examples which follow:
24	24
25	25		``` JavaScript
26	26		{
27	27		"id" : 123, // an integer
28	28		"obj" : { "name": "Hello world!" }, // an object
29	29		"coll" : [ { "name": "Object 1" }, { "name": "Object 2" } ], // two objects in a TCollection
30	30		"strings": [ "Hello 1", "Hello 2" ] // a string list
31	31		}
32	32		```
33	33
34	34		It can be defined in your Free Pascal program using a constant assignment as follows:
35	35
36	36		``` pascal
37	37		const JSON_TESTDATA =
38	38		'{'+LineEnding+
39	39		' "id": 123,'+LineEnding+
40	40		' "obj": { "name": "Hello world!" },'+LineEnding+
41	41		' "coll": [ { "name": "Object 1" }, { "name": "Object 2" } ],'+LineEnding+
42	42		' "strings": [ "Hello 1", "Hello 2" ]'+LineEnding+
43	43		'}';
44	44		```
45	45
46	46		## Data Structure
47	47
48	48		The base class for the data is [[TPersistent]] from the Classes unit, [[Runtime Type Information (RTTI)\|runtime type information (RTTI)]] is created for it and all subclasses. These are essential for streaming. Since fpjsonrtti does not integrate into the streaming system, any other class translated with the compiler switch {\$M+} can also be used.
49	49
50	50		All properties to be read must be declared as a [[Property\|property]] in the [[Published\|published]] section of the class. As a rule, you can use read and write to refer directly to a data field (the variable). If you want, you can of course use getter and setter methods.
51	51
52	52		The following class definition results from the JSON structure:
53	53
54	54		``` pascal
55	55		type
56	56		TNameObject = class(TCollectionItem) // class for the 'obj' property and TCollection
57	57		private
58	58		fName: String;
59	59		published
60	60		property name: String read fName write fName;
61	61		end;
62	62
63	63		TBaseObject = class(TPersistent) // class for the entire JSON structure
64	64		private
65	65		fid: Integer;
66	66		fObj: TNameObject;
67	67		fColl: TCollection;
68	68		fStrings: TStrings;
69	69		public
70	70		constructor Create;
71	71		destructor Destroy; override;
72	72		published // all properties must be published
73	73		property id: Integer read fid write fid;
74	74		property obj: TNameObject read fObj write fObj;
75	75		property coll: TCollection read fColl;
76	76		property strings: TStrings read fStrings;
77	77		end;
78	78		```
79	79
80	80		The `TNameObject` class was derived from [[TCollectionItem]]. This means that it can be used both for the obj property and in the collection. If this is not desired, then two different classes must be defined here.
81	81
82	82		The TCollection and the string list must be created in the constructor of the TBaseObject class and released in the destructor.
83	83
84	84		``` pascal
85	85		constructor TBaseObject.Create;
86	86		begin
87	87		// Create Collection and StringList
88	88		fColl := TCollection.Create(TNameObject);
89	89		fStrings := TStringList.Create;
90	90		fObj := TNameObject.Create(nil);
91	91		end;
92	92
93	93		destructor TBaseObject.Destroy;
94	94		begin
95	95		// Release Collection and StringList
96	96		fColl.Free;
97	97		fStrings.Free;
98	98		fObj.Free;
99	99		inherited Destroy;
100	100		end;
101	101		```
102	102
103	103		If you do not want any more functionality in the data classes, their definition is now complete.
104	104
105	105		## Load JSON
106	106
107	107		With the method `Procedure JSONToObject(Const JSON : TJSONStringType; AObject : TObject);` in the [[TJSONDeStreamer]] class you can assign JSON data directly to an existing object. Before you call the method, you must create TJSONDeStreamer and the target object.
108	108
109	109		The following method loads the data from the JSON structure `JSON_TESTDATA` in the object o and then outputs the current values of the properties to the console.
110	110
111	111		``` pascal
112	112		procedure DeStreamTest;
113	113		var
114	114		DeStreamer: TJSONDeStreamer;
115	115		o: TBaseObject;
116	116		no: TNameObject;
117	117		s: String;
118	118		begin
119	119		WriteLn('DeStream test');
120	120		WriteLn('======================================');
121	121
122	122		// Create the DeStreamer object and target object
123	123		DeStreamer := TJSONDeStreamer.Create(nil);
124	124		o := TBaseObject.Create;
125	125		try
126	126		// Load JSON data into object o
127	127		DeStreamer.JSONToObject(JSON_TESTDATA, o);
128	128		// output ID
129	129		WriteLn(o.id);
130	130		// output object name
131	131		WriteLn(o.obj.name);
132	132		// output the names of all objects
133	133		for TCollectionItem(no) in o.coll do
134	134		Writeln(no.name);
135	135		// output all strings
136	136		for s in o.strings do
137	137		WriteLn(s);
138	138
139	139		// Cleanup
140	140		finally
141	141		o.Destroy;
142	142		DeStreamer.Destroy;
143	143		end;
144	144		end;
145	145		```
146	146
147	147		## Saving JSON
148	148
149	149		The class [[TJSONStreamer]] is used to convert an object into JSON text. Here the method `Function ObjectToJSONString(AObject : TObject) : TJSONStringType;` is used.
150	150
151	151		In the following procedure, an object is created, filled with the test data, and then converted to JSON. The JSON text is output on the console. The order in which the properties are output cannot be specified.
152	152
153	153		``` pascal
154	154		procedure StreamTest;
155	155		var
156	156		Streamer: TJSONStreamer;
157	157		o: TBaseObject;
158	158		JSONString: String;
159	159		begin
160	160		WriteLn('Stream test');
161	161		WriteLn('======================================');
162	162
163	163		Streamer := TJSONStreamer.Create(nil);
164	164		o := TBaseObject.Create;
165	165		try
166	166		// Setup data
167	167		o.id := 123;
168	168		o.obj.name := 'Hello world!';
169	169		TNameObject(o.coll.Add).name := 'Object 1';
170	170		TNameObject(o.coll.Add).name := 'Object 2';
171	171		o.strings.Add('Hello 1');
172	172		o.strings.Add('Hello 2');
173	173
174	174		Streamer.Options := Streamer.Options + [jsoTStringsAsArray]; // Save strings as JSON array
175	175		// convert to JSON and output to console
176	176		JSONString := Streamer.ObjectToJSONString(o);
177	177		WriteLn(JSONString);
178	178
179	179		// Cleanup
180	180		finally
181	181		o.Destroy;
182	182		Streamer.Destroy;
183	183		end;
184	184		end;
185	185		```
186	186
187	187		## Custom properties
188	188
189	189		Now that we can save and load to JSON, we can as well customize how the property is saved. By default a TColor (TGraphicsColor) is saved as a number, but for example we want to make it a string, so is more human readable.
190	190
191	191		This example uses BGRABitmap library, that has a function to convert from string to color easily. The streamed control in this case is a button control from BGRAControls package.
192	192
193	193		This customizes how TColor is saved and loaded.
194	194
195	195		Saving code:
196	196
197	197		``` pascal
198	198		procedure TForm1.Button1Click(Sender: TObject);
199	199		var
200	200		Streamer: TJSONStreamer;
201	201		JSONString: String;
202	202		begin
203	203		Streamer := TJSONStreamer.Create(nil);
204	204		try
205	205		Streamer.OnStreamProperty:=@OnStreamProperty;
206	206		JSONString := Streamer.ObjectToJSONString(BCButton1.StateNormal);
207	207		Memo1.Lines.Text := JSONString;
208	208		finally
209	209		Streamer.Destroy;
210	210		end;
211	211		end;
212	212		```
213	213
214	214		``` pascal
215	215		procedure TForm1.OnStreamProperty(Sender: TObject; AObject: TObject;
216	216		Info: PPropInfo; var Res: TJSONData);
217	217		var
218	218		bgracolor: TBGRAPixel;
219	219		begin
220	220		if (Info^.PropType^.Name = 'TGraphicsColor') then
221	221		begin
222	222		bgracolor := ColorToBGRA(TColor(GetPropValue(AObject, Info, False)));
223	223		Res.Free;
224	224		Res := TJSONString.Create('rgb('+IntToStr(bgracolor.red)+','+IntToStr(bgracolor.green)+','+IntToStr(bgracolor.blue)+')');
225	225		end;
226	226		end;
227	227		```
228	228
229	229		Loading code:
230	230
231	231		``` pascal
232	232		procedure TForm1.Button2Click(Sender: TObject);
233	233		var
234	234		DeStreamer: TJSONDeStreamer;
235	235		s: String;
236	236		begin
237	237		DeStreamer := TJSONDeStreamer.Create(nil);
238	238		try
239	239		DeStreamer.OnRestoreProperty:=@OnRestoreProperty;
240	240		DeStreamer.JSONToObject(Memo1.Lines.Text, BCButton1.StateNormal);
241	241		finally
242	242		DeStreamer.Destroy;
243	243		end;
244	244		end;
245	245		```
246	246
247	247		``` pascal
248	248		procedure TForm1.OnRestoreProperty(Sender: TObject; AObject: TObject;
249	249		Info: PPropInfo; AValue: TJSONData; var Handled: Boolean);
250	250		var
251	251		bgracolor: TBGRAPixel;
252	252		begin
253	253		Handled := False;
254	254		if (Info^.PropType^.Name = 'TGraphicsColor') then
255	255		begin
256	256		Handled := True;
257	257		bgracolor := StrToBGRA(AValue.AsString);
258	258		SetPropValue(AObject, Info, BGRAToColor(bgracolor));
259	259		end;
260	260		end;
261	261		```
262	262
263	263		## Conclusion
264	264
265	265		With the knowledge presented, simple and complex JSON data structures can be loaded into Free Pascal programs. Should any pre- or post-processing of the JSON data be necessary, the text data can be first loaded from the [[jsonparser]] unit into a JSON data structure using the [[TJSONParser]] class and then manipulated as desired with the [[fpJSON]] unit.
266	266
267	267		The Options property of the TJSONStreamer class can be used to control how the output maps its own data structures in JSON.
268	268
269	269		## See Also
270	270
271	271		- [[JSON]]
272	272		- [[fcl-json]]
273	273		- [[Streaming components]]
274	274
275	275		## Notes & References
276	276
277		-	~~1. <div id="ref1">~~
278		-
279		-	~~<http://lists.freepascal.org/fpc-pascal/2013-January/036254.html>~~
280		-
281		-	~~</div>~~
	277	+	1. <http://lists.freepascal.org/fpc-pascal/2013-January/036254.html>
282	278
283	279		2. \<div id="ref2\>http://lists.lazarus.freepascal.org/pipermail/lazarus/2011-January/058878.html
284		-	~~</div>~~
285	280
286	281		---
287	282		From the Free Pascal wiki, page "Streaming JSON", as it stood on 2022-08-06 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history