Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

Function set core_serialization

Function used to store items persistently. more...


Function list

deserialize Deserialize an item from a stream.
serialize Serializes an item on a stream.

Detailed description

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.


Functions

deserialize()

Deserialize an item from a stream.

deserialize( stream )
stream

An instance of the Stream (or derived) class.

Raises:
IoError

on underlying stream error.

GenericError

If the data is correctly de-serialized, but it refers to external symbols non defined by this script.

ParseError

if the format of the input data is invalid.

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. This call is equivalent to call Stream.readItem method.

serialize()

Serializes an item on a stream.

serialize( stream, item )
stream

An instance of the Stream (or derived) class.

item

The item to be serialized.

Raises:
IoError

on underlying stream error.

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. Also, the method Stream.writeItem is equivalent to this function; the difference in BOM.serialize() and Stream.writeItem() is only in the fact that Item.serialize() accepts a stream on which to perform the serialization as the parameter, while Stream.writeItem() must be provided with the item to be serialized.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0