1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Copyright 2014 Alexis Laferrière <alexis.laf@xymus.net>
5 # Licensed under the Apache License, Version 2.0 (the "License");
6 # you may not use this file except in compliance with the License.
7 # You may obtain a copy of the License at
9 # http://www.apache.org/licenses/LICENSE-2.0
11 # Unless required by applicable law or agreed to in writing, software
12 # distributed under the License is distributed on an "AS IS" BASIS,
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 # See the License for the specific language governing permissions and
15 # limitations under the License.
17 # Handles serialization and deserialization of objects to/from JSON
21 # `JsonSerializer` write Nit objects that subclass `Serializable` to JSON,
22 # and `JsonDeserializer` can read them. They both use meta-data added to the
23 # generated JSON to recreate the Nit instances with the exact original type.
25 # For more information on Nit serialization, see: ../serialization/README.md
29 # The attribute `JsonSerializer::plain_json` triggers generating plain and
30 # clean JSON. This format is easier to read for an human and a non-Nit program,
31 # but it cannot be fully deserialized. It can still be read by services from
32 # `json::static` and `json::dynamic`.
34 # A shortcut to this service is provided by `Serializable::to_plain_json`.
39 # import json::serialization
45 # var year_of_birth: Int
46 # var next_of_kin: nullable Person
49 # var bob = new Person("Bob", 1986)
50 # var alice = new Person("Alice", 1978, bob)
52 # assert bob.to_plain_json == """
53 # {"name": "Bob", "year_of_birth": 1986, "next_of_kin": null}"""
55 # assert alice.to_plain_json == """
56 # {"name": "Alice", "year_of_birth": 1978, "next_of_kin": {"name": "Bob", "year_of_birth": 1986, "next_of_kin": null}}"""
60 import ::serialization
61 private import ::serialization
::engine_tools
64 # Serializer of Nit objects to Json string.
68 # Target writing stream
71 # Write plain JSON? easier to read but does not support Nit deserialization
73 # If `false`, the default, serialize to support deserialization:
75 # * Write meta-data, including the types of the serialized objects so they can
76 # be deserialized to their original form using `JsonDeserializer`.
77 # * Use references when an object has already been serialized so to not duplicate it.
78 # * Support cycles in references.
79 # * Preserve the Nit `Char` type as an object because it does not exist in JSON.
80 # * The generated JSON is standard and can be read by non-Nit programs.
81 # However, some Nit types are not represented by the simplest possible JSON representation.
82 # With the added meta-data, it can be complex to read.
84 # If `true`, serialize for other programs:
86 # * Nit objects are serialized to pure and standard JSON so they can
87 # be easily read by non-Nit programs and humans.
88 # * Nit objects are serialized for every references, so they can be duplicated.
89 # It is easier to read but it creates a larger output.
90 # * Does not support cycles, will replace the problematic references by `null`.
91 # * Does not serialize the meta-data needed to deserialize the objects
92 # back to regular Nit objects.
93 # * Keys of Nit `HashMap` are converted to their string reprensentation using `to_s`.
94 var plain_json
= false is writable
96 # List of the current open objects, the first is the main target of the serialization
98 # Used only when `plain_json == true` to detect cycles in serialization.
99 private var open_objects
= new Array[Object]
101 # Has the first attribute of the current object already been serialized?
103 # Used only when `plain_json == true`.
104 private var first_attribute
= false
106 redef fun serialize
(object
)
108 if object
== null then
112 for o
in open_objects
do
113 if object
.is_same_serialized
(o
) then
120 open_objects
.add object
123 first_attribute
= true
124 object
.serialize_to_json
self
125 first_attribute
= false
127 if plain_json
then open_objects
.pop
131 redef fun serialize_attribute
(name
, value
)
133 if not plain_json
or not first_attribute
then
135 first_attribute
= false
144 redef fun serialize_reference
(object
)
146 if not plain_json
and refs_map
.has_key
(object
) then
147 # if already serialized, add local reference
148 var id
= ref_id_for
(object
)
149 stream
.write
"\{\"__kind\
": \"ref\
", \"__id\
": "
158 # Map of references to already serialized objects.
159 private var refs_map
= new StrictHashMap[Serializable,Int]
161 # Get the internal serialized reference for this `object`.
162 private fun ref_id_for
(object
: Serializable): Int
164 if refs_map
.has_key
(object
) then
165 return refs_map
[object
]
167 var id
= refs_map
.length
168 refs_map
[object
] = id
174 # Deserializer from a Json string.
175 class JsonDeserializer
178 # Json text to deserialize from.
179 private var text
: Text
181 # Root json object parsed from input text.
182 private var root
: nullable Jsonable is noinit
184 # Depth-first path in the serialized object tree.
185 private var path
= new Array[JsonObject]
187 # Map of references to already deserialized objects.
188 private var id_to_object
= new StrictHashMap[Int, Object]
190 # Last encountered object reference id.
192 # See `id_to_object`.
193 var just_opened_id
: nullable Int = null
196 var root
= text
.parse_json
197 if root
isa JsonObject then path
.add
(root
)
201 redef fun deserialize_attribute
(name
)
203 assert not path
.is_empty
204 var current
= path
.last
206 assert current
.keys
.has
(name
)
207 var value
= current
[name
]
209 return convert_object
(value
)
212 # This may be called multiple times by the same object from constructors
213 # in different nclassdef
214 redef fun notify_of_creation
(new_object
)
216 var id
= just_opened_id
217 if id
== null then return # Register `new_object` only once
218 id_to_object
[id
] = new_object
221 # Convert from simple Json object to Nit object
222 private fun convert_object
(object
: nullable Object): nullable Object
224 if object
isa JsonObject then
225 assert object
.keys
.has
("__kind")
226 var kind
= object
["__kind"]
229 if kind
== "ref" then
230 assert object
.keys
.has
("__id")
231 var id
= object
["__id"]
234 assert id_to_object
.has_key
(id
)
235 return id_to_object
[id
]
239 if kind
== "obj" then
240 assert object
.keys
.has
("__id")
241 var id
= object
["__id"]
244 assert object
.keys
.has
("__class")
245 var class_name
= object
["__class"]
246 assert class_name
isa String
248 assert not id_to_object
.has_key
(id
) else print
"Error: Object with id '{id}' of {class_name} is deserialized twice."
254 var value
= deserialize_class
(class_name
)
255 just_opened_id
= null
264 if kind
== "char" then
265 assert object
.keys
.has
("__val")
266 var val
= object
["__val"]
267 assert val
isa String
269 if val
.length
!= 1 then print
"Error: expected a single char when deserializing '{val}'."
271 return val
.chars
.first
274 print
"Malformed Json string: unexpected Json Object kind '{kind or else "null"}'"
278 if object
isa Array[nullable Object] then
279 # special case, isa Array[nullable Serializable]
280 var array
= new Array[nullable Serializable]
281 for e
in object
do array
.add e
.as(nullable Serializable)
288 redef fun deserialize
do return convert_object
(root
)
291 redef class Serializable
292 private fun serialize_to_json
(v
: JsonSerializer)
294 var id
= v
.ref_id_for
(self)
296 if not v
.plain_json
then
297 v
.stream
.write
"\"__kind\
": \"obj\
", \"__id\
": "
298 v
.stream
.write id
.to_s
299 v
.stream
.write
", \"__class\
": \""
300 v.stream.write class_name
307 # Serialize this object to plain JSON
309 # This is a shortcut using `JsonSerializer::plain_json`,
310 # see its documentation for more information.
311 fun to_plain_json
: String
313 var stream
= new StringWriter
314 var serializer
= new JsonSerializer(stream
)
315 serializer
.plain_json
= true
316 serializer
.serialize
self
323 redef fun serialize_to_json
(v
) do v
.stream
.write
(to_s
)
327 redef fun serialize_to_json
(v
) do v
.stream
.write
(to_s
)
331 redef fun serialize_to_json
(v
) do v
.stream
.write
(to_s
)
335 redef fun serialize_to_json
(v
)
338 v
.stream
.write to_s
.to_json
340 v
.stream
.write
"\{\"__kind\
": \"char\
", \"__val\
": "
341 v
.stream
.write to_s
.to_json
348 redef fun serialize_to_json
(v
) do v
.stream
.write
(to_json
)
351 redef class NativeString
352 redef fun serialize_to_json
(v
) do to_s
.serialize_to_json
(v
)
355 redef class Collection[E
]
356 # Utility to serialize a normal Json array
357 private fun serialize_to_pure_json
(v
: JsonSerializer)
364 else v
.stream
.write
", "
366 if not v
.try_to_serialize
(e
) then
367 v
.warn
("element of type {e.class_name} is not serializable.")
374 redef class SimpleCollection[E
]
375 redef fun serialize_to_json
(v
)
377 # Register as pseudo object
378 if not v
.plain_json
then
379 var id
= v
.ref_id_for
(self)
380 v
.stream
.write
"""{"__kind": "obj", "__id": """
381 v
.stream
.write id
.to_s
382 v
.stream
.write
""", "__class": """"
383 v.stream.write class_name
384 v.stream.write """", "__length": """
385 v.stream.write length.to_s
386 v.stream.write """, "__items": """
389 serialize_to_pure_json v
391 if not v.plain_json then
396 redef init from_deserializer(v: Deserializer)
398 if v isa JsonDeserializer then
399 v.notify_of_creation self
402 var length = v.deserialize_attribute("__length").as(Int)
403 var arr = v.path.last["__items"].as(SequenceRead[nullable Object])
404 for i in length.times do
405 var obj = v.convert_object(arr[i])
413 redef fun serialize_to_json(v)
415 if v.plain_json or class_name == "Array[nullable Serializable]" then
416 # Using class_name to get the exact type,
417 # we do not want Array[Int] or anything else here.
419 serialize_to_pure_json v
424 redef class Map[K, V]
425 redef fun serialize_to_json(v)
427 # Register as pseudo object
428 var id = v.ref_id_for(self)
433 for key, val in self do
438 if key == null then key = "null"
440 v.stream.write key.to_s.to_json
442 if not v.try_to_serialize(val) then
443 v.warn("element of type {val.class_name} is not serializable.")
444 v.stream.write "null"
449 v.stream.write """{"__kind": "obj", "__id": """
450 v.stream.write id.to_s
451 v.stream.write """, "__class": """"
452 v.stream.write class_name
453 v.stream.write """", "__length
": """
454 v.stream.write length.to_s
456 v.stream.write """, "__keys
": """
457 keys.serialize_to_pure_json v
459 v.stream.write """, "__values
": """
460 values.serialize_to_pure_json v
466 # Instantiate a new `Array` from its serialized representation.
467 redef init from_deserializer(v: Deserializer)
471 if v isa JsonDeserializer then
472 v.notify_of_creation self
474 var length = v.deserialize_attribute("__length
").as(Int)
475 var keys = v.path.last["__keys
"].as(SequenceRead[nullable Object])
476 var values = v.path.last["__values
"].as(SequenceRead[nullable Object])
477 for i in length.times do
478 var key = v.convert_object(keys[i])
479 var value = v.convert_object(values[i])