1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Copyright 2014 Alexis Laferrière <alexis.laf@xymus.net>
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
9 # http://www.apache.org/licenses/LICENSE-2.0
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.
17 # Abstract services to serialize Nit objects to different formats
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.
23 # Interesting entities for end users of serializable classes:
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.
30 # Interesting entities to create custom serializable classes:
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.
39 # Interesting entities for serialization format:
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
49 # Abstract serialization service to be sub-classed by specialized services.
51 # Entry point method of this service, serialize the `object`
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
57 # Serialize an object, with full serialization or a simple reference
58 protected fun serialize_reference
(object
: Serializable) is abstract
60 # Serialize an attribute to compose a serializable object
62 # This method should be called from `Serializable::core_serialize_to`.
63 fun serialize_attribute
(name
: String, value
: nullable Object)
65 if not try_to_serialize
(value
) then
66 warn
("argument {name} of type {value.class_name} is not serializable.")
70 # Serialize `value` is possie, i.e. it is `Serializable` or `null`
71 fun try_to_serialize
(value
: nullable Object): Bool
73 if value
isa Serializable then
74 value
.serialize_to_or_delay
(self)
75 else if value
== null then
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}"
86 # Abstract deserialization service
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
93 # Internal method to be implemented by sub-classes
94 fun deserialize_attribute
(name
: String): nullable Object is abstract
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
100 # Deserialize the next available object as an instance of `class_name`
102 # Returns the deserialized object on success, aborts on error.
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}\
""
113 # Instances of this class can be passed to `Serializer::serialize`
114 interface Serializable
115 # Serialize `self` to `serializer`
117 # This is a shortcut to `Serializer::serialize`.
118 fun serialize_to
(serializer
: Serializer) do serializer
.serialize
(self)
120 # Actual serialization of `self` to `serializer`
122 # This writes the full data of `self` to `serializer`.
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.
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
132 # Accept references or force direct serialization (using `serialize_to`)
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)
138 # Create an instance of this class from the `deserializer`
140 # This constructor is refined by subclasses to correctly build their instances.
141 init from_deserializer
(deserializer
: Deserializer) do end
144 redef interface Object
145 # Is `self` the same as `other` in a serialization context?
147 # Used to determine if an object has already been serialized.
148 fun is_same_serialized
(other
: nullable Object): Bool do return is_same_instance
(other
)
150 # Hash value use for serialization
152 # Used in combination with `is_same_serialized`. If two objects are the same
153 # in a serialization context, they must have the same `serialization_hash`.
154 fun serialization_hash
: Int do return object_id
157 # Instances of this class are not delayed and instead serialized immediately
158 # This applies mainly to `universal` types
159 interface DirectSerializable
162 redef fun serialize_to_or_delay
(v
) do serialize_to
(v
)
165 redef class Bool super DirectSerializable end
166 redef class Char super DirectSerializable end
167 redef class Int super DirectSerializable end
168 redef class Float super DirectSerializable end
169 redef class NativeString super DirectSerializable end
170 redef class String super DirectSerializable end
171 redef class SimpleCollection[E
] super Serializable end
172 redef class Map[K
, V
] super Serializable end
174 redef class Couple[F
, S
]
177 redef init from_deserializer
(v
)
179 v
.notify_of_creation
self
180 var first
= v
.deserialize_attribute
("first")
181 var second
= v
.deserialize_attribute
("second")
185 redef fun core_serialize_to
(v
)
187 v
.serialize_attribute
("first", first
)
188 v
.serialize_attribute
("second", second
)
192 redef class Container[E
]
195 redef init from_deserializer
(v
)
197 v
.notify_of_creation
self
198 var item
= v
.deserialize_attribute
("item")
202 redef fun core_serialize_to
(v
)
204 v
.serialize_attribute
("item", first
)