Serializer

The Serializer class is specialized to store and restore the members of an Object.

PropertyPublisher: A Serializer serializes trees of classes and struct that implement the PropertyPublisher interface. Their publications define what is saved or restored. Object descriptors leading to an owned Object define the structure. Basics types and array of basic types are handled. Special cases exist to manage Stream properties, delegates or objects that are stored in the ReferenceMan. It's even possible to handle more complex types by using or writing custom PropertyPublishers, such as those defined in iz.classes.

Ownership: Sub objects can be fully serialized or not. This is determined by the ownership. A sub object is considered as owned when its member 'declarator' matches to to the member 'declarator' of the descriptor that returns this sub object. When not owned, the sub object publications are not stored, instead, the serializer writes its unique identifier, as found in the ReferenceMan. When deserializing, the opposite process happens: the serializer tries to restore the reference using the ReferenceMan. Ownership is automatically set by the PropertyPubliserImpl analyzers.

Representation: The serializer uses an intermediate serialization tree (IST) that ensures a certain flexibilty against a traditional single-shot sequential serialization. As expected for a serializer, object trees can be stored or restored by a simple and single call to publisherToStream() in pair with streamToPublisher() but the IST also allows to convert a Stream or to find and restores a specific property.

Errors: Two events (onWantDescriptor and onWantAggregate) allow to handle the errors that could be encountered when restoring. They permit a PropertyPublisher to be modified without any risk of deserialization failure. Data saved from an older version can be recovered by deserializing in a temporary property and converted to a new type. They can also be skipped, without stopping the whole processing. Missing objects can be created when The serializer ask for, since in this case, the original Object type and the original variable names are passed as hint.

Hints: The serializer handles the PropHints of the publications. If PropHint.dontSet is in the hints then a property is not restored. If PropHint.dontGet is in the hints then the property is not stored. These two hints allow to deprecate some publications, without breaking the restoration. The hint PropHint.initCare indicates that a property equal to its initializer is written. For floating point types there is an exception that is the intializer is considered to be 0.

Constructors

this
this()

Destructor

A destructor is present on this object, but not explicitly documented in the source.

Members

Functions

findNode
IstNode findNode(const(char)[] descriptorName)

Finds the tree node matching to an identifier chain.

istToPublisher
void istToPublisher(ref R root)

Restores the IST to a PropertyPublisher.

istToStream
void istToStream(Stream outputStream, SerializationFormat format = defaultFormat)

Saves the IST to a Stream.

nodeToProperty
void nodeToProperty(IstNode node, PropDescriptor!T* descriptor = null)

Restores the property associated to an IST node using the setter of the PropDescriptor passed as parameter.

nodeToPublisher
void nodeToPublisher(IstNode node, bool recursive = false)

Restores the IST from an arbitrary tree node.

publisherToIst
void publisherToIst(Object root)

Builds the IST from a PropertyPublisher.

publisherToIst
void publisherToIst(ref S root)

Builds the IST from a struct that has the traits of a property publisher.

publisherToStream
void publisherToStream(Object root, Stream outputStream, SerializationFormat format = defaultFormat)
void publisherToStream(ref S root, Stream outputStream, SerializationFormat format = defaultFormat)

Builds the IST from a PropertyPublisher and stores each publication of the publisher in a stream.

streamToIst
void streamToIst(Stream inputStream, SerializationFormat format = defaultFormat)

Builds the IST from a Stream.

streamToPublisher
void streamToPublisher(Stream inputStream, ref R root, SerializationFormat format = defaultFormat)
void streamToPublisher(Stream inputStream, R root, SerializationFormat format = defaultFormat)

Builds the IST from a Stream and restores from root.

updateCache
void updateCache()

Updates the cache optionally used in findNode().

Properties

onFinishAggregate
void delegate(void*) onFinishAggregate [@property setter]
void delegate(void*) onFinishAggregate [@property getter]

Event called when the serializer finishes to destream an aggregate.

onWantAggregate
WantAggregateEvent onWantAggregate [@property getter]
WantAggregateEvent onWantAggregate [@property setter]

Event called when the serializer misses an aggregate

onWantDescriptor
WantDescriptorEvent onWantDescriptor [@property getter]
WantDescriptorEvent onWantDescriptor [@property setter]

Event called when the serializer misses a property descriptor.

serializationTree
IstNode serializationTree [@property getter]

The IST can be modified, build, cleaned from the root node

Examples

1 // defines two serializable classes
2 class B: PropertyPublisher
3 {
4     mixin PropertyPublisherImpl;
5     @SetGet uint data1 = 1, data2 = 2;
6     this(){collectPublications!B;}
7     void reset(){data1 = 0; data2 = 0;}
8 }
9 class A: PropertyPublisher
10 {
11     mixin PropertyPublisherImpl;
12     @SetGet B sub1, sub2;
13     this()
14     {
15         sub1 = construct!B;
16         sub2 = construct!B;
17         // sub1 and sub2 are fully serialized because they already exist
18         // when the analyzers run, otherwise they would be considered as
19         // reference and their members would not be serialized.
20         collectPublications!A;
21     }
22     ~this(){destructEach(sub1, sub2);}
23 }
24 
25 MemoryStream stream = construct!MemoryStream;
26 Serializer serializer = construct!Serializer;
27 A a = construct!A;
28 // serializes
29 serializer.publisherToStream(a, stream);
30 
31 // reset the fields
32 a.sub1.reset;
33 a.sub2.reset;
34 stream.position = 0;
35 // deserializes
36 serializer.streamToPublisher(stream, a);
37 // check the restored values
38 assert(a.sub1.data1 == 1);
39 assert(a.sub2.data1 == 1);
40 assert(a.sub1.data2 == 2);
41 assert(a.sub2.data2 == 2);
42 // cleanup
43 destructEach(a, serializer, stream);

Meta