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 `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.
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_core
is
46 new_annotation auto_serializable
47 new_annotation serialize
48 new_annotation noserialize
49 new_annotation serialize_as
52 intrude import core
::queue
55 # Abstract serialization service to be sub-classed by specialized services.
57 # Entry point method of this service, serialize the `object`
59 # This method, and refinements, should handle `null` and probably
60 # use double dispatch to customize the bahavior per serializable objects.
61 fun serialize
(object
: nullable Serializable) is abstract
63 # The object currently serialized by `serialized`
65 # Can be used by a custom serializer to add domain-specific serialization behavior.
66 protected fun current_object
: nullable Object is abstract
68 # Serialize an object, with full serialization or a simple reference
69 protected fun serialize_reference
(object
: Serializable) is abstract
71 # Serialize an attribute to compose a serializable object
73 # This method should be called from `Serializable::core_serialize_to`.
74 fun serialize_attribute
(name
: String, value
: nullable Object)
76 if not try_to_serialize
(value
) then
77 assert value
!= null # null would have been serialized
78 warn
("argument {name} of type {value.class_name} is not serializable.")
82 # Serialize `value` is possible, i.e. it is `Serializable` or `null`
83 fun try_to_serialize
(value
: nullable Object): Bool
85 if value
isa Serializable then
86 value
.serialize_to_or_delay
(self)
87 else if value
== null then
93 # The method is called when a standard `value` is serialized
95 # The default behavior is to call `value.core_serialize_to(self)` but it
96 # can be redefined by a custom serializer to add domain-specific serialization behavior.
97 fun serialize_core
(value
: Serializable)
99 value
.core_serialize_to
(self)
102 # Warn of problems and potential errors (such as if an attribute
103 # is not serializable)
104 fun warn
(msg
: String) do print
"Serialization warning: {msg}"
107 # Abstract deserialization service
109 # The main service is `deserialize`.
110 abstract class Deserializer
111 # Deserialize and return an object, storing errors in the attribute `errors`
113 # If a `static_type` is given, only subtypes of the `static_type` are accepted.
115 # This method behavior varies according to the implementation engines.
116 fun deserialize
(static_type
: nullable String): nullable Object is abstract
118 # Deserialize the attribute with `name` from the object open for deserialization
120 # The `static_type` restricts what kind of object can be deserialized.
122 # Return the deserialized value or null on error, and set
123 # `deserialize_attribute_missing` to whether the attribute was missing.
125 # Internal method to be implemented by the engines.
126 fun deserialize_attribute
(name
: String, static_type
: nullable String): nullable Object is abstract
128 # Was the attribute queried by the last call to `deserialize_attribute` missing?
129 var deserialize_attribute_missing
= false
131 # Register a newly allocated object (even if not completely built)
133 # Internal method called by objects in creation, to be implemented by the engines.
134 fun notify_of_creation
(new_object
: Object) is abstract
136 # Deserialize the next available object as an instance of `class_name`
138 # Return the deserialized object on success and
139 # record in `errors` if `class_name` is unknown.
141 # This method should be redefined for each custom subclass of `Serializable`.
142 # All refinement should look for a precise `class_name` and call super
143 # on unsupported classes.
144 protected fun deserialize_class
(class_name
: Text): nullable Object do
145 if class_name
== "Error" then return new Error.from_deserializer
(self)
146 return deserialize_class_intern
(class_name
)
149 # Generated service to deserialize the next available object as an instance of `class_name`
151 # Refinements to this method will be generated by the serialization phase.
152 # To avoid conflicts, there should not be any other refinements to this method.
153 # You can instead use `deserialize_class`.
154 protected fun deserialize_class_intern
(class_name
: Text): nullable Object do
155 errors
.add
new Error("Deserialization Error: Doesn't know how to deserialize class \"{class_name}\
"")
159 # Should `self` keep trying to deserialize an object after an error?
161 # This behavior takes effect after each attribute deserialization with
162 # errors such as a missing attribute or the value is of the wrong type.
163 # If `keep_going`, the attribute will be skipped but the engine will
164 # deserialize the next attribute.
165 # If `not keep_going`, the engine stops deserializing right away.
167 # When at `true`, this may cause the accumulation of a lot of entries in `errors`.
170 var keep_going
: nullable Bool = null is writable
172 # Errors encountered in the last call to `deserialize`
173 var errors
= new Array[Error]
176 # Deserialization error related to an attribute of `receiver`
177 abstract class AttributeError
180 # Parent object of the problematic attribute
183 # Name of the problematic attribute in `receiver`
184 var attribute_name
: String
187 # Invalid dynamic type for a deserialized attribute
188 class AttributeTypeError
191 autoinit receiver
, attribute_name
, attribute
, expected_type
193 # Deserialized object that isn't of the `expected_type`
194 var attribute
: nullable Object
196 # Name of the type expected for `attribute`
197 var expected_type
: String
199 redef var message
is lazy
do
200 var attribute
= attribute
201 var found_type
= if attribute
!= null then attribute
.class_name
else "null"
203 return "Deserialization Error: {
204 }Wrong type on `{receiver.class_name}::{attribute_name}` expected `{expected_type}`, got `{found_type}`"
208 # Missing attribute at deserialization
209 class AttributeMissingError
212 autoinit receiver
, attribute_name
214 redef var message
is lazy
do
215 return "Deserialization Error: Missing attribute `{receiver.class_name}::{attribute_name}`"
219 # Instances of this class can be passed to `Serializer::serialize`
220 interface Serializable
221 # Serialize `self` to `serializer`
223 # This is a shortcut to `Serializer::serialize`.
224 fun serialize_to
(serializer
: Serializer) do serializer
.serialize
(self)
226 # Actual serialization of `self` to `serializer`
228 # This writes the full data of `self` to `serializer`.
230 # This method can be redefined in sub classes and refinements.
231 # It should use `Serializer::serialize_attribute` to to register real or
232 # logical attributes.
234 # Any refinement should have its equivalent refinement of
235 # `Deserializer::deserialize_class` to support this custom deserialization.
236 fun core_serialize_to
(serializer
: Serializer) do end
238 # Accept references or force direct serialization (using `serialize_to`)
240 # The subclass change the default behavior, which will accept references,
241 # to force to always serialize copies of `self`.
242 private fun serialize_to_or_delay
(v
: Serializer) do v
.serialize_reference
(self)
244 # Create an instance of this class from the `deserializer`
246 # This constructor is refined by subclasses to correctly build their instances.
247 init from_deserializer
(deserializer
: Deserializer) is nosuper
do end
250 # Instances of this class are not delayed and instead serialized immediately
251 # This applies mainly to `universal` types
252 interface DirectSerializable
255 redef fun serialize_to_or_delay
(v
) do serialize_to
(v
)
258 redef class Bool super DirectSerializable end
259 redef class Char super DirectSerializable end
260 redef class Byte super DirectSerializable end
261 redef class Int super DirectSerializable end
262 redef class Float super DirectSerializable end
263 redef class CString super DirectSerializable end
264 redef class Text super DirectSerializable end
265 redef class SimpleCollection[E
] super Serializable end
266 redef class Map[K
, V
] super Serializable end
268 redef class Couple[F
, S
]
271 redef init from_deserializer
(v
)
273 v
.notify_of_creation
self
274 var first
= v
.deserialize_attribute
("first")
275 var second
= v
.deserialize_attribute
("second")
279 redef fun core_serialize_to
(v
)
281 v
.serialize_attribute
("first", first
)
282 v
.serialize_attribute
("second", second
)
289 redef init from_deserializer
(v
)
291 v
.notify_of_creation
self
292 var item
= v
.deserialize_attribute
("item")
296 redef fun core_serialize_to
(v
)
298 v
.serialize_attribute
("item", first
)
305 redef init from_deserializer
(v
)
307 v
.notify_of_creation
self
309 var message
= v
.deserialize_attribute
("message")
310 if not message
isa String then message
= ""
313 var cause
= v
.deserialize_attribute
("cause")
314 if cause
isa nullable Error then self.cause
= cause
317 redef fun core_serialize_to
(v
)
319 v
.serialize_attribute
("message", message
)
320 v
.serialize_attribute
("cause", cause
)
325 # core::queue classes
327 redef abstract class ProxyQueue[E
]
329 redef init from_deserializer
(v
)
331 v
.notify_of_creation
self
333 var seq
= v
.deserialize_attribute
("seq", (new GetName[Sequence[E
]]).to_s
)
334 if not seq
isa Sequence[E
] then seq
= new Array[E
]
335 if v
.deserialize_attribute_missing
then
336 v
.errors
.add
new AttributeMissingError(self, "seq")
342 redef fun core_serialize_to
(v
) do v
.serialize_attribute
("seq", seq
)
345 redef class RandQueue[E
]
347 redef init from_deserializer
(v
)
349 v
.notify_of_creation
self
351 var seq
= v
.deserialize_attribute
("seq", (new GetName[SimpleCollection[E
]]).to_s
)
352 if not seq
isa SimpleCollection[E
] then seq
= new Array[E
]
353 if v
.deserialize_attribute_missing
then
354 v
.errors
.add
new AttributeMissingError(self, "seq")
360 redef fun core_serialize_to
(v
) do v
.serialize_attribute
("seq", seq
)
363 redef class MinHeap[E
]
365 redef init from_deserializer
(v
)
367 v
.notify_of_creation
self
369 var items
= v
.deserialize_attribute
("items", (new GetName[SimpleCollection[E
]]).to_s
)
370 if not items
isa Array[E
] then items
= new Array[E
]
371 if v
.deserialize_attribute_missing
then
372 v
.errors
.add
new AttributeMissingError(self, "items")
375 var comparator
= v
.deserialize_attribute
("comparator", "Comparator")
376 if not comparator
isa Comparator then comparator
= default_comparator
377 if v
.deserialize_attribute_missing
then
378 v
.errors
.add
new AttributeMissingError(self, "comparator")
382 self.items
.add_all items
385 redef fun core_serialize_to
(v
)
387 v
.serialize_attribute
("items", items
)
388 v
.serialize_attribute
("comparator", comparator
)