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

Static Public Member Methods

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

Private:Internal Member Methods

nothing deserializeMembers (hash< auto > members)
 overrides the default automatic member assignment logic for user classes during data deserialization
 
__7_ hash< autoserializeMembers (__7_ 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,
__7_ 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,
__7_ 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,
__7_ 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,
__7_ 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: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;
}
}
Qore namespace.
Definition QC_AbstractSmartLock.dox.h:2

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,
__7_ 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,
__7_ 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 ( __7_ 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,
__7_ 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,
__7_ 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,
__7_ 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()

__7_ hash< auto > Qore::Serializable::serializeMembers ( __7_ 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
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 ( __7_ 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,
__7_ 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)