ISerializable

Description

interface Tinman.Core.IO.Serialization.ISerializable

Extended by

CxNode abstract
IColorRamp
ICurve
IDatumTransform
IDocumentNode
IGeoObject
IGeoRegistry
IHeightmapFormat
IJsonValue
INoiseFunctionBase
IRasterTransform
IShape
SerializableBase abstract
SerializableDisposableBase abstract

A class that supports serialization must implement this interface.

The following concepts exist for serializable objects:

  • Serial Type
    The SerialType property returns a ISerialTypeInfo object which uniquely identifies the serial type of the ISerializable object. Type objects are singletons may be compared via identity.

  • Default Instance
    Every solid implementation class (i.e. non-abstract) of ISerializable must provide a public default constructor. This is required by ISerialTypeInfo.CreateInstance, which is used to create a default instance during deserialization. Usually, the default instance is a minimal object which is then initialized by Deserialize.

  • Version Number
    The SerialVersion property defines the range of serial data versions that are defined for the serial type. The SerialVersionWrite property can optionally be used to deliberately write an older version, for backward compatibility.

Public / Methods

Deserialize

public method Deserialize → (2)

serialVersion in : int32

The serial data version that has been used to write the object state, see SerialVersionWrite.

data in : ISerializer

[not-null]
The serial data stream.

returns → ISerializable

The deserialized object. This will typically be this, but in some circumstances, another instance may be returned (e.g. singletons).

Initializes the state of this object from the given data stream.

The Deserialize method will be called immediately after the object has been instantiated via its default constructor.

The provided serialVersion in number is guaranteed to be equal to or less than the SerialVersion returned by this object (i.e. ISerializable object must provide backwards compatibility).

IOException

If an I/O error has occurred.

See also

ISerializable.Serialize
ISerializable.SerialVersion

Serialize

public method Serialize → (2)

serialVersion in : int32

The serial data version to use for writing the object state, as returned by SerialVersionWrite.

data in : ISerializer

[not-null]
The serial data stream.

Serializes the current state of this object to the given data stream.

IOException

If an I/O error has occurred.

See also

ISerializable.Deserialize
ISerializable.SerialVersion

Public / Attributes

Serial​Type

public attribute SerialType → (get)

value : ISerialTypeInfo

[not-null]
The serial type.

Returns the serial type of this object.

Serial​Version

public attribute SerialVersion → (get)

value : int32

[>=1]
The serial data version tag.

Returns the serial data version.

The Deserialize method must support all versions up to the one returned by SerialVersion. The Serialize method must at least support the returned version, but may also support smaller versions for backward compatibility (see SerialVersionWrite).

Serial​Version​Write

public attribute SerialVersionWrite → (get)

value : RangeI

The serial data version range to use for writing. The default implementation returns a range that contains only SerialVersion, which chooses the most recent serial data version for writing.

Returns the range of serial data versions that may be passed to the subsequent call to Serialize.

RangeI.Last specifies the smallest version that will encode all information in this object losslessly, thus providing the highest amount of backward compatibility. RangeI.Start specifies the smallest version that is supported by Serialize. This results in the following serial version intervals (bounds are inclusive):

  • RangeI.Last to SerialVersion
    All information is encoded losslessly, possibly using different binary formats.

  • RangeI.Start to RangeI.Last - 1
    Some information is encoded, possibly lossy. This is used only in very specific cases, where the loss of information is taken into account and handled by suitable logic.

  • 1 to RangeI.Start - 1
    The version cannot be used, an IOException is thrown.

The ISerializer.WriteObjectVersion method can be used to specify a serial version range per ISerialTypeInfo.