1 # Abstract serialization services
3 The serialization services are centered around the `auto_serializable` annotation,
4 the `Serializable` interface and the implementations of `Serializer` and `Deserializer`.
6 ## The `auto_serializable` annotation
8 A class annotated with `auto_serializable` identifies it as a subclass of Serializable and
9 triggers the generation of customized serialization and deserialization services.
14 # Simple serializable class identifying a human
21 # Year of birth (`null` if unknown)
22 var birth: nullable Int
24 redef fun ==(o) do return o isa SELF and name == o.name and birth == o.birth
25 redef fun hash do return name.hash
29 The `Person` class also defines `==` and `hash`, this is optional but we will use it to make an important point.
30 By definition of a serializable class, an instance can be serialized to a stream, then deserialized.
31 The deserialized instance will not be the same instance, but they should be equal.
32 So, in this case, we can compare both instances with `==` to test their equality.
34 Some conditions applies to the classes that can be annotated as `auto_serializable`.
35 All attributes of the class must be serializable, runtime errors will be
36 raised when trying to serialize non-serializable attributes.
38 In the class `Person`, all attributes are typed with classes the standards library.
39 These common types are defined defined as serializable by this project.
40 The attributes could also be typed with user-defined `auto_serializable`
41 classes or any other subclass of `Serializable`.
44 # This `auto_serializable` class is composed of two `auto_serializable` attributes
51 redef fun ==(o) do return o isa SELF and partner_a == o.partner_a and partner_b == o.partner_b
52 redef fun hash do return partner_a.hash + 1024*partner_b.hash
56 The `auto_serializable` applies only to the class definition,
57 only attributes declared locally will be serialized.
58 However, each definition of a class (a refinement or specialization)
59 can declare `auto_serializable`.
61 ## Custom serializable classes
63 The annotation `auto_serializable` should be enough for most cases,
64 but in some cases you need more control over the serialization process.
66 For more control, create a subclass to `Serializable` and redefine `core_serialize_to`.
67 This method should use `Serializer::serialize_attribute` to serialize its components.
68 `serialize_attribute` works as a dictionary and organize attributes with a key.
70 You will also need to redefine `Deserializer::deserialize_class` to support this specific class.
71 The method should only act on known class names, and call super otherwise.
73 ### Example: the User class
75 The following example cannot use the `auto_serializable` annotations
76 because some of the arguments to the `User` class need special treatment:
78 * The `name` attribute is perfectly normal, it can be serialized and deserialized
81 * The `password` attribute must be encrypted before being serialized,
82 and unencrypted on deserialization.
84 * The `avatar` attributes is kept as ASCII art in memory.
85 It could be serialized as such but it is cleaner to only
86 serialize the path to its source on the file system.
87 The data is reloaded on deserialization.
89 For this customization, the following code snippet implements
90 two serialization services: `User::core_serialize_to` and
91 `Deserializer::deserialize_class`.
94 module user_credentials
96 # User credentials for a website
103 # Clear text password
106 # User's avatar image as data blob
109 redef fun core_serialize_to(serializer: Serializer)
111 # This is the normal serialization process
112 serializer.serialize_attribute("name", name)
114 # Serialized an encrypted version of the password
116 # Obviously, `rot(13)` is not a good encrption
117 serializer.serialize_attribute("pass", password.rot(13))
119 # Do not serialize the image, only its path
120 serializer.serialize_attribute("avatar_path", avatar.path)
124 redef class Deserializer
125 redef fun deserialize_class(name)
127 if name == "User" then
128 # Deserialize normally
129 var user = deserialize_attribute("name")
132 var pass = deserialize_attribute("pass").rot(-13)
134 # Deserialize the path and load the avatar from the file system
135 var avatar_path = deserialize_attribute("avatar_path")
136 var avatar = new Image(avatar_path)
138 return new User(user, pass, avatar)
145 # An image loaded in memory as ASCII art
147 # Not really useful for this example, provided for consistency only.
149 # Path on the filesystem for `self`
152 # ASCII art composing this image
153 var ascii_art: String = path.read_all is lazy
158 See the documentation of the module `serialization::serialization` for more
159 information on the services to redefine.
161 ## Serialization services
163 The `auto_serializable` annotation and the `Serializable` class are used on
164 classes specific to the business domain.
165 To write (and read) instances of these classes to a persistent format
166 you must use implementations of `Serializer` and `Deserializer`.
168 The main implementations of these services are `JsonSerializer` and `JsonDeserializer`,
169 from the `json_serialization` module.
172 import json_serialization
173 import user_credentials
175 # Data to be serialized and deserialized
176 var couple = new Partnership(
177 new Person("Alice", 1985, new Image("alice.png")),
178 new Person("Bob", null, new Image("bob.png")))
180 var path = "serialized_data.json"
181 var writer = new FileWriter(path)
182 var serializer = new JsonSerializer(writer)
183 serializer.serialize couple
186 var reader = new FileReader(path)
187 var deserializer = new JsonDeserializer(reader.to_s)
188 var deserialized_couple = deserializer.deserialize
191 assert couple == deserialize_couple
194 ## Limitations and TODO
196 The serialization has some limitations:
198 * Not enough classes from the standard library are supported.
199 This only requires someone to actually code the support.
200 It should not be especially hard for most classes, some can
201 simply declare the `auto_serializable` annotation.
203 * A limitation of the Json parser prevents deserializing from files
204 with more than one object.
205 This could be improved in the future, but for now you should
206 serialize a single object to each filesand use different instances of
207 serializer and deserializer each time.
209 * The `auto_serializable` annotation does not handle very well
210 complex constructors. This could be improved in the compiler.
211 For now, you may prefer to use `auto_serializable` on simple classes,
212 of by using custom `Serializable`.
214 * The serialization uses only the short name of a class, not its qualified name.
215 This will cause problem when different classes using the same name.
216 This could be solved partially in the compiler and the library.
217 A special attention must be given to the consistency of the name across
218 the different programs sharing the serialized data.
220 * The serialization support in the compiler need some help to
221 deal with generic types. The solution is to use `nitserial`,
222 the next section explores this subject.
224 ## Dealing with generic types
226 One limitation of the serialization support in the compiler is with generic types.
227 For example, the `Array` class is generic and serializable.
228 However, the runtime types of Array instances are parameterized and are unknown to the compiler.
229 So the compiler won't support serializing instances of `Array[MySerializable]`.
231 The tool `nitserial` solves this problem at the level of user modules.
232 It does so by parsing a Nit module, group or project to find all known
233 parameterized types of generic classes.
234 It will then generating a Nit module to handle deserialization of these types.
236 Usage steps to serialize parameterized types:
238 * Write your program, let's call it `my_prog.nit`,
239 it must use some parameterized serializable types.
240 Let's say that you use `Array[MySerializable]`.
242 * Run nitserial using `nitserial my_prog.nit` to
243 generate the file `my_prog_serial.nit`.
245 * Compile your program by mixing in the generated module with:
246 `nitc my_prog.nit -m my_prog_serial.nit`
248 This was a simple example, in practical cases you may need
249 to use more than one generated file.
250 For example, on a client/server system, an instance can be created
251 server-side, serialized and the used client-side.
252 In this case, two files will be generated by nitserial,
253 one for the server and one for the client.
254 Both the files should be compiled with both the client and the server.