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