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 # Offers services to serialize a Nit objects to different persistent formats
  18 module serialization is
  19         new_annotation auto_serializable
  20 end
  21
  22 # Abstract serialization service to be sub-classed by specialized services.
  23 interface Serializer
  24         # Main method of this service, serialize the `object`
  25         fun serialize(object: nullable Serializable) is abstract
  26
  27         # Serialize an object as a "possible" reference, depending of the service
  28         fun serialize_reference(object: Serializable) is abstract
  29
  30         # Serialize an attribute, used by `Serializable::core_serialize_to`
  31         fun serialize_attribute(name: String, value: nullable Object)
  32         do
  33                 if not try_to_serialize(value) then
  34                         warn("argument {value.class_name}::{name} is not serializable.")
  35                 end
  36         end
  37
  38         # Serialize `value` is possie, i.e. it is `Serializable` or `null`
  39         fun try_to_serialize(value: nullable Object): Bool
  40         do
  41                 if value isa Serializable then
  42                         value.serialize_to_or_delay(self)
  43                 else if value == null then
  44                         serialize value
  45                 else return false
  46                 return true
  47         end
  48
  49         # Warn of problems and potential errors (such as if an attribute
  50         # is not serializable)
  51         fun warn(msg: String) do print "Serialization warning: {msg}"
  52 end
  53
  54 # Abstract deserialization service
  55 #
  56 # After initialization of one of its sub-classes, call `deserialize`
  57 interface Deserializer
  58         # Main method of this class, returns a Nit object
  59         fun deserialize: nullable Object is abstract
  60
  61         # Internal method to be implemented by sub-classes
  62         fun deserialize_attribute(name: String): nullable Object is abstract
  63
  64         # Internal method called by objects in creation,
  65         # to be implemented by sub-classes
  66         fun notify_of_creation(new_object: Object) is abstract
  67
  68         # Mainly generated method to return the next instance of the givent
  69         # class by name
  70         fun deserialize_class(class_name: String): Object do
  71                 print "Error: doesn't know how to deserialize class \"{class_name}\""
  72                 abort
  73         end
  74 end
  75
  76 # Instances of this class can be passed to `Serializer::serialize`
  77 interface Serializable
  78         # Full or true serialization
  79         fun serialize_to(v: Serializer) do v.serialize(self)
  80
  81         # Body of the serialization of this class
  82         # Can be redefed in sub classes and refinements
  83         fun core_serialize_to(v: Serializer) do end
  84
  85         # Whether full serialization (calls `serialize_to`) or place only references
  86         fun serialize_to_or_delay(v: Serializer) do v.serialize_reference(self)
  87 end
  88
  89 # Instances of this class are not delayed and instead serialized immediately
  90 # This applies mainly to `universal` types
  91 interface DirectSerializable
  92         super Serializable
  93
  94         redef fun serialize_to_or_delay(v) do serialize_to(v)
  95 end
  96
  97 redef class Bool super DirectSerializable end
  98 redef class Char super DirectSerializable end
  99 redef class Int super DirectSerializable end
 100 redef class Float super DirectSerializable end
 101 redef class NativeString super DirectSerializable end
 102 redef class String super DirectSerializable end
 103 redef class Array[E] super Serializable end