Qore Programming Language Reference Manual  0.9.1
Qore::Serializable Class Reference

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

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< SerializationInfoserializeToData ()
 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 (hash< SerializationInfo > data)
 Deserializes data produced with serializeToData() and returns the value represented by the data. More...
 
static hash< SerializationInfodeserializeToData (InputStream stream)
 Deserializes data produced with serialize() and returns the value represented by the data. More...
 
static hash< SerializationInfodeserializeToData (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< SerializationInfoserializeToData (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/3]

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
streaman input stream providing serialized binary data as generated by serialize()
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() [2/3]

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
binbinary data representing serializeed data as generated by serialize()
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/3]

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
datathe data representing the object as generated by serializeToData()
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

◆ 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
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 ( 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
streaman input stream providing serialized binary data as generated by serialize()
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

◆ deserializeToData() [2/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
binbinary data representing serializeed data as generated by serialize()
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

◆ serialize() [1/4]

Qore::Serializable::serialize ( OutputStream  stream)

converts the object to binary data representing the object

Example:
obj.serialize(stream);
Parameters
streaman 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-ERRORthe object cannot be serialized as it contains non-serializable data (closures, call references, references, and non-serializable objects)

◆ serialize() [2/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-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 
)
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

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]

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
valthe 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-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: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 ( )

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