| Qore Programming Language Reference Manual 1.0.8

Public Member Functions | Static Public Member Functions | Private Member Functions | List of all members
Qore::Serializable Class Reference

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

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)
| 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 Functions
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 Member Functions
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 | ( | 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() [2/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() [3/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

## ◆ deserialize() [4/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

## ◆ 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;
  }
  }

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

## ◆ 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

  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

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

## ◆ 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-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]

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)

## ◆ 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

  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)