Falcon::CoreObject Class Reference

Base core object class. More...

#include <coreobject.h>

Inheritance diagram for Falcon::CoreObject:

List of all members.

Public Member Functions

bool apply (const ItemDict &dict, bool bRaiseOnError=false)

Apply the given values to this object.

virtual CoreObject * clone () const =0

Creates a shallow copy of this item.

bool derivedFrom (const String &className) const

Returns true if this object has the given class among its ancestors.

virtual bool deserialize (Stream *stream, bool bLive)

Deserializes the object from a stream.

virtual void gcMark (uint32 mark)

Performs GC marking of the inner object data.

const CoreClass * generator () const

Get the class that generated this object.

FalconData * getFalconData () const

Returns a valid sequence instance if this object's user data is a "Falcon Data".

bool getMethod (const String &propName, Item &method) const

Returns a method from an object.

virtual bool getProperty (const String &prop, Item &value) const =0

Returns the a shallow item copy of required property.

Sequence * getSequence () const

Returns a valid sequence instance if this object's user data is a "Falcon Sequence".

void * getUserData () const

Return the inner user data that is attached to this item.

virtual bool hasProperty (const String &prop) const

Returns true if the class provides a certain property.

virtual void readIndex (const Item &pos, Item &target)

Override deep item accessor.

virtual void readProperty (const String &pos, Item &target)

Override deep item accessor.

bool retrieve (ItemDict &dict, bool bRaiseOnError=false, bool bFillDict=false, bool bIgnoreMethods=true) const

Retrieves values of properties in this object.

virtual bool serialize (Stream *stream, bool bLive) const

Serializes this instance on a stream.

bool setProperty (const String &prop, const String &value)

Stores an arbitrary string in a property.

virtual bool setProperty (const String &prop, const Item &value)=0

Sets a property in the object.

void setUserData (Sequence *sdata)

Set a Sequence as the user data for this object.

void setUserData (FalconData *fdata)

Set a FalconData as the user data for this object.

void setUserData (void *data)

Set a generic user data for this object.

virtual void writeIndex (const Item &pos, const Item &target)

Override deep item accessor.

virtual void writeProperty (const String &pos, const Item &target)

Override deep item accessor.

virtual ~CoreObject ()

The base destructor does nothing.

Protected Member Functions

CoreObject (const CoreObject &other)

CoreObject (const CoreClass *parent)

bool defaultProperty (const String &key, Item &prop) const

Creates the default value for this property.

bool getMethodDefault (const String &name, Item &mth) const

Return a default method among those recorded in the generator class.

void readOnlyError (const String &key) const

Generates a property access error.

Protected Attributes

bool m_bIsFalconData

bool m_bIsSequence

const CoreClass * m_generatedBy

void * m_user_data

Detailed Description

Base core object class.

To create your own objects, derive from this class and reimplement:

   virtual bool hasProperty( const String &key ) const;
   virtual bool setProperty( const String &prop, const Item &value );
   virtual bool getProperty( const String &key, Item &ret ) const;
   virtual CoreObject *clone() const;

Eventually, reimplement also:

   virtual bool serialize( Stream *stream, bool bLive ) const;
   virtual bool deserialize( Stream *stream, bool bLive );

Those default methods in this class will save the object on the stream on live serialization (i.e. inter-vm serializations), but will just fail on normal serializations.

Then, create a factory function returning an object of your class when creating an instance, like the following:

   // typedef ObjectFactory ...
   CoreObject* MyClassFactory( const CoreClass *cls, void *data, bool bDeserializing );

Remember that inner program-specific data may be provided later via setUserData() method, so the factory function must take into accunt the fact that data may not be provided (may be 0).

The bDeserializing parameter will be true when creating an instance after a serialized data. As deserialize() is going to be called next, the constructor may take this parameter to avoid performing full construction and let deserialize() to setup the object.

Then, in the module owning this object, the class that shall return an instance of this must be configured via ClassDef::factory( ObjectFactory ) method. In example:

   Symbol *my_class = self->addClass( "MyClass", my_class_init );
   my_class->getClassDef()->factory( &MyClassFactory );

Three standard subclasses with their respective factories are provided.

FalconObject is the standard CoreObject containing falcon Item instances in each property and possibly a FalconData entity.
ReflectObject is totally opaque, and all its get/set properties are sent to the class reflection table. The class reflection table indicates which action must be taken when setting or getting a property, and can both store C native data in the underlying user_data, or call functions to perform this task.
CRObject: Is a reflective object that has a back-up Item for each property. If a prioperty is not declared reflective in the class reflection table, it is treated as if in a FalconObject, otherwise its value is generated through the reflection mechanism and cached in the property item.

Those three class factories are automatically applied by the VM in case it has not been set. If the class has all the properties fully reflected (or reflected on read and read only) ReflectObject factory will be used; if one or more properties are not reflected CRObject factory will be used; if none is reflected, FalconObject factory is used.

Note:: Actually, there are three factories for each one of the basic classes, depending on which kind of user data is expected to be associated with the created instance, if any. The VM uses the factory functions that suppose that the data stored in the instance will be an instance of FalconData class, as this is the most common case and the only data stored in objects by the engine.

Constructor & Destructor Documentation

Falcon::CoreObject::CoreObject ( const CoreClass * parent ) [protected]

Falcon::CoreObject::CoreObject ( const CoreObject & other ) [protected]

virtual Falcon::CoreObject::~CoreObject ( ) [virtual]

The base destructor does nothing.

Use finalize() hook to dispose of internal, reflected data.

Member Function Documentation

bool Falcon::CoreObject::apply	(	const ItemDict &	dict,
		bool	bRaiseOnError = `false`
	)

Apply the given values to this object.

This function applies the values in dict inside this object, applying repeatedly them via setProperty.

This function skips writeProperty and calls directly to the virtual setProperty method. This means that VM overrides are uncalled.

If bRaiseOnError is set to true, a failed setProperty will cause the function to raise an AccessError. Otherwise, the function will ignore the error and proceed, but it will return false when completed.

Parameters:

	dict	The property => value dictionary to be applied.
	bRaiseOnError	if true, raise when a property in dict is not found here.

Returns:: true on success, false if some property was not found and bRaiseOnError is false.

virtual CoreObject* Falcon::CoreObject::clone ( ) const [pure virtual]

Creates a shallow copy of this item.

Will return zero if this item has a non-cloneable user-defined data, that is, it's not fully manageable by the language.

Clone operation requests the class ObjectManager to clone the user_data stored in this object, if any. In turn, the ObjectManager may ask the user_data, properly cast, to clone itself. If one of this operation fails or is not possible, then the method returns 0. The VM will eventually raise a CloneError to signal that the operation tried to clone a non manageable user-data object.

If this object has not a user_data, then the cloneing will automatically succeed.

Returns:: a shallow copy of this item.

Implemented in Falcon::CoreCarrier< _T >, Falcon::CoreSlotCarrier, Falcon::CRObject, Falcon::core::ErrorObject, Falcon::FalconObject, and Falcon::ReflectObject.

bool Falcon::CoreObject::defaultProperty	(	const String &	key,
		Item &	prop
	)			const `[protected]`

Creates the default value for this property.

Simple reflection can be done by overloading CoreObject and handling reflected properties in a string if/else cascade or in a switch based on property searches in the class property table.

This utility function can be used as a default way to return basic values (and eventually methods) from the property table if they doesn't need special management.

Example:

      bool MyClass::getProperty( const String &key, Item &ret ) const
      {
         if ( key == "prop1" )
         {
            //...
         }
         else if ( key == "prop2" )
         {
            //...
         }
         else {
            return defaultProperty( key, ret );
         }

         return true; // we found it or we would have called defalutProperty.
      }

Referenced by Falcon::CoreCarrier< _T >::getProperty().

bool Falcon::CoreObject::derivedFrom ( const String & className ) const

Returns true if this object has the given class among its ancestors.

virtual bool Falcon::CoreObject::deserialize	(	Stream *	stream,
		bool	bLive
	)			`[virtual]`

Deserializes the object from a stream.

The object should be created shortly before this call, giving instruction to the constructor not to perform a full initialization, as the content of the object will be soon overwritten.

Will throw in case of error.

Exceptions:

IOError

in case of stream error.

Parameters:

	stream	The stream from which to read the object.
	bLive	If true,

Returns:: External call indicator. In case it returns true, the caller should

Reimplemented in Falcon::CacheObject.

virtual void Falcon::CoreObject::gcMark ( uint32 mark ) [virtual]

Performs GC marking of the inner object data.

This marks properties and eventually inner data, if it's a FalconData* subclass instance.

Reimplemented from Falcon::Garbageable.

Reimplemented in Falcon::CacheObject, and Falcon::core::ErrorObject.

const CoreClass* Falcon::CoreObject::generator ( ) const [inline]

Get the class that generated this object.

This is the phisical core object instance that generated this object. The symbol in the returned class is the value returend by instanceOf().

Returns:: the CoreClass that were used to generate this object.

Referenced by Falcon::CoreCarrier< _T >::hasProperty().

FalconData* Falcon::CoreObject::getFalconData ( ) const [inline]

Returns a valid sequence instance if this object's user data is a "Falcon Data".

Sequences can be used in sequential operations as the for-in loops, or in functional sequence operations (as map, filter and so on).

Objects containing a Falcon Sequence as user data can declare this changing this function and returning the sequence data.

bool Falcon::CoreObject::getMethod	(	const String &	propName,
		Item &	method
	)			const `[inline]`

Returns a method from an object.

This function searches for the required property; if it's found, and if it's a callable function, the object fills the returned item with a "method" that may be directly called by the VM.

Note:: Actually this function calls methodize() on the retreived item. The value of the method parameter may change even if this call is unsuccesfull.

Parameters:

	key	the name of the potential method
	method	an item where the method will be stored

Returns:: true if the property exists and is a callable item.

References Falcon::Item::methodize().

bool Falcon::CoreObject::getMethodDefault	(	const String &	name,
		Item &	mth
	)			const `[protected]`

Return a default method among those recorded in the generator class.

Takes the property table of the generator class and, if it's a function, methodizes it.

Note:: This method is protected, and meant to extend objects by replacing directly the getProperty() method; external users should rely on getMethod().

Parameters:

	name	The name of the method to be searched.
	mth	The item that will be filled with a full ready method instance on success.

Returns:: true if the property exists and can be methodized.

virtual bool Falcon::CoreObject::getProperty	(	const String &	prop,
		Item &	value
	)			const `[pure virtual]`

Returns the a shallow item copy of required property.

The copy is shallow; strings, arrays and complex data inside the original property are shared.

Parameters:

	prop	the property to be found
	value	an item containing the object proerty copy.

Returns:: true if the property can be found, false otherwise

Implemented in Falcon::CacheObject, Falcon::CoreCarrier< _T >, Falcon::CRObject, and Falcon::ReflectObject.

Sequence* Falcon::CoreObject::getSequence ( ) const [inline]

Returns a valid sequence instance if this object's user data is a "Falcon Sequence".

Sequences can be used in sequential operations as the for-in loops, or in functional sequence operations (as map, filter and so on).

Objects containing a Falcon Sequence as user data can declare this changing this function and returning the sequence data.

void* Falcon::CoreObject::getUserData ( ) const [inline]

Return the inner user data that is attached to this item.

Referenced by Falcon::core::ErrorObject::getError().

virtual bool Falcon::CoreObject::hasProperty ( const String & prop ) const [virtual]

Returns true if the class provides a certain property.

Should not account Object metaclass properties, unless explicitly overloaded.

Parameters:

prop

The property to be searched.

Returns:: true if the generator class provides this property.

Reimplemented in Falcon::CoreCarrier< _T >.

virtual void Falcon::CoreObject::readIndex	(	const Item &	pos,
		Item &	target
	)			`[virtual]`

Override deep item accessor.

By default, it searches a method named "getIndex__" and passes the target item to it; it raises if the method is not found.

Implements Falcon::DeepItem.

void Falcon::CoreObject::readOnlyError ( const String & key ) const [protected]

Generates a property access error.

If the property is in the class property table, a "read only" property error is raised, otherwise a "property not found" error is raised instead.

Useful as a default terminator of simple subclass setProperty() overloads.

virtual void Falcon::CoreObject::readProperty	(	const String &	pos,
		Item &	target
	)			`[virtual]`

Override deep item accessor.

Resolves into getProperty().

Implements Falcon::DeepItem.

bool Falcon::CoreObject::retrieve	(	ItemDict &	dict,
		bool	bRaiseOnError = `false`,
		bool	bFillDict = `false`,
		bool	bIgnoreMethods = `true`
	)			const

Retrieves values of properties in this object.

This method calls iteratively getProperty to fill the properties that corespond to the keys in dict.

If bFillDict is true, the object is scanned and its properties are set in the dictionary instead.

If bIgnoreMethods is true, method proeprties are skipped when bFillDict is true.

If bRaiseOnError is true the function throws an AccessError when getProperty fails; this setting is ignored when bFillDict is true.

Parameters:

	dict	The dictionary to be filled.
	bRaiseOnError	If true, throw an AccessError when dict contains a key that doesn't match any property.
	bFillDict	If true, ignore the contents of dict, and fill it with the actual properties instead.
	bIgnoreMethods	When true, copy only data properties.

Returns:: True on success, false if bRaiseOnError is false and some keys in dict can't be found as properties of this object.

virtual bool Falcon::CoreObject::serialize	(	Stream *	stream,
		bool	bLive
	)			const `[virtual]`

Serializes this instance on a stream.

Exceptions:

IOError

in case of stream error.

Reimplemented in Falcon::CacheObject.

bool Falcon::CoreObject::setProperty	(	const String &	prop,
		const String &	value
	)

Stores an arbitrary string in a property.

The string is copied in a garbageable string created by the object itself.

virtual bool Falcon::CoreObject::setProperty	(	const String &	prop,
		const Item &	value
	)			`[pure virtual]`

Sets a property in the object.

If the property is found, the value in the item is copied, otherwise the object is untouched and false is returned.

In case of reflected objects, it may be impossible to set the property. In that case, the owning vm gets an error, and false is returned.

Parameters:

	prop	The property to be set.
	value	The item to be set in the property.

Returns:: ture if the property can be set, false otherwise.

Implemented in Falcon::CacheObject, Falcon::CoreCarrier< _T >, Falcon::CRObject, and Falcon::ReflectObject.

void Falcon::CoreObject::setUserData ( Sequence * sdata ) [inline]

Set a Sequence as the user data for this object.

Sequence class is derived from FalconData, and it adds an interface for serial access to items.

void Falcon::CoreObject::setUserData ( FalconData * fdata ) [inline]

Set a FalconData as the user data for this object.

FalconData class present a minimal interface that cooperates with this class:

It has a virtual destructor, that is called when the wrapping CoreObject instance is destroyed.
It provides a clone() method that is called when the wrapping CoreObject is cloned.
It provides a gcMark() method, called when this Object is marked.
Serialization support is available but defaulted to fail.

void Falcon::CoreObject::setUserData ( void * data ) [inline]

Set a generic user data for this object.

This user data is completely un-handled by this class; it's handling is completely demanded to user-defined sub-classes and/or to property-level reflection system.

Referenced by Falcon::CoreCarrier< _T >::CoreCarrier().

virtual void Falcon::CoreObject::writeIndex	(	const Item &	pos,
		const Item &	target
	)			`[virtual]`

Override deep item accessor.

By default, it searches a method named "setIndex__" and passes the target item to it; it raises if the method is not found.

Implements Falcon::DeepItem.

virtual void Falcon::CoreObject::writeProperty	(	const String &	pos,
		const Item &	target
	)			`[virtual]`

Override deep item accessor.

Resolves into setProperty().

Implements Falcon::DeepItem.

Member Data Documentation

bool Falcon::CoreObject::m_bIsFalconData [protected]

bool Falcon::CoreObject::m_bIsSequence [protected]

const CoreClass* Falcon::CoreObject::m_generatedBy [protected]

void* Falcon::CoreObject::m_user_data [protected]

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

/home/gian/Progetti/falcon/core/include/falcon/coreobject.h


Public Member Functions
bool	apply (const ItemDict &dict, bool bRaiseOnError=false)
	Apply the given values to this object.
virtual CoreObject *	clone () const =0
	Creates a shallow copy of this item.
bool	derivedFrom (const String &className) const
	Returns true if this object has the given class among its ancestors.
virtual bool	deserialize (Stream *stream, bool bLive)
	Deserializes the object from a stream.
virtual void	gcMark (uint32 mark)
	Performs GC marking of the inner object data.
const CoreClass *	generator () const
	Get the class that generated this object.
FalconData *	getFalconData () const
	Returns a valid sequence instance if this object's user data is a "Falcon Data".
bool	getMethod (const String &propName, Item &method) const
	Returns a method from an object.
virtual bool	getProperty (const String &prop, Item &value) const =0
	Returns the a shallow item copy of required property.
Sequence *	getSequence () const
	Returns a valid sequence instance if this object's user data is a "Falcon Sequence".
void *	getUserData () const
	Return the inner user data that is attached to this item.
virtual bool	hasProperty (const String &prop) const
	Returns true if the class provides a certain property.
virtual void	readIndex (const Item &pos, Item &target)
	Override deep item accessor.
virtual void	readProperty (const String &pos, Item &target)
	Override deep item accessor.
bool	retrieve (ItemDict &dict, bool bRaiseOnError=false, bool bFillDict=false, bool bIgnoreMethods=true) const
	Retrieves values of properties in this object.
virtual bool	serialize (Stream *stream, bool bLive) const
	Serializes this instance on a stream.
bool	setProperty (const String &prop, const String &value)
	Stores an arbitrary string in a property.
virtual bool	setProperty (const String &prop, const Item &value)=0
	Sets a property in the object.
void	setUserData (Sequence *sdata)
	Set a Sequence as the user data for this object.
void	setUserData (FalconData *fdata)
	Set a FalconData as the user data for this object.
void	setUserData (void *data)
	Set a generic user data for this object.
virtual void	writeIndex (const Item &pos, const Item &target)
	Override deep item accessor.
virtual void	writeProperty (const String &pos, const Item &target)
	Override deep item accessor.
virtual	~CoreObject ()
	The base destructor does nothing.
Protected Member Functions
	CoreObject (const CoreObject &other)
	CoreObject (const CoreClass *parent)
bool	defaultProperty (const String &key, Item &prop) const
	Creates the default value for this property.
bool	getMethodDefault (const String &name, Item &mth) const
	Return a default method among those recorded in the generator class.
void	readOnlyError (const String &key) const
	Generates a property access error.
Protected Attributes
bool	m_bIsFalconData
bool	m_bIsSequence
const CoreClass *	m_generatedBy
void *	m_user_data