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 `auto_serializable` 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 end
  48
  49 # Abstract serialization service to be sub-classed by specialized services.
  50 interface Serializer
  51         # Entry point method of this service, serialize the `object`
  52         #
  53         # This method, and refinements, should handle `null` and probably
  54         # use double dispatch to customize the bahavior per serializable objects.
  55         fun serialize(object: nullable Serializable) is abstract
  56
  57         fun serialize_reference(object: Serializable) is abstract
  58         # Serialize an object, with full serialization or a simple reference
  59
  60         # Serialize an attribute to compose a serializable object
  61         #
  62         # This method should be called from `Serializable::core_serialize_to`.
  63         fun serialize_attribute(name: String, value: nullable Object)
  64         do
  65                 if not try_to_serialize(value) then
  66                         warn("argument {value.class_name}::{name} is not serializable.")
  67                 end
  68         end
  69
  70         # Serialize `value` is possie, i.e. it is `Serializable` or `null`
  71         fun try_to_serialize(value: nullable Object): Bool
  72         do
  73                 if value isa Serializable then
  74                         value.serialize_to_or_delay(self)
  75                 else if value == null then
  76                         serialize value
  77                 else return false
  78                 return true
  79         end
  80
  81         # Warn of problems and potential errors (such as if an attribute
  82         # is not serializable)
  83         fun warn(msg: String) do print "Serialization warning: {msg}"
  84 end
  85
  86 # Abstract deserialization service
  87 #
  88 # After initialization of one of its sub-classes, call `deserialize`
  89 interface Deserializer
  90         # Main method of this class, returns a Nit object
  91         fun deserialize: nullable Object is abstract
  92
  93         # Internal method to be implemented by sub-classes
  94         fun deserialize_attribute(name: String): nullable Object is abstract
  95
  96         # Internal method called by objects in creation,
  97         # to be implemented by sub-classes
  98         fun notify_of_creation(new_object: Object) is abstract
  99
 100         # Deserialize the next available object as an instance of `class_name`
 101         #
 102         # Returns the deserialized object on success, aborts on error.
 103         #
 104         # This method should be redefined for each custom subclass of `Serializable`.
 105         # All refinement should look for a precise `class_name` and call super
 106         # on unsupported classes.
 107         fun deserialize_class(class_name: String): Object do
 108                 print "Error: doesn't know how to deserialize class \"{class_name}\""
 109                 abort
 110         end
 111 end
 112
 113 # Instances of this class can be passed to `Serializer::serialize`
 114 interface Serializable
 115         # Serialize `self` to `serializer`
 116         #
 117         # This is a shortcut to `Serializer::serialize`.
 118         fun serialize_to(serializer: Serializer) do serializer.serialize(self)
 119
 120         # Actual serialization of `self` to `serializer`
 121         #
 122         # This writes the full data of `self` to `serializer`.
 123         #
 124         # This method can be redefined in sub classes and refinements.
 125         # It should use `Serializer::serialize_attribute` to to register real or
 126         # logical attributes.
 127         #
 128         # Any refinement should have its equivalent refinement of
 129         # `Deserializer::deserialize_class` to support this custom deserialization.
 130         fun core_serialize_to(serializer: Serializer) do end
 131
 132         # Accept references or force direct serialization (using `serialize_to`)
 133         #
 134         # The subclass change the default behavior, which will accept references,
 135         # to force to always serialize copies of `self`.
 136         private fun serialize_to_or_delay(v: Serializer) do v.serialize_reference(self)
 137 end
 138
 139 # Instances of this class are not delayed and instead serialized immediately
 140 # This applies mainly to `universal` types
 141 interface DirectSerializable
 142         super Serializable
 143
 144         redef fun serialize_to_or_delay(v) do serialize_to(v)
 145 end
 146
 147 redef class Bool super DirectSerializable end
 148 redef class Char super DirectSerializable end
 149 redef class Int super DirectSerializable end
 150 redef class Float super DirectSerializable end
 151 redef class NativeString super DirectSerializable end
 152 redef class String super DirectSerializable end
 153 redef class Array[E] super Serializable end