lib/serialization/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 # Abstract services to serialize Nit objects to different formats
  18 #
  19 # This module declares the `serialize` annotation to mark Nit classes as serializable.
  20 # For an introduction to this service, refer to the documentation of the `serialization` group.
  21 # This documentation provides more technical information on interesting entitie of this module.
  22 #
  23 # Interesting entities for end users of serializable classes:
  24 #
  25 # * Serialize an instance subclass of `Serializable` with either
  26 #   `Serializer::serializable` and `Serializable::serialize`.
  27 # * Deserialize an object using `Deserializer::deserialize`.
  28 #   The object type must the be checked with an `assert` or otherwise.
  29 #
  30 # Interesting entities to create custom serializable classes:
  31 #
  32 # * Subclass `Serializable` to declare a class as serializable and to customize
  33 #   the serialization and deserialization behavior.
  34 # * Redefine `Serializable::core_serialize_to` to customize the serialization
  35 #   of the receiver class.
  36 # * Redefine `Deserializer::deserialize_class` to customize the deserialization
  37 #   of a specific class by name.
  38 #
  39 # Interesting entities for serialization format:
  40 #
  41 # * Subclass `Serializer` and `Deserializer` with custom serices.
  42 # * In `Serializer`, `serialize` and `serialize_reference` must be redefined.
  43 # * In `Deserializer`; `deserialize`, `deserialize_attribute and
  44 #   `notify_of_creation` must be redefined.
  45 module serialization is
  46         new_annotation auto_serializable
  47         new_annotation serialize
  48         new_annotation noserialize
  49         new_annotation serialize_as
  50 end
  51
  52 # Abstract serialization service to be sub-classed by specialized services.
  53 interface Serializer
  54         # Entry point method of this service, serialize the `object`
  55         #
  56         # This method, and refinements, should handle `null` and probably
  57         # use double dispatch to customize the bahavior per serializable objects.
  58         fun serialize(object: nullable Serializable) is abstract
  59
  60         # Serialize an object, with full serialization or a simple reference
  61         protected fun serialize_reference(object: Serializable) is abstract
  62
  63         # Serialize an attribute to compose a serializable object
  64         #
  65         # This method should be called from `Serializable::core_serialize_to`.
  66         fun serialize_attribute(name: String, value: nullable Object)
  67         do
  68                 if not try_to_serialize(value) then
  69                         warn("argument {name} of type {value.class_name} is not serializable.")
  70                 end
  71         end
  72
  73         # Serialize `value` is possie, i.e. it is `Serializable` or `null`
  74         fun try_to_serialize(value: nullable Object): Bool
  75         do
  76                 if value isa Serializable then
  77                         value.serialize_to_or_delay(self)
  78                 else if value == null then
  79                         serialize value
  80                 else return false
  81                 return true
  82         end
  83
  84         # Warn of problems and potential errors (such as if an attribute
  85         # is not serializable)
  86         fun warn(msg: String) do print "Serialization warning: {msg}"
  87 end
  88
  89 # Abstract deserialization service
  90 #
  91 # The main service is `deserialize`.
  92 abstract class Deserializer
  93         # Deserialize and return an object, storing errors in the attribute `errors`
  94         #
  95         # This method behavior varies according to the implementation engines.
  96         fun deserialize: nullable Object is abstract
  97
  98         # Deserialize the attribute with `name` from the object open for deserialization
  99         #
 100         # The `static_type` can be used as last resort if the deserialized object
 101         # desn't have any metadata declaring the dynamic type.
 102         #
 103         # Return the deserialized value or null on error, and set
 104         # `deserialize_attribute_missing` to whether the attribute was missing.
 105         #
 106         # Internal method to be implemented by the engines.
 107         fun deserialize_attribute(name: String, static_type: nullable String): nullable Object is abstract
 108
 109         # Was the attribute queried by the last call to `deserialize_attribute` missing?
 110         var deserialize_attribute_missing = false
 111
 112         # Register a newly allocated object (even if not completely built)
 113         #
 114         # Internal method called by objects in creation, to be implemented by the engines.
 115         fun notify_of_creation(new_object: Object) is abstract
 116
 117         # Deserialize the next available object as an instance of `class_name`
 118         #
 119         # Return the deserialized object on success and
 120         # record in `errors` if `class_name` is unknown.
 121         #
 122         # This method should be redefined for each custom subclass of `Serializable`.
 123         # All refinement should look for a precise `class_name` and call super
 124         # on unsupported classes.
 125         protected fun deserialize_class(class_name: String): nullable Object do
 126                 if class_name == "Error" then return new Error.from_deserializer(self)
 127                 return deserialize_class_intern(class_name)
 128         end
 129
 130         # Generated service to deserialize the next available object as an instance of `class_name`
 131         #
 132         # Refinements to this method will be generated by the serialization phase.
 133         # To avoid conflicts, there should not be any other refinements to this method.
 134         # You can instead use `deserialize_class`.
 135         protected fun deserialize_class_intern(class_name: String): nullable Object do
 136                 errors.add new Error("Deserialization Error: Doesn't know how to deserialize class \"{class_name}\"")
 137                 return null
 138         end
 139
 140         # Should `self` keep trying to deserialize an object after an error?
 141         #
 142         # This behavior takes effect after each attribute deserialization with
 143         # errors such as a missing attribute or the value is of the wrong type.
 144         # If `keep_going`, the attribute will be skipped but the engine will
 145         # deserialize the next attribute.
 146         # If `not keep_going`, the engine stops deserializing right away.
 147         #
 148         # When at `true`, this may cause the accumulation of a lot of entries in `errors`.
 149         #
 150         # Default at `true`.
 151         var keep_going: nullable Bool = null is writable
 152
 153         # Errors encountered in the last call to `deserialize`
 154         var errors = new Array[Error]
 155 end
 156
 157 # Error on invalid dynamic type for a deserialized attribute
 158 class AttributeTypeError
 159         super Error
 160
 161         autoinit receiver, attribute_name, attribute, expected_type
 162
 163         # Parent object of the problematic attribute
 164         var receiver: Object
 165
 166         # Name of the problematic attribute in `receiver`
 167         var attribute_name: String
 168
 169         # Deserialized object that isn't of the `expected_type`
 170         var attribute: nullable Object
 171
 172         # Name of the type expected for `attribute`
 173         var expected_type: String
 174
 175         redef var message is lazy do
 176                 var attribute = attribute
 177                 var found_type = if attribute != null then attribute.class_name else "null"
 178
 179                 return "Deserialization Error: {
 180                 }Wrong type on `{receiver.class_name}::{attribute_name}` expected `{expected_type}`, got `{found_type}`"
 181         end
 182 end
 183
 184 # Instances of this class can be passed to `Serializer::serialize`
 185 interface Serializable
 186         # Serialize `self` to `serializer`
 187         #
 188         # This is a shortcut to `Serializer::serialize`.
 189         fun serialize_to(serializer: Serializer) do serializer.serialize(self)
 190
 191         # Actual serialization of `self` to `serializer`
 192         #
 193         # This writes the full data of `self` to `serializer`.
 194         #
 195         # This method can be redefined in sub classes and refinements.
 196         # It should use `Serializer::serialize_attribute` to to register real or
 197         # logical attributes.
 198         #
 199         # Any refinement should have its equivalent refinement of
 200         # `Deserializer::deserialize_class` to support this custom deserialization.
 201         fun core_serialize_to(serializer: Serializer) do end
 202
 203         # Accept references or force direct serialization (using `serialize_to`)
 204         #
 205         # The subclass change the default behavior, which will accept references,
 206         # to force to always serialize copies of `self`.
 207         private fun serialize_to_or_delay(v: Serializer) do v.serialize_reference(self)
 208
 209         # Create an instance of this class from the `deserializer`
 210         #
 211         # This constructor is refined by subclasses to correctly build their instances.
 212         init from_deserializer(deserializer: Deserializer) is nosuper do end
 213 end
 214
 215 redef interface Object
 216         # Is `self` the same as `other` in a serialization context?
 217         #
 218         # Used to determine if an object has already been serialized.
 219         fun is_same_serialized(other: nullable Object): Bool do return is_same_instance(other)
 220
 221         # Hash value use for serialization
 222         #
 223         # Used in combination with `is_same_serialized`. If two objects are the same
 224         # in a serialization context, they must have the same `serialization_hash`.
 225         fun serialization_hash: Int do return object_id
 226 end
 227
 228 # Instances of this class are not delayed and instead serialized immediately
 229 # This applies mainly to `universal` types
 230 interface DirectSerializable
 231         super Serializable
 232
 233         redef fun serialize_to_or_delay(v) do serialize_to(v)
 234 end
 235
 236 redef class Bool super DirectSerializable end
 237 redef class Char super DirectSerializable end
 238 redef class Int super DirectSerializable end
 239 redef class Float super DirectSerializable end
 240 redef class NativeString super DirectSerializable end
 241 redef class Text super DirectSerializable end
 242 redef class SimpleCollection[E] super Serializable end
 243 redef class Map[K, V] super Serializable end
 244
 245 redef class Couple[F, S]
 246         super Serializable
 247
 248         redef init from_deserializer(v)
 249         do
 250                 v.notify_of_creation self
 251                 var first = v.deserialize_attribute("first")
 252                 var second = v.deserialize_attribute("second")
 253                 init(first, second)
 254         end
 255
 256         redef fun core_serialize_to(v)
 257         do
 258                 v.serialize_attribute("first", first)
 259                 v.serialize_attribute("second", second)
 260         end
 261 end
 262
 263 redef class Ref[E]
 264         super Serializable
 265
 266         redef init from_deserializer(v)
 267         do
 268                 v.notify_of_creation self
 269                 var item = v.deserialize_attribute("item")
 270                 init item
 271         end
 272
 273         redef fun core_serialize_to(v)
 274         do
 275                 v.serialize_attribute("item", first)
 276         end
 277 end
 278
 279 redef class Error
 280         super Serializable
 281
 282         redef init from_deserializer(v)
 283         do
 284                 v.notify_of_creation self
 285
 286                 var message = v.deserialize_attribute("message")
 287                 if not message isa String then message = ""
 288                 init message
 289
 290                 var cause = v.deserialize_attribute("cause")
 291                 if cause isa nullable Error then self.cause = cause
 292         end
 293
 294         redef fun core_serialize_to(v)
 295         do
 296                 v.serialize_attribute("message", message)
 297                 v.serialize_attribute("cause", cause)
 298         end
 299 end