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 #     serialize
  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::caching
  61 private import ::serialization::engine_tools
  62 private import static
  63
  64 # Serializer of Nit objects to Json string.
  65 class JsonSerializer
  66         super CachingSerializer
  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 cache.has_object(object) then
 147                         # if already serialized, add local reference
 148                         var id = cache.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 end
 158
 159 # Deserializer from a Json string.
 160 class JsonDeserializer
 161         super CachingDeserializer
 162
 163         # Json text to deserialize from.
 164         private var text: Text
 165
 166         # Root json object parsed from input text.
 167         private var root: nullable Jsonable is noinit
 168
 169         # Depth-first path in the serialized object tree.
 170         private var path = new Array[JsonObject]
 171
 172         # Last encountered object reference id.
 173         #
 174         # See `id_to_object`.
 175         var just_opened_id: nullable Int = null
 176
 177         init do
 178                 var root = text.parse_json
 179                 if root isa JsonObject then path.add(root)
 180                 self.root = root
 181         end
 182
 183         redef fun deserialize_attribute(name)
 184         do
 185                 assert not path.is_empty # This is an internal error, abort
 186                 var current = path.last
 187
 188                 if not current.keys.has(name) then
 189                         errors.add new Error("Deserialization Error: JSON object has not attribute '{name}'.")
 190                         return null
 191                 end
 192
 193                 var value = current[name]
 194
 195                 return convert_object(value)
 196         end
 197
 198         # This may be called multiple times by the same object from constructors
 199         # in different nclassdef
 200         redef fun notify_of_creation(new_object)
 201         do
 202                 var id = just_opened_id
 203                 if id == null then return # Register `new_object` only once
 204                 cache[id] = new_object
 205         end
 206
 207         # Convert from simple Json object to Nit object
 208         private fun convert_object(object: nullable Object): nullable Object
 209         do
 210                 if object isa JsonObject then
 211                         assert object.keys.has("__kind")
 212                         var kind = object["__kind"]
 213
 214                         # ref?
 215                         if kind == "ref" then
 216                                 if not object.keys.has("__id") then
 217                                         errors.add new Error("Serialization Error: JSON object reference does not declare a `__id`.")
 218                                         return object
 219                                 end
 220
 221                                 var id = object["__id"]
 222                                 if not id isa Int then
 223                                         errors.add new Error("Serialization Error: JSON object reference declares a non-integer `__id`.")
 224                                         return object
 225                                 end
 226
 227                                 if not cache.has_id(id) then
 228                                         errors.add new Error("Serialization Error: JSON object reference has an unknown `__id`.")
 229                                         return object
 230                                 end
 231
 232                                 return cache.object_for(id)
 233                         end
 234
 235                         # obj?
 236                         if kind == "obj" then
 237                                 var id = null
 238                                 if object.keys.has("__id") then
 239                                         id = object["__id"]
 240
 241                                         if not id isa Int then
 242                                                 errors.add new Error("Serialization Error: JSON object declaration declares a non-integer `__id`.")
 243                                                 return object
 244                                         end
 245
 246                                         if cache.has_id(id) then
 247                                                 errors.add new Error("Serialization Error: JSON object with `__id` {id} is deserialized twice.")
 248                                                 # Keep going
 249                                         end
 250                                 end
 251
 252                                 if not object.keys.has("__class") then
 253                                         errors.add new Error("Serialization Error: JSON object declaration does not declare a `__class`.")
 254                                         return object
 255                                 end
 256
 257                                 var class_name = object["__class"]
 258                                 if not class_name isa String then
 259                                         errors.add new Error("Serialization Error: JSON object declaration declares a non-string `__class`.")
 260                                         return object
 261                                 end
 262
 263                                 # advance on path
 264                                 path.push object
 265
 266                                 just_opened_id = id
 267                                 var value = deserialize_class(class_name)
 268                                 just_opened_id = null
 269
 270                                 # revert on path
 271                                 path.pop
 272
 273                                 return value
 274                         end
 275
 276                         # char?
 277                         if kind == "char" then
 278                                 if not object.keys.has("__val") then
 279                                         errors.add new Error("Serialization Error: JSON `char` object does not declare a `__val`.")
 280                                         return object
 281                                 end
 282
 283                                 var val = object["__val"]
 284
 285                                 if not val isa String or val.is_empty then
 286                                         errors.add new Error("Serialization Error: JSON `char` object does not declare a single char in `__val`.")
 287                                         return object
 288                                 end
 289
 290                                 return val.chars.first
 291                         end
 292
 293                         errors.add new Error("Serialization Error: JSON object has an unknown `__kind`.")
 294                         return object
 295                 end
 296
 297                 if object isa Array[nullable Object] then
 298                         # special case, isa Array[nullable Serializable]
 299                         var array = new Array[nullable Serializable]
 300                         for e in object do array.add e.as(nullable Serializable)
 301                         return array
 302                 end
 303
 304                 return object
 305         end
 306
 307         redef fun deserialize do return convert_object(root)
 308 end
 309
 310 redef class Serializable
 311         private fun serialize_to_json(v: JsonSerializer)
 312         do
 313                 var id = v.cache.new_id_for(self)
 314                 v.stream.write "\{"
 315                 if not v.plain_json then
 316                         v.stream.write "\"__kind\": \"obj\", \"__id\": "
 317                         v.stream.write id.to_s
 318                         v.stream.write ", \"__class\": \""
 319                         v.stream.write class_name
 320                         v.stream.write "\""
 321                 end
 322                 core_serialize_to(v)
 323                 v.stream.write "\}"
 324         end
 325
 326         # Serialize this object to plain JSON
 327         #
 328         # This is a shortcut using `JsonSerializer::plain_json`,
 329         # see its documentation for more information.
 330         fun to_plain_json: String
 331         do
 332                 var stream = new StringWriter
 333                 var serializer = new JsonSerializer(stream)
 334                 serializer.plain_json = true
 335                 serializer.serialize self
 336                 stream.close
 337                 return stream.to_s
 338         end
 339 end
 340
 341 redef class Int
 342         redef fun serialize_to_json(v) do v.stream.write(to_s)
 343 end
 344
 345 redef class Float
 346         redef fun serialize_to_json(v) do v.stream.write(to_s)
 347 end
 348
 349 redef class Bool
 350         redef fun serialize_to_json(v) do v.stream.write(to_s)
 351 end
 352
 353 redef class Char
 354         redef fun serialize_to_json(v)
 355         do
 356                 if v.plain_json then
 357                         v.stream.write to_s.to_json
 358                 else
 359                         v.stream.write "\{\"__kind\": \"char\", \"__val\": "
 360                         v.stream.write to_s.to_json
 361                         v.stream.write "\}"
 362                 end
 363         end
 364 end
 365
 366 redef class String
 367         redef fun serialize_to_json(v) do v.stream.write(to_json)
 368 end
 369
 370 redef class NativeString
 371         redef fun serialize_to_json(v) do to_s.serialize_to_json(v)
 372 end
 373
 374 redef class Collection[E]
 375         # Utility to serialize a normal Json array
 376         private fun serialize_to_pure_json(v: JsonSerializer)
 377         do
 378                         v.stream.write "["
 379                         var is_first = true
 380                         for e in self do
 381                                 if is_first then
 382                                         is_first = false
 383                                 else v.stream.write ", "
 384
 385                                 if not v.try_to_serialize(e) then
 386                                         v.warn("element of type {e.class_name} is not serializable.")
 387                                 end
 388                         end
 389                         v.stream.write "]"
 390         end
 391 end
 392
 393 redef class SimpleCollection[E]
 394         redef fun serialize_to_json(v)
 395         do
 396                 # Register as pseudo object
 397                 if not v.plain_json then
 398                         var id = v.cache.new_id_for(self)
 399                         v.stream.write """{"__kind": "obj", "__id": """
 400                         v.stream.write id.to_s
 401                         v.stream.write """, "__class": """"
 402                         v.stream.write class_name
 403                         v.stream.write """", "__length": """
 404                         v.stream.write length.to_s
 405                         v.stream.write """, "__items": """
 406                 end
 407
 408                 serialize_to_pure_json v
 409
 410                 if not v.plain_json then
 411                         v.stream.write "\}"
 412                 end
 413         end
 414
 415         redef init from_deserializer(v: Deserializer)
 416         do
 417                 super
 418                 if v isa JsonDeserializer then
 419                         v.notify_of_creation self
 420                         init
 421
 422                         var length = v.deserialize_attribute("__length").as(Int)
 423                         var arr = v.path.last["__items"].as(SequenceRead[nullable Object])
 424                         for i in length.times do
 425                                 var obj = v.convert_object(arr[i])
 426                                 self.add obj
 427                         end
 428                 end
 429         end
 430 end
 431
 432 redef class Array[E]
 433         redef fun serialize_to_json(v)
 434         do
 435                 if v.plain_json or class_name == "Array[nullable Serializable]" then
 436                         # Using class_name to get the exact type,
 437                         # we do not want Array[Int] or anything else here.
 438
 439                         serialize_to_pure_json v
 440                 else super
 441         end
 442 end
 443
 444 redef class Map[K, V]
 445         redef fun serialize_to_json(v)
 446         do
 447                 # Register as pseudo object
 448                 var id = v.cache.new_id_for(self)
 449
 450                 if v.plain_json then
 451                         v.stream.write "\{"
 452                         var first = true
 453                         for key, val in self do
 454                                 if not first then
 455                                         v.stream.write ", "
 456                                 else first = false
 457
 458                                 if key == null then key = "null"
 459
 460                                 v.stream.write key.to_s.to_json
 461                                 v.stream.write ": "
 462                                 if not v.try_to_serialize(val) then
 463                                         v.warn("element of type {val.class_name} is not serializable.")
 464                                         v.stream.write "null"
 465                                 end
 466                         end
 467                         v.stream.write "\}"
 468                 else
 469                         v.stream.write """{"__kind": "obj", "__id": """
 470                         v.stream.write id.to_s
 471                         v.stream.write """, "__class": """"
 472                         v.stream.write class_name
 473                         v.stream.write """", "__length": """
 474                         v.stream.write length.to_s
 475
 476                         v.stream.write """, "__keys": """
 477                         keys.serialize_to_pure_json v
 478
 479                         v.stream.write """, "__values": """
 480                         values.serialize_to_pure_json v
 481
 482                         v.stream.write "\}"
 483                 end
 484         end
 485
 486         # Instantiate a new `Array` from its serialized representation.
 487         redef init from_deserializer(v: Deserializer)
 488         do
 489                 super
 490
 491                 if v isa JsonDeserializer then
 492                         v.notify_of_creation self
 493                         init
 494
 495                         var length = v.deserialize_attribute("__length").as(Int)
 496                         var keys = v.path.last["__keys"].as(SequenceRead[nullable Object])
 497                         var values = v.path.last["__values"].as(SequenceRead[nullable Object])
 498                         for i in length.times do
 499                                 var key = v.convert_object(keys[i])
 500                                 var value = v.convert_object(values[i])
 501                                 self[key] = value
 502                         end
 503                 end
 504         end
 505 end