Mixin class that provides a standard serialization interface. More...

#include <Serializable.h>

Inheritance diagram for Hypertable::Serializable:

Public Member Functions
virtual size_t	encoded_length () const
	Returns serialized object length. More...

virtual void	encode (uint8_t **bufp) const
	Writes serialized representation of object to a buffer. More...

virtual void	decode (const uint8_t *bufp, size_t remainp)
	Reads serialized representation of object from a buffer. More...

Protected Member Functions
virtual uint8_t	encoding_version () const =0
	Returns encoding version. More...

virtual size_t	encoded_length_internal () const =0
	Returns internal serialized length. More...

virtual void	encode_internal (uint8_t **bufp) const =0
	Writes serialized representation of object to a buffer. More...

virtual void	decode_internal (uint8_t version, const uint8_t *bufp, size_t remainp)=0
	Reads serialized representation of object from a buffer. More...

Detailed Description

Mixin class that provides a standard serialization interface.

This class is designed to provide a standard serialization interface to any class. It allows the serialization of a class to be extended in such a way to allow for both backward and forward compatibility. It accomplishes this by encoding a header at the beginning of the serialization that includes a version number and the length of the remaining encoding. An encoding version can be extended in a forward compatible way by adding additional encoded state at the end of the encoding. This additional encoding will be skipped by older decoders and newer decoders can decode older encodings (of the same version) by returning once the end of the serialization is reached. For example, let's say that you create an encoding that initially just encodes a 32-bit integer and then is later extended to included an additional string. To handle the decoding in a backward and forward compatible way, the decode_internal() function should be implemented as follows:

void decode_internal(uint8_t version, const uint8_t **bufp, size_t *remainp) {
  if (version == 1) {
    m_num = Serialization::decode_i32(bufp, remainp);
    // Check to see if we're at the end of the record and if so return.
    if (*remainp == 0)
      return;
    m_str = Serialization::decode_vstr(bufp, remainp);
  }
}

A change in the encoding version number means that the encoding has changed in a forward incompatible way. The decode() function will throw an Exception with code Error::PROTOCOL_ERROR if the version being decoded is greater than the version returned by encoding_version().

Definition at line 65 of file Serializable.h.

Member Function Documentation

void Serializable::decode	(	const uint8_t **	bufp,
		size_t *	remainp
	)

virtual

Reads serialized representation of object from a buffer.

Parameters

bufp	Address of destination buffer pointer (advanced by call)
remainp	Address of integer holding amount of remaining buffer

See also: encode() for encoding format

Exceptions

Exception with code Error::PROTOCOL_ERROR if version being decoded is greater than that returned by encoding_version().

Reimplemented in Hypertable::MetaLog::EntityRecover.

Definition at line 70 of file Serializable.cc.

virtual void Hypertable::Serializable::decode_internal	(	uint8_t	version,
		const uint8_t **	bufp,
		size_t *	remainp
	)

protectedpure virtual

Reads serialized representation of object from a buffer.

This function is to be overridden by derived classes and should decode the object per-se as encoded with encode_internal().

Parameters

version	Encoding version
bufp	Address of destination buffer pointer (advanced by call)
remainp	Address of integer holding amount of serialized encoding remaining

See also: encode_internal() for encoding format

void Serializable::encode ( uint8_t ** bufp ) const

virtual

Writes serialized representation of object to a buffer.

This function encodes a serialized representation of the object, starting with a header that includes the encoding version and the serialized length of the object. After the header, the object per-se is encoded with encode_internal().

Parameters

bufp	Address of destination buffer pointer (advanced by call)

Encoding is as follows:

Encoding	Description
1 byte	Encoding version as returned by encoding_version()
vint	Length of encoded object as returned by encoded_length_internal()
variable	Object encoded with encode_internal()

Reimplemented in Hypertable::MetaLog::EntityRecover.

Definition at line 64 of file Serializable.cc.

virtual void Hypertable::Serializable::encode_internal ( uint8_t ** bufp ) const

protectedpure virtual

Writes serialized representation of object to a buffer.

This function is to be overridden by derived classes and should encode the object per-se.

Parameters

bufp	Address of destination buffer pointer (advanced by call)

size_t Serializable::encoded_length ( ) const

virtual

Returns serialized object length.

Returns the serialized length of the object as encoded by encode().

See also: encode() for encoding format

Returns: Overall serialized object length

Reimplemented in Hypertable::MetaLog::EntityRecover.

Definition at line 37 of file Serializable.cc.

virtual size_t Hypertable::Serializable::encoded_length_internal ( ) const

protectedpure virtual

Returns internal serialized length.

This function is to be overridden by derived classes and should return the length of the the serialized object per-se.

Returns: Internal serialized length

See also: encode_internal() for encoding format

virtual uint8_t Hypertable::Serializable::encoding_version ( ) const

protectedpure virtual

Returns encoding version.

Returns: Encoding version

The documentation for this class was generated from the following files:

/home/doug/src/hypertable/src/cc/Common/Serializable.h
/home/doug/src/hypertable/src/cc/Common/Serializable.cc

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation