ZFSerializable Class Reference

base class of call serializable object More...

#include <ZFSerializable.h>

Inheritance diagram for ZFSerializable:

Public Member Functions
zfbool	serializable (void)
	true if object is currently serializable, see ZFSerializable
zfbool	serializeFromData (const ZFSerializableData &serializableData, zfstring *outErrorHint=zft_zfnull, ZFSerializableData *outErrorPos=zft_zfnull)
	serialize from data, see ZFSerializable
zfbool	serializeToData (ZFSerializableData &serializableData, zfstring *outErrorHint=zft_zfnull, ZFSerializable *refOwner=zft_zfnull)
	serialize to data, see ZFSerializable
zfbool	serializeFromString (const zfchar *src, zfindex srcLen=((zfindex) -1), zfstring *errorHint=zft_zfnull)
	serialize from string, return false by default
zfbool	serializeToString (zfstring &ret, zfstring *errorHint=zft_zfnull)
	see serializeFromString
void	serializablePropertyTypeGetAll (ZFCoreArray< const ZFProperty * > &notSerializableProperty, ZFCoreArray< const ZFProperty * > &serializableProperty, ZFCoreArray< const ZFProperty * > &embededProperty)
	return a list of each type of property, for debug use only
zfstring	serializablePropertyTypeInfo (void)
	return info of serializablePropertyTypeGetAll, for debug use only
void	serializableGetAllSerializablePropertyT (ZFCoreArray< const ZFProperty * > &ret)
	see serializableGetAllSerializableProperty
ZFCoreArray< const ZFProperty * >	serializableGetAllSerializableProperty (void)
	get all serializable property, usually for debug only, see serializableOnCheckPropertyType
void	serializableGetAllSerializableEmbededPropertyT (ZFCoreArray< const ZFProperty * > &ret)
	see serializableGetAllSerializableEmbededProperty
ZFCoreArray< const ZFProperty * >	serializableGetAllSerializableEmbededProperty (void)
	get all serializable embeded property, usually for debug only, see serializableOnCheckPropertyType
virtual void	serializableInfoT (zfstring &ret)
	get info as a serializable
virtual zfstring	serializableInfo (void)
	see serializableInfoT
Public Member Functions inherited from ZFInterface
virtual const ZFClass *	classData (void)=0
	get instance's class info
virtual ZFObject *	toObject (void)=0
	convert to ZFObject type

Static Public Member Functions
static const ZFClass *	ClassData (void)
	get class info
Static Public Member Functions inherited from ZFInterface
static const ZFClass *	ClassData (void)
	get class info

Protected Types
typedef ZFInterface	zfsuper
	typedef for super (always ZFInterface for an interface type)
typedef ZFSerializable	zfself
	typedef for self
Protected Types inherited from ZFInterface
typedef _ZFP_ObjI_Base	zfsuper
	typedef for super (always ZFInterface for an interface type)
typedef ZFInterface	zfself
	typedef for self

Protected Member Functions
virtual ZFSerializablePropertyType	serializableOnCheckPropertyType (const ZFProperty *property)
	check the property type that serializable should do what while serializing
virtual zfbool	serializableOnCheck (void)
	see serializable
virtual zfbool	serializableOnSerializeFromData (const ZFSerializableData &serializableData, zfstring *outErrorHint=zft_zfnull, ZFSerializableData *outErrorPos=zft_zfnull)
	for serializable data that has "category" attribute, ZFSerializable would ignore it and leave it to subclass to resolve, see ZFSerializable
virtual zfbool	serializableOnSerializeToData (ZFSerializableData &serializableData, zfstring *outErrorHint=zft_zfnull, ZFSerializable *refOwner=zft_zfnull)
	corresponding to serializableOnSerializeFromData, return whether the task is success, see ZFSerializable
virtual zfbool	serializableOnSerializePropertyFromData (const ZFSerializableData &propertyData, const ZFProperty *property, zfstring *outErrorHint=zft_zfnull, ZFSerializableData *outErrorPos=zft_zfnull)
	see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable
virtual zfbool	serializableOnSerializePropertyToData (ZFSerializableData &ownerData, const ZFProperty *property, zfstring *outErrorHint=zft_zfnull, ZFSerializable *refOwner=zft_zfnull)
	see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable
virtual zfbool	serializableOnSerializeEmbededPropertyFromData (const ZFSerializableData &propertyData, const ZFProperty *property, zfstring *outErrorHint=zft_zfnull, ZFSerializableData *outErrorPos=zft_zfnull)
	see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable
virtual zfbool	serializableOnSerializeEmbededPropertyToData (ZFSerializableData &ownerData, const ZFProperty *property, ZFSerializable *refOwner, zfstring *outErrorHint=zft_zfnull)
	see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable
virtual zfbool	serializableOnSerializeFromString (const zfchar *src, zfindex srcLen=((zfindex) -1), zfstring *errorHint=zft_zfnull)
	see serializeFromString
virtual zfbool	serializableOnSerializeToString (zfstring &ret, zfstring *errorHint=zft_zfnull)
	see serializeFromString

Detailed Description

base class of call serializable object

a serializable object can be encoded to and decoded from a string data, use ZFSerializableData to store necessary data
a ZFSerializableData can hold these datas:

• serializable class: ZFObject's class name or other non-ZFObject's type name, such as "zfstring" and "zfint"
• property name: used only when the serializable belongs to another serializable, it's the property name, and is ensured stored in attributes with "prop" as the attribute name
• property value: used only when the serializable can be converted directly to a type, and is ensured stored in attributes with "value" as the attribute name
• category: used to mark the node should be resolved specially, and is ensured stored in attributes with "category" as the attribute name
• attributes: used to hold extra type datas for the owner
• elements: used to hold properties of the serializable, it's a ZFSerializableData too

ZFSerializableData can be converted from and to xml elements, to make it easier to understand, here's a typical serializable data in xml format that shows the types:

// assume we have a object hold a ZFArray as retain property:
zfclass TestClass : zfextend ZFSerializable {
    ZFOBJECT_DECLARE(TestClass, ZFSerializable)
    ZFPROPERTY_RETAIN(zfanyT<ZFArray>, testProperty)
    ...
};
 
// we have a ZFSerializableData like:
<TestClass test="test">
    <ZFArray prop="testProperty">
        <v_zfstring value="string content" />
    </ZFArray>
    <SomeType category="CategoryName" />
</TestClass>

in this example:

• the "TestClass" in "<TestClass>" is a serializable class
• the "testProperty" in "<ZFArray prop="testProperty">" is a property name
• the "string content" in "<v_zfstring value="string content" />" is a property value
• the "test="test"" in "<TestClass test="test">" is a attribute
• the "category" in "<SomeType category="CategoryName" />" is a category that should be resolved by subclass during serializableOnSerializeFromData

we have these builtin keywords for serializable data, you should not use them as attribute name:

• "prop": shows the serializable is it's parent's property, and the name is the property's name
• "category": if exist this attribute, ZFSerializable would ignore this node and leave it to subclass to decode

a simplest way to implement ZFSerializable is:

• declare your object, and make it implement ZFSerializable, by default, all ZFProperty would be auto serialized

if your object has extra serialize step to do, you may want to:

• override serializableOnCheck to check serializable depending on current object state
• override one or more of these methods to achieve custom serialize step:
  • serializableOnSerializePropertyFromData / serializableOnSerializePropertyToData
  • serializableOnSerializeEmbededPropertyFromData / serializableOnSerializeEmbededPropertyToData
  • serializableOnSerializeFromData / serializableOnSerializeToData
• take care of refOwner while serialize to data, where you should implement reference logic for your custom serialize step
  see ZFStyleSet for more info
  by default, serializable property and embeded property's reference logic would be done by ZFSerializable automatically, but you should take care of category's reference logic manually

typically you should override serializableOnSerializeFromData and serializableOnSerializeToData to supply custom serialize step

serializable logic can also be used with style logic, see ZFStyleSet for more info

ADVANCED:
serializable would be created by ZFClass::newInstance while serializing from data, you may supply your custom constructor, see ZFSerializableKeyword_serializableNewInstance

Member Function Documentation

serializable()

zfbool ZFSerializable::serializable

(

void

)

true if object is currently serializable, see ZFSerializable

subclass should override serializableOnCheck to check whether serializable
some object may be serializable or not depends on content

Note

you must check super's state first if override

See also

ZFSerializable

serializeFromData()

zfbool ZFSerializable::serializeFromData	(	const ZFSerializableData &	serializableData,
		zfstring *	outErrorHint = zft_zfnull,
		ZFSerializableData *	outErrorPos = zft_zfnull )

serialize from data, see ZFSerializable

note that for performance, this method won't check whether serializable before execute

Note

for convenient for script, you may supply a method named "serializableOnSerializeFromData" / "serializableOnSerializeToData", if you do so, the method would be called to perform serialization after default action
the method's proto type should match serializableOnSerializeFromData, and can be registered by ZFMETHOD_USER_REGISTER_N series or ZFMethodDynamicRegister series
typically, this is useful for script language with ZFDynamic

serializeToData()

zfbool ZFSerializable::serializeToData	(	ZFSerializableData &	serializableData,
		zfstring *	outErrorHint = zft_zfnull,
		ZFSerializable *	refOwner = zft_zfnull )

serialize to data, see ZFSerializable

note that for performance, this method won't check whether serializable before execute

serializeFromString()

zfbool ZFSerializable::serializeFromString	(	const zfchar *	src,
		zfindex	srcLen = ((zfindex) -1),
		zfstring *	errorHint = zft_zfnull )

serialize from string, return false by default

for most case, serializeFromData would supply serialization logic automatically, however, the serialization result may be quite verbose for the data structure, subclass may override serializableOnSerializeFromString to supply custom serialization logic as short data structure

Note

for convenient for script, you may supply a method named "serializableOnSerializeFromString" / "serializableOnSerializeToString", if you do so, the method would be called to perform serialization and replace the default action
the method's proto type should match serializableOnSerializeToData, and can be registered by ZFMETHOD_USER_REGISTER_N series or ZFMethodDynamicRegister series
typically, this is useful for script language with ZFDynamic

serializableOnCheckPropertyType()

virtual ZFSerializablePropertyType ZFSerializable::serializableOnCheckPropertyType ( const ZFProperty * property )

protectedvirtual

check the property type that serializable should do what while serializing

properties declared in ZFSerializable have these types:

• not serializable:
  • the property is not serializable and should be manually serialized if necessary
• normal serializable property:
  • the property would be serialized automatically during serializableOnSerializePropertyFromData and serializableOnSerializePropertyToData
  • while serializing from data, ZFSerializable will serialize a property's new instance and then set to the property
  • by default, a property is treated as normal serializable property if:
    • the property's setter and getter is not private
    • the property is retain property and its type is ZFSerializable
    • the property is assign property and its type is registered by ZFTYPEID_DECLARE
• embeded serializable property:
  
  • the property would be serialized automatically during serializableOnSerializeEmbededPropertyFromData and serializableOnSerializeEmbededPropertyToData
  • while serializing from data, ZFSerializable will directly serialize the data to property instance (do nothing if property is null)
  • by default, a property is treated as embeded serializable property if:
    • the property is retain property and its type is ZFSerializable
    • the property's setter is private and getter is not private
  • if a property is an embeded property, you must ensure it's not null while serializing, otherwise, serializing would fail

subclass may override this method to make ZFSerializable ignore or force serialize some property, but you must make sure it's logical valid
ignored property (i.e. ZFSerializablePropertyTypeNotSerializable) can be manually serialized during serializableOnSerializeFromData and serializableOnSerializeToData

by default, properties would be treated as not serializable if ZFProperty::isInternal

Reimplemented in ZFUIAutoLayoutParam, ZFUIListView, and ZFUIOnScreenKeyboardAutoFitLayout.

serializableOnCheck()

virtual zfbool ZFSerializable::serializableOnCheck ( void )

inlineprotectedvirtual

see serializable

Reimplemented in ZFContainer, and ZFKeyValueContainer.

serializableOnSerializeFromData()

virtual zfbool ZFSerializable::serializableOnSerializeFromData ( const ZFSerializableData & serializableData, zfstring * outErrorHint = zft_zfnull, ZFSerializableData * outErrorPos = zft_zfnull )

inlineprotectedvirtual

for serializable data that has "category" attribute, ZFSerializable would ignore it and leave it to subclass to resolve, see ZFSerializable

while overriding this method, you should call super first, and then check whether super has resolved the data
if subclass should resolve the category, you should mark data as resolved and return whether resolve success
if not, subclass should leave the data unresoved and return true

Reimplemented in v_ZFCoreArray, ZFAniForFrame, ZFAniGroup, ZFContainer, ZFEnum, ZFKeyValueContainer, ZFRegExp, ZFStyleList, ZFTime, ZFTypeIdWrapper, ZFUIAutoLayout, ZFUIAutoLayoutParam, ZFUICellArray, ZFUIImage, ZFUIListView, and ZFUIView.

serializableOnSerializeToData()

virtual zfbool ZFSerializable::serializableOnSerializeToData ( ZFSerializableData & serializableData, zfstring * outErrorHint = zft_zfnull, ZFSerializable * refOwner = zft_zfnull )

inlineprotectedvirtual

corresponding to serializableOnSerializeFromData, return whether the task is success, see ZFSerializable

Reimplemented in v_ZFCoreArray, ZFAniForFrame, ZFAniGroup, ZFContainer, ZFEnum, ZFKeyValueContainer, ZFRegExp, ZFStyleList, ZFTime, ZFTypeIdWrapper, ZFUIAutoLayoutParam, ZFUICellArray, ZFUIImage, ZFUIListView, and ZFUIView.

serializableOnSerializePropertyFromData()

virtual zfbool ZFSerializable::serializableOnSerializePropertyFromData ( const ZFSerializableData & propertyData, const ZFProperty * property, zfstring * outErrorHint = zft_zfnull, ZFSerializableData * outErrorPos = zft_zfnull )

protectedvirtual

see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable

if subclass override this method, you should check whether it's resolved by parent, and then mark data as resolved and return whether resolve success

zfbool YourType::serializableOnSerializePropertyFromData(...) {
    if(!SuperSerializable::serializableOnSerializePropertyFromData(...)) {
        return zffalse;
    }
    if(propertyData.resolved()) {
        return zftrue;
    }
 
    // mark resolve if you have resolved
    // or don't mark to leave it to subclass
    propertyData.resolveMark();
 
    return zftrue;
}

serializableOnSerializePropertyToData()

virtual zfbool ZFSerializable::serializableOnSerializePropertyToData ( ZFSerializableData & ownerData, const ZFProperty * property, zfstring * outErrorHint = zft_zfnull, ZFSerializable * refOwner = zft_zfnull )

protectedvirtual

see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable

set serializable class to null to show the property is in init value state and have no need to be serialized

serializableOnSerializeEmbededPropertyToData()

virtual zfbool ZFSerializable::serializableOnSerializeEmbededPropertyToData ( ZFSerializableData & ownerData, const ZFProperty * property, ZFSerializable * refOwner, zfstring * outErrorHint = zft_zfnull )

protectedvirtual

see serializableOnCheckPropertyType, usually you have no need to override this method, see ZFSerializable

set serializable class to null to show the property is in init value state and have no need to be serialized

serializableOnSerializeFromString()

virtual zfbool ZFSerializable::serializableOnSerializeFromString ( const zfchar * src, zfindex srcLen = ((zfindex)-1), zfstring * errorHint = zft_zfnull )

inlineprotectedvirtual

see serializeFromString

Reimplemented in ZFRegExp, and ZFTypeIdWrapper.

serializableOnSerializeToString()

virtual zfbool ZFSerializable::serializableOnSerializeToString ( zfstring & ret, zfstring * errorHint = zft_zfnull )

inlineprotectedvirtual

see serializeFromString

Reimplemented in ZFRegExp, and ZFTypeIdWrapper.

---

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

• ZFSerializable.h