Qore Programming Language Reference Manual 2.0.0
Loading...
Searching...
No Matches
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:
[legend]

Public Member Functions

 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, *int flags)
 converts the object to binary data representing the object
 
binary serialize (*int flags)
 converts the object to binary data representing the object
 
hash< SerializationInfoserializeToData (*int flags)
 converts the object to a serialization hash representing the object
 

Static Public Member Functions

static auto deserialize (InputStream stream, *int flags)
 Deserializes data produced with serialize() and returns the value represented by the data.
 
static auto deserialize (binary bin, *int flags)
 Deserializes data produced with serialize() and returns the value represented by the data.
 
static auto deserialize (string bin, *int flags)
 Deserializes data produced with serialize() and returns the value represented by the data.
 
static auto deserialize (hash< SerializationInfo > data, *int flags)
 Deserializes data produced with serializeToData() and returns the value represented by the data.
 
static hash< SerializationInfodeserializeToData (InputStream stream, *int flags)
 Deserializes data produced with serialize() and returns the value represented by the data.
 
static hash< SerializationInfodeserializeToData (binary bin, *int flags)
 Deserializes data produced with serialize() and returns the value represented by the data.
 
static serialize (auto val, OutputStream stream, *int flags)
 serializes the data and writes the serialized data to the given output stream
 
static binary serialize (auto val, *int flags)
 serializes the data and returns the serialized data as a binary object
 
static hash< SerializationInfoserializeToData (auto val, *int flags)
 converts the value to a serialization hash representing the value
 

Private Member Functions

nothing deserializeMembers (hash< auto > members)
 overrides the default automatic member assignment logic for user classes during data deserialization
 
*hash< auto > serializeMembers (*hash< auto > members)
 overrides the default automatic member retrieval for user classes during data serialization
 

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,
*int flags )
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
binbinary data representing serialized data as generated by serialize()
flagsoptional deserialization flags as a bitfield
Returns
the value represented by the data
Exceptions
DESERIALIZATION-ERRORthe 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,
*int flags )
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
datathe data representing the object as generated by serializeToData()
flagsoptional deserialization flags as a bitfield
Returns
the value represented by the data
Exceptions
DESERIALIZATION-ERRORthe 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,
*int flags )
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
streaman input stream providing serialized binary data as generated by serialize()
flagsoptional deserialization flags as a bitfield
Returns
the value represented by the serialization stream
Exceptions
DESERIALIZATION-ERRORthe 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,
*int flags )
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
binbinary data representing serialized data as generated by serialize()
flagsoptional deserialization flags as a bitfield
Returns
the value represented by the data
Exceptions
DESERIALIZATION-ERRORthe 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

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;
}
}
main Qore-language namespace
Definition Pseudo_QC_All.dox.h:3

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
memberslocally-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,
*int flags )
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
binbinary data representing serialized data as generated by serialize()
flagsoptional deserialization flags as a bitfield
Returns
the intermediate SerializationInfo hash value represented by the input data
Exceptions
DESERIALIZATION-ERRORthe 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,
*int flags )
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
streaman input stream providing serialized binary data as generated by serialize()
flagsoptional deserialization flags as a bitfield
Returns
the intermediate SerializationInfo hash value represented by the serialization stream
Exceptions
DESERIALIZATION-ERRORthe 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 ( *int flags)

converts the object to binary data representing the object

Example:
binary b = obj.serialize();
Parameters
flagsoptional serialization flags as a bitfield
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-ERRORthe 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,
*int flags )
static

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

Example:
binary bin = Serializable::serialize(val);
Parameters
valthe data to serialize
flagsoptional serialization flags as a bitfield
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-ERRORthe 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,
*int flags )
static

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

Example:
Serializable::serialize(val, stream);
Parameters
valthe data to serialize
streaman output stream where the serialized data will be written
flagsoptional serialization flags as a bitfield

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-ERRORthe 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,
*int flags )

converts the object to binary data representing the object

Example:
obj.serialize(stream);
Parameters
streaman output stream where the serialized data will be written
flagsoptional serialization flags as a bitfield

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-ERRORthe 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

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
memberslocally-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 ( *int flags)

converts the object to a serialization hash representing the object

Code Flags:
RET_VALUE_ONLY
Example:
hash<SerializationInfo> h = obj.serializeToData();
Parameters
flagsoptional serialization flags as a bitfield
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-ERRORthe 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,
*int flags )
static

converts the value to a serialization hash representing the value

Code Flags:
RET_VALUE_ONLY
Example:
hash<SerializationInfo> h = serializeToData(val);
Parameters
valthe value to serialize to a serialization data hash
flagsoptional serialization flags as a bitfield
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-ERRORthe object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)