lib/json/serialization.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Copyright 2014 Alexis Laferrière <alexis.laf@xymus.net>
   4 #
   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
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  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.
  16
  17 # Handles serialization and deserialization of objects to/from JSON
  18 #
  19 # ## Nity JSON
  20 #
  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.
  24 #
  25 # For more information on Nit serialization, see: ../serialization/README.md
  26 #
  27 # ## Plain JSON
  28 #
  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`.
  33 #
  34 # A shortcut to this service is provided by `Serializable::to_plain_json`.
  35 #
  36 # ### Usage Example
  37 #
  38 # ~~~nitish
  39 # import json::serialization
  40 #
  41 # class Person
  42 #     auto_serializable
  43 #
  44 #     var name: String
  45 #     var year_of_birth: Int
  46 #     var next_of_kin: nullable Person
  47 # end
  48 #
  49 # var bob = new Person("Bob", 1986)
  50 # var alice = new Person("Alice", 1978, bob)
  51 #
  52 # assert bob.to_plain_json == """
  53 # {"name": "Bob", "year_of_birth": 1986, "next_of_kin": null}"""
  54 #
  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}}"""
  57 # ~~~
  58 module serialization
  59
  60 import ::serialization
  61 private import ::serialization::engine_tools
  62 private import static
  63
  64 # Serializer of Nit objects to Json string.
  65 class JsonSerializer
  66         super Serializer
  67
  68         # Target writing stream
  69         var stream: Writer
  70
  71         # Write plain JSON? easier to read but does not support Nit deserialization
  72         #
  73         # If `false`, the default, serialize to support deserialization:
  74         #
  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.
  83         #
  84         # If `true`, serialize for other programs:
  85         #
  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
  95
  96         # List of the current open objects, the first is the main target of the serialization
  97         #
  98         # Used only when `plain_json == true` to detect cycles in serialization.
  99         private var open_objects = new Array[Object]
 100
 101         # Has the first attribute of the current object already been serialized?
 102         #
 103         # Used only when `plain_json == true`.
 104         private var first_attribute = false
 105
 106         redef fun serialize(object)
 107         do
 108                 if object == null then
 109                         stream.write "null"
 110                 else
 111                         if plain_json then
 112                                 for o in open_objects do
 113                                         if object.is_same_serialized(o) then
 114                                                 # Cycle detected
 115                                                 stream.write "null"
 116                                                 return
 117                                         end
 118                                 end
 119
 120                                 open_objects.add object
 121                         end
 122
 123                         first_attribute = true
 124                         object.serialize_to_json self
 125                         first_attribute = false
 126
 127                         if plain_json then open_objects.pop
 128                 end
 129         end
 130
 131         redef fun serialize_attribute(name, value)
 132         do
 133                 if not plain_json or not first_attribute then
 134                         stream.write ", "
 135                         first_attribute = false
 136                 end
 137
 138                 stream.write "\""
 139                 stream.write name
 140                 stream.write "\": "
 141                 super
 142         end
 143
 144         redef fun serialize_reference(object)
 145         do
 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\": "
 150                         stream.write id.to_s
 151                         stream.write "\}"
 152                 else
 153                         # serialize here
 154                         serialize object
 155                 end
 156         end
 157
 158         # Map of references to already serialized objects.
 159         private var refs_map = new StrictHashMap[Serializable,Int]
 160
 161         # Get the internal serialized reference for this `object`.
 162         private fun ref_id_for(object: Serializable): Int
 163         do
 164                 if refs_map.has_key(object) then
 165                         return refs_map[object]
 166                 else
 167                         var id = refs_map.length
 168                         refs_map[object] = id
 169                         return id
 170                 end
 171         end
 172 end
 173
 174 # Deserializer from a Json string.
 175 class JsonDeserializer
 176         super Deserializer
 177
 178         # Json text to deserialize from.
 179         private var text: Text
 180
 181         # Root json object parsed from input text.
 182         private var root: nullable Jsonable is noinit
 183
 184         # Depth-first path in the serialized object tree.
 185         private var path = new Array[JsonObject]
 186
 187         # Map of references to already deserialized objects.
 188         private var id_to_object = new StrictHashMap[Int, Object]
 189
 190         # Last encountered object reference id.
 191         #
 192         # See `id_to_object`.
 193         var just_opened_id: nullable Int = null
 194
 195         init do
 196                 var root = text.parse_json
 197                 if root isa JsonObject then path.add(root)
 198                 self.root = root
 199         end
 200
 201         redef fun deserialize_attribute(name)
 202         do
 203                 assert not path.is_empty
 204                 var current = path.last
 205
 206                 assert current.keys.has(name)
 207                 var value = current[name]
 208
 209                 return convert_object(value)
 210         end
 211
 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)
 215         do
 216                 var id = just_opened_id
 217                 if id == null then return # Register `new_object` only once
 218                 id_to_object[id] = new_object
 219         end
 220
 221         # Convert from simple Json object to Nit object
 222         private fun convert_object(object: nullable Object): nullable Object
 223         do
 224                 if object isa JsonObject then
 225                         assert object.keys.has("__kind")
 226                         var kind = object["__kind"]
 227
 228                         # ref?
 229                         if kind == "ref" then
 230                                 assert object.keys.has("__id")
 231                                 var id = object["__id"]
 232                                 assert id isa Int
 233
 234                                 assert id_to_object.has_key(id)
 235                                 return id_to_object[id]
 236                         end
 237
 238                         # obj?
 239                         if kind == "obj" then
 240                                 assert object.keys.has("__id")
 241                                 var id = object["__id"]
 242                                 assert id isa Int
 243
 244                                 assert object.keys.has("__class")
 245                                 var class_name = object["__class"]
 246                                 assert class_name isa String
 247
 248                                 assert not id_to_object.has_key(id) else print "Error: Object with id '{id}' of {class_name} is deserialized twice."
 249
 250                                 # advance on path
 251                                 path.push object
 252
 253                                 just_opened_id = id
 254                                 var value = deserialize_class(class_name)
 255                                 just_opened_id = null
 256
 257                                 # revert on path
 258                                 path.pop
 259
 260                                 return value
 261                         end
 262
 263                         # char?
 264                         if kind == "char" then
 265                                 assert object.keys.has("__val")
 266                                 var val = object["__val"]
 267                                 assert val isa String
 268
 269                                 if val.length != 1 then print "Error: expected a single char when deserializing '{val}'."
 270
 271                                 return val.chars.first
 272                         end
 273
 274                         print "Malformed Json string: unexpected Json Object kind '{kind or else "null"}'"
 275                         abort
 276                 end
 277
 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)
 282                         return array
 283                 end
 284
 285                 return object
 286         end
 287
 288         redef fun deserialize do return convert_object(root)
 289 end
 290
 291 redef class Serializable
 292         private fun serialize_to_json(v: JsonSerializer)
 293         do
 294                 var id = v.ref_id_for(self)
 295                 v.stream.write "\{"
 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
 301                         v.stream.write "\""
 302                 end
 303                 core_serialize_to(v)
 304                 v.stream.write "\}"
 305         end
 306
 307         # Serialize this object to plain JSON
 308         #
 309         # This is a shortcut using `JsonSerializer::plain_json`,
 310         # see its documentation for more information.
 311         fun to_plain_json: String
 312         do
 313                 var stream = new StringWriter
 314                 var serializer = new JsonSerializer(stream)
 315                 serializer.plain_json = true
 316                 serializer.serialize self
 317                 stream.close
 318                 return stream.to_s
 319         end
 320 end
 321
 322 redef class Int
 323         redef fun serialize_to_json(v) do v.stream.write(to_s)
 324 end
 325
 326 redef class Float
 327         redef fun serialize_to_json(v) do v.stream.write(to_s)
 328 end
 329
 330 redef class Bool
 331         redef fun serialize_to_json(v) do v.stream.write(to_s)
 332 end
 333
 334 redef class Char
 335         redef fun serialize_to_json(v)
 336         do
 337                 if v.plain_json then
 338                         v.stream.write to_s.to_json
 339                 else
 340                         v.stream.write "\{\"__kind\": \"char\", \"__val\": "
 341                         v.stream.write to_s.to_json
 342                         v.stream.write "\}"
 343                 end
 344         end
 345 end
 346
 347 redef class String
 348         redef fun serialize_to_json(v) do v.stream.write(to_json)
 349 end
 350
 351 redef class NativeString
 352         redef fun serialize_to_json(v) do to_s.serialize_to_json(v)
 353 end
 354
 355 redef class Collection[E]
 356         # Utility to serialize a normal Json array
 357         private fun serialize_to_pure_json(v: JsonSerializer)
 358         do
 359                         v.stream.write "["
 360                         var is_first = true
 361                         for e in self do
 362                                 if is_first then
 363                                         is_first = false
 364                                 else v.stream.write ", "
 365
 366                                 if not v.try_to_serialize(e) then
 367                                         v.warn("element of type {e.class_name} is not serializable.")
 368                                 end
 369                         end
 370                         v.stream.write "]"
 371         end
 372 end
 373
 374 redef class SimpleCollection[E]
 375         redef fun serialize_to_json(v)
 376         do
 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": """
 387                 end
 388
 389                 serialize_to_pure_json v
 390
 391                 if not v.plain_json then
 392                         v.stream.write "\}"
 393                 end
 394         end
 395
 396         redef init from_deserializer(v: Deserializer)
 397         do
 398                 if v isa JsonDeserializer then
 399                         v.notify_of_creation self
 400                         init
 401
 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])
 406                                 self.add obj
 407                         end
 408                 end
 409         end
 410 end
 411
 412 redef class Array[E]
 413         redef fun serialize_to_json(v)
 414         do
 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.
 418
 419                         serialize_to_pure_json v
 420                 else super
 421         end
 422 end
 423
 424 redef class Map[K, V]
 425         redef fun serialize_to_json(v)
 426         do
 427                 # Register as pseudo object
 428                 var id = v.ref_id_for(self)
 429
 430                 if v.plain_json then
 431                         v.stream.write "\{"
 432                         var first = true
 433                         for key, val in self do
 434                                 if not first then
 435                                         v.stream.write ", "
 436                                 else first = false
 437
 438                                 if key == null then key = "null"
 439
 440                                 v.stream.write key.to_s.to_json
 441                                 v.stream.write ": "
 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"
 445                                 end
 446                         end
 447                         v.stream.write "\}"
 448                 else
 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
 455
 456                         v.stream.write """, "__keys": """
 457                         keys.serialize_to_pure_json v
 458
 459                         v.stream.write """, "__values": """
 460                         values.serialize_to_pure_json v
 461
 462                         v.stream.write "\}"
 463                 end
 464         end
 465
 466         # Instantiate a new `Array` from its serialized representation.
 467         redef init from_deserializer(v: Deserializer)
 468         do
 469                 init
 470
 471                 if v isa JsonDeserializer then
 472                         v.notify_of_creation self
 473
 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])
 480                                 self[key] = value
 481                         end
 482                 end
 483         end
 484 end