Qore::Serializable Class Reference

The Serializable class can be used to mark a class as being serializable. More...

#include <QC_Serializable.dox.h>

Inheritance diagram for Qore::Serializable:

Public Member Methods
	constructor ()
	The constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class.
	copy ()
	The copy constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class.
	serialize (OutputStream stream)
	converts the object to binary data representing the object More...
binary	serialize ()
	converts the object to binary data representing the object More...
hash< SerializationInfo >	serializeToData ()
	converts the object to a serialization hash representing the object More...

Static Public Member Methods
static auto	deserialize (InputStream stream)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static auto	deserialize (binary bin)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static auto	deserialize (string bin)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static auto	deserialize (hash< SerializationInfo > data)
	Deserializes data produced with serializeToData() and returns the value represented by the data. More...
static hash< SerializationInfo >	deserializeToData (InputStream stream)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static hash< SerializationInfo >	deserializeToData (binary bin)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static	serialize (auto val, OutputStream stream)
	serializes the data and writes the serialized data to the given output stream More...
static binary	serialize (auto val)
	serializes the data and returns the serialized data as a binary object More...
static hash< SerializationInfo >	serializeToData (auto val)
	converts the value to a serialization hash representing the value More...

Private:Internal Member Methods
nothing	deserializeMembers (hash< auto > members)
	overrides the default automatic member assignment logic for user classes during data deserialization More...
*hash< auto >	serializeMembers (*hash< auto > members)
	overrides the default automatic member retrieval for user classes during data serialization More...

Detailed Description

The Serializable class can be used to mark a class as being serializable.

This class serves two purposes; to mark classes as serializable and then to implement the actual serialization and deserialization methods.

This class may also be inherited as private:internal to mark it as serializable (in this case the serialization methods are only available inside the class itself).

Objects are serialized very efficiently; each object in a data structure will only be serialized once, even if it appears multiple times in the data structure. Recursive references and cyclic graphs of objects are also supported for serialization.

Classes that do not inherit this class cannot be serialized; if any non-transient member of a serializable class holds an object from a class that does not inherit this class, a SERIALIZATION-ERROR will be thrown when the object is attempted to be serialized.

Furthermore any attempt to serialize a closures, call references, or a reference will result in a SERIALIZATION-ERROR as well.

Since

Qore 0.9

Member Function Documentation

deserialize() [1/4]

static auto Qore::Serializable::deserialize ( binary  bin )

static

Deserializes data produced with serialize() and returns the value represented by the data.

Code Flags:

RET_VALUE_ONLY

Example:

auto val = Serializable::deserialize(bin);    

Parameters

bin	binary data representing serialized data as generated by serialize()

Returns

the value represented by the data

Exceptions

DESERIALIZATION-ERROR

the data cannot be deserialized due to an error in the serialization format or a reference to an unknown class or Hashdecl: Type-Safe Hash Declarations

deserialize() [2/4]

static auto Qore::Serializable::deserialize ( hash< SerializationInfo >  data )

static

Deserializes data produced with serializeToData() and returns the value represented by the data.

Code Flags:

RET_VALUE_ONLY

Example:

auto val = Serializable::deserialize(h);

Parameters

data	the data representing the object as generated by serializeToData()

Returns

the value represented by the data

Exceptions

DESERIALIZATION-ERROR

the data cannot be deserialized due to an error in the serialization format or a reference to an unknown class or Hashdecl: Type-Safe Hash Declarations

deserialize() [3/4]

static auto Qore::Serializable::deserialize ( InputStream  stream )

static

Deserializes data produced with serialize() and returns the value represented by the data.

Code Flags:

RET_VALUE_ONLY

Example:

auto val = Serializable::deserialize(stream);

Parameters

stream

an input stream providing serialized binary data as generated by serialize()

Returns

the value represented by the serialization stream

Exceptions

DESERIALIZATION-ERROR

the data cannot be deserialized due to an error in the serialization format or a reference to an unknown class or Hashdecl: Type-Safe Hash Declarations

deserialize() [4/4]

static auto Qore::Serializable::deserialize ( string  bin )

static

Deserializes data produced with serialize() and returns the value represented by the data.

Code Flags:

RET_VALUE_ONLY

Example:

auto val = Serializable::deserialize(bin);

Parameters

bin	binary data representing serialized data as generated by serialize()

Returns

the value represented by the data

Exceptions

DESERIALIZATION-ERROR

the data cannot be deserialized due to an error in the serialization format or a reference to an unknown class or Hashdecl: Type-Safe Hash Declarations

Since

Qore 0.9.2

deserializeMembers()

nothing Qore::Serializable::deserializeMembers ( hash< auto >  members )

private:internal

overrides the default automatic member assignment logic for user classes during data deserialization

Example:

class MyClass inherits Qore::Serializable {
    private:internal {
        transient string my_special_member;
    }
 
    # when defining this member, all member assignment during deserialization must be performed by this method,
    # even for transient members, as no automatic member assignment will be performed
    deserializeMembers(*hash<auto> members) {
        my_special_member = get_special_value();
        self += members;
    }
}

This method is special in that it is only called during data deserialization for user classes for each class in a class hierarchy if the method is defined.

This method in the base class does nothing and should not be called from user classes; this method is declared private:internal to emphasize that it is only called for the local class by the internal deserialization logic; it may be declared with any access permission, but in any case the method only has an effect for the local class and not for the hierarchy, which makes it different than other Qore class methods (other than the similar serializeMembers() method.

This method can be used to implement special deserialization logic when deserializing members of a particular class in a class hierarchy.

Parameters

members

locally-defined deserialized members to assign to the local class to be assigned manually in this method; this hash will be empty if no members were serialized

Note

If this method is defined, then the class must assign its own members including transient members, as automatic member initialization will not be performed for the local class by the deserialization logic in this case.

See also

serializeMembers()

deserializeToData() [1/2]

static hash< SerializationInfo > Qore::Serializable::deserializeToData ( binary  bin )

static

Deserializes data produced with serialize() and returns the value represented by the data.

Code Flags:

RET_VALUE_ONLY

Example:

hash<SerializationInfo> h = Serializable::deserializeToData(b);

Parameters

bin	binary data representing serialized data as generated by serialize()

Returns

the intermediate SerializationInfo hash value represented by the input data

Exceptions

DESERIALIZATION-ERROR

the data cannot be deserialized due to an error in the serialization format or a reference to an unknown class or Hashdecl: Type-Safe Hash Declarations

deserializeToData() [2/2]

static hash< SerializationInfo > Qore::Serializable::deserializeToData ( InputStream  stream )

static

Deserializes data produced with serialize() and returns the value represented by the data.

Code Flags:

RET_VALUE_ONLY

Example:

hash<SerializationInfo> h = Serializable::deserializeToData(stream);

Parameters

stream

an input stream providing serialized binary data as generated by serialize()

Returns

the intermediate SerializationInfo hash value represented by the serialization stream

Exceptions

DESERIALIZATION-ERROR

the data cannot be deserialized due to an error in the serialization format or a reference to an unknown class or Hashdecl: Type-Safe Hash Declarations

serialize() [1/4]

binary Qore::Serializable::serialize

(

)

converts the object to binary data representing the object

Example:

binary b = obj.serialize();

Returns

a binary object representing the object

All non-serializable data such as closures, call references, references, or non-serializable objects must be tagged as Transient Members or a SERIALIZATION-ERROR exception will be thrown.

Exceptions

SERIALIZATION-ERROR

the object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)

serialize() [2/4]

static binary Qore::Serializable::serialize ( auto  val )

static

serializes the data and returns the serialized data as a binary object

Example:

binary bin = Serializable::serialize(val);

Parameters

val	the data to serialize

Returns

serialized data representing the input data

All non-serializable data such as closures, call references, references, or non-serializable objects must be tagged as Transient Members in object members or a SERIALIZATION-ERROR exception will be thrown.

Exceptions

SERIALIZATION-ERROR

the object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)

serialize() [3/4]

static Qore::Serializable::serialize ( auto  val, OutputStream  stream  )

static

serializes the data and writes the serialized data to the given output stream

Example:

Serializable::serialize(val, stream);

Parameters

val	the data to serialize
stream	an output stream where the serialized data will be written

All non-serializable data such as closures, call references, references, or non-serializable objects must be tagged as Transient Members in object members or a SERIALIZATION-ERROR exception will be thrown.

Exceptions

SERIALIZATION-ERROR

the object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)

serialize() [4/4]

Qore::Serializable::serialize

(

OutputStream

stream

)

converts the object to binary data representing the object

Example:

obj.serialize(stream);

Parameters

stream

an output stream where the serialized data will be written

All non-serializable data such as closures, call references, references, or non-serializable objects must be tagged as Transient Members or a SERIALIZATION-ERROR exception will be thrown.

Exceptions

SERIALIZATION-ERROR

the object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)

serializeMembers()

*hash< auto > Qore::Serializable::serializeMembers ( *hash< auto >  members )

private:internal

overrides the default automatic member retrieval for user classes during data serialization

Example:

class MyClass inherits Qore::Serializable {
    private:internal {
        transient string my_special_member;
    }
 
    # if this member is defined, all members retrieved from this class will be returned only
    # by this method, as in this case no automatic member retrieval for the given class will be
    # performed
    hash<auto> serializeMembers() {
        return {
            "special_data": get_special_data(),
        }
    }
}

This method is special in that it is only called for user classes for each class in a class hierarchy if the method is defined.

This method in the base class does nothing and should not be called from user classes; this method is declared private:internal to emphasize that it is only called for the local class by the internal serialization logic; it may be declared with any access permission, but in any case the method only has an effect for the local class and not for the hierarchy, which makes it different than other Qore class methods (other than the similar deserializeMembers() method).

This method can be used to implement special serialization logic when serializing members of a particular class in a class hierarchy.

Parameters

members

locally-defined serialized non-transient members, if any

Returns

member information to be passed to the class during deserialization; overrides the default member retrieval logic during object serialization

Note

If this method is defined, then the class must return its own members, as automatic member retrieval will not be performed for the local class by the serialization logic in this case.

See also

deserializeMembers()

serializeToData() [1/2]

hash< SerializationInfo > Qore::Serializable::serializeToData

(

)

converts the object to a serialization hash representing the object

Code Flags:

RET_VALUE_ONLY

Example:

hash<SerializationInfo> h = obj.serializeToData();

Returns

a serialization hash representing the object

All non-serializable data such as closures, call references, references, or non-serializable objects must be tagged as Transient Members or a SERIALIZATION-ERROR exception will be thrown.

Exceptions

SERIALIZATION-ERROR

the object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)

serializeToData() [2/2]

static hash< SerializationInfo > Qore::Serializable::serializeToData ( auto  val )

static

converts the value to a serialization hash representing the value

Code Flags:

RET_VALUE_ONLY

Example:

hash<SerializationInfo> h = serializeToData(val);

Parameters

val	the value to serialize to a serialization data hash

Returns

a serialization hash representing the value

All non-serializable data such as closures, call references, references, or non-serializable objects must be tagged as Transient Members or a SERIALIZATION-ERROR exception will be thrown.

Exceptions

SERIALIZATION-ERROR

the object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)