Persistate

Serialising and Deserialising

Hide Navigation Pane

Serialising and Deserialising

Previous topic Next topic No directory for this topic  

Serialising and Deserialising

Previous topic Next topic Topic directory requires JavaScript JavaScript is required for the print function Mail us feedback on this topic!  

The Persistate runtime includes two classes which allow you to serialise a portion of the persistent tree to a Message or a file, which can then be deserialised to reconstitute the original tree. Persistate uses these classes to serialise packages for deployment - see the Deploy operation in Generator only operations.  The two classes are complementary - the Messages, Streams and files used by TreeDeserialiser must have been produced by TreeSerialiser.

The TreeSerialiser class

The TreeSerialiser class serialises the tree of objects - the subtree - under a particular root object.  The subtree can be part of the  persistent tree, or can be a provisional tree (not persisted) in memory only. TreeSerialiser uses the Persistent.CallTree method to perform this serialisation, so the generated CallTree methods for each class are used to descend the tree.  The serialisation process happens in two stages, with each stage performing a tree descent.

In the first descent, the nodes of the containment tree are serialised.  Two important points to note.  Firstly, collections of selected objects are not serialised.  Secondly, for collections of many objects, only the subset of the collection which is currently in the IndexedList property is serialised.
In the second descent, associations are added.  This is done in a second descent so that those associations which refer to objects within the serialised subtree can be serialised as indexes to the appropriate serialised node.  If course, this leaves associations which refer to objects outside the serialised subtree.  If possible these are serialised as MetaReferences.  This can only be done if the target of the association is IMetaReferable, otherwise a Reference is serialised.  See References and MetaReferences for details.

When you perform a tree serialisation, you can optionally supply a SerialiserFilter delegate.  If supplied, this delegate is called for every node in the serialised subtree.  The SerialiserFilter is supplied with information concerning the node being serialised and can return true or false.  If it returns false, the node is not serialised, and nor are any of the nodes under it in the subtree.  This allows you to selectively filter out portions of the subtree from the output.

The TreeSerialiser class contains the following methods you can use.  This is intended to list the capabilities of the class - see the API documentation for full details.

Serialise(Persistent root, string filePath, SerialiserFilter filter).  This method serialises the subtree of the given root object, and writes the result to a file with the given path and file name.  The serialisation process is filtered by the given filter.  You can reconstitute the subtree using the Deserialise(string filePath) method.
Serialise(Persistent root, SerialiserFilter filter).  This method serialises the subtree of the given root object to a Message object.  The serialisation process is filtered by the given filter.  You can reconstitute the subtree using the Deserialise(Message message) method.
Write(Message[] messages, string filePath).  This method writes an array of Message objects to a file with the given path and file name.  You can use this method in conjunction with the above method to serialise several subtrees and write the output of all to one file.  You can retrieve the Messages using the Read(string filePath, int count) method.
Write(Message[] messages, Stream stream).  This method writes an array of Message objects to a stream.  You can use this method in conjunction with the above method to serialise several subtrees and write the output of all to one stream.  You can retrieve the Messages using the Read(Stream stream, int count) method.

The TreeDeserialiser class

The TreeDeserialiser class takes the output of the TreeSerialiser class and deserialises it to reconstitute the original tree of objects.  The reconstituted tree is not attached to the persistent tree, but is "provisional" - not yet persisted to a database.  This is true even if the serialised tree was part of the persistent tree.  You can attach the entire reconstituted subtree to the persistent tree by simply adding the root object to a persistent collection or setting it into a contained scalar member.

During the deserialisation process, any associations which were within the serialised subtree are recreated without problem.  For associations which referred to objects outside the serialised subtree, then TreeDeserialiser attempts to dereference the serialised MetaReference or Reference, but of course this may not be successful.  In order to deal with this problem, you can set an event handler for the Session.ResolveReference event.  This event will be triggered when a dereference fails, and you can supply a replacement MetaReference, Reference or target object.  See References and MetaReferences.

The TreeDeserialiser class contains the following methods you can use.  This is intended to list the capabilities of the class - see the API documentation for full details.

Deserialise(string filePath).  This method reconstitutes a subtree from the serialised information in the file with the given path and file name. The file must have been written using one of the TreeSerialiser methods, but note that this uses only the first Message written to the file.
Read(string filePath, int count).  This method reads and returns a given number of Message objects from a file.  The file must have been written using one of the TreeSerialiser methods.
Deserialise(Stream stream).  This method reconstitutes a subtree from the serialised information in a Stream.  The stream must be connected to the one used by the Write(Message[] messages, Stream stream) method or connected to a file produced by one of the TreeSerialiser methods, but note that this uses only the first Message written to the file or Stream.
Read(Stream stream, int count).  This method reads and returns a given number of Message objects from a stream.  The stream must be connected to the one used by the Write(Message[] messages, Stream stream) method or connected to a file produced by one of the TreeSerialiser methods.
Deserialise(Message message).  This method reconstitutes a subtree from the serialised information in a Message.  The Message must have been produced by, or be from a file or Stream produced by one of the TreeSerialiser methods.