Function used to store items persistently.
Serialization functions allow to flatten a Falcon item, or a sequence of items, on a stream for later retrieval, storage or transmission. At the moment, custom serialization is not supported. This means that all the basic items, as strings and numbers, plus arrays and dictionaries are supported. Objects are partially supported: when they are fully derived from Falcon classes, or declared as "object" by the scripts, the serialization and de-serialization are successful. However, there is no mechanism to support creation of user-specific data, as the "load" that objects can carry internally in behalf of embedding applications.
Nevertheless, if there is the need, objects may be serialized/deserialized with the provided functions, and after the de-serialization step, a custom mechanism may be used to re-create application specific data.
However, it is necessary that the deserializing application has access to the same classes that were used to create the serialized object.
Notice that also functions are correctly serialized and deserialized. Also, static block is not re-executed in case the function is re-entered after a de-serialization.
Deserialize an item from a stream.
deserialize( stream )
| stream | An instance of the Stream (or derived) class. | ||||||
| Raise |
|
The returned item is a new copy of the item that has been previously serialized on the given stream. After the read, the stream pointer is left ready for a new read, so that items that are serialized in sequence may be deserialized in the same order.
If the underlying stream read causes an i/o failure, an error is raised.
Also, an error is raised if the function cannot deserialize from the stream because the data format is invalid.
Serializes an item on a stream.
serialize( item, stream )
| item | The item to be serialized. | ||
| stream | An instance of the Stream (or derived) class. | ||
| Raise |
|
The item is stored on the stream so that a deserialize() call on the same position in the stream where serialization took place will create an exact copy of the serialized item.
The application must ensure that the item does not contains circular references, or the serialization will enter an endless loop.
In case the underlying stream write causes an i/o failure, an error is raised.
The BOM method BOM.serialize is available for all the Falcon items, and is equivalent to call this function.