Hurricane::Property Class Reference

Property description (API) More...

Inheritance diagram for Hurricane::Property:

Public Member Functions
virtual Name	getName () const =0
virtual void	onCapturedBy (DBo *owner)=0
virtual void	onReleasedBy (DBo *owner)=0
Property Collection
virtual void	destroy ()

Detailed Description

Property description (API)

Introduction

Properties can be attached to the data base objects. Those properties must have a name in order to access them unambiguously. Of course only one property of a given name can be attached to an object.

In a first step we define two great categories of properties : the private properties which can be attached to only one object and the shared properties which can be attached to a large number of objects.

We will detail separately their respective behaviour, but we ensure that the management of each of those two property categories is absolutely secure. That is, on one side you can destroy explicitely a property (and the objects will be notified) and on the other side the properties will be automatically destroyed when no more object reference them.

Remarks

By overloading some messages, as we will see later, it is possible to set up different behaviours (like avoid the automatic delete).

The Quarks

As we shall see, the occurences are very simple objects which are used to designate some entity of the virtually unfolded hierarchy. Indeed, those occurences, which are built and deleted very quickly, are very volatile objects to which obvioulsy we can't attach properties directly.

But the interest of occurences is precisely to be able to attach them properties. In order to be able to do that, properties must be stored in a secure place where we could find them when needed. The quarks are here for that purpose : they are subtypes of data base object and therefore can store the properties attached to occurences.

Important:\n only one quark is attached to all occurences which refer the

same entity of the virtually unfolded hierarchy. This means that a property placed on an occurence can be read by any other occurence which refers the same entity of the virtually unfolded hierarchy.

Remarks

Those quarks are also volatile objects because their only reason to exist is that at least one property is attached to them.

How that works

We will detail the way properties are managed by analysing more precisely what happens at the level of property access functions both for data base objects and for occurences.

Accessing a property by its name

Property* DBo::getProperty(const Name& name) const;

This member function returns the property of name <name> if there is one attached to the object, else NULL.

Property* Occurrence::getProperty(const Name& name) const;

This function searches in a first time the quark representing the occurence.

If the quark doesn't exist, this means there is no property attached to that occurence, then the function returns NULL.

If the quark does exist, the function returns the property of name <name> attached to the quark, if any, by calling the previous function (because quarks are data base objects).

Accessing the set of all properties

Properties  DBo::getProperties() const;

Return the collection of properties attached to the object (possibly empty).

Properties  Occurrence::getProperties() const;

This function searches in a first time the quark representing the occurence.

If the quark doesn't exist, this means there is no property attached to that occurence, then the function returns an empty property collection.

If the quark does exist, the function returns the property collection attached to the quark, by calling the previous function (the returned collection is inevitably non empty, else the quark would not exist).

Does the object have properties ?

bool DBo::hasProperty() const;

Return true if the object owns at least a property, else false.

bool Occurrence::hasProperty() const;

This function searches the quark representing the occurence.

If the quark does exist it means there is at least a property assigned to it and the function returns true, else it returns false.

Adding a property : things becomes a little harder

void DBo::put(Property* property);

Adds the property <property> to the set of properties of the object.

void Occurrence::put(Property* property);

This function searches the quark representing the occurence.

If the quark doesn't exist it is automatically created in order to attach this first property.

once the quark has been got or created, we can add the property with the previous function.

Two important things might happen then : The property is already owned by an other object (may be a quark) and that property is not a shared one and/or the object owns already a property with the same name.

Therefore it may happen, within this step, that adding a property to an object leads to the deletion of an other property on that object (name unicity) or on an other object (unicity of owner for a private property).

Which behaviour should we have in such conditions ? Shall we destroy the property which has been detached ? There is no unique behaviour which matches all needs. In order to solve this problem the properties must answer to two specific messages which are : onCapturedBy(DBo* dbo) when the property is attached to an object and onReleasedBy(DBo* dbo) when it is detached from the object. It is within that last message that the decision about the future of the property must be taken.

Remarks

We will detail below those messages for both private and shared properties.

Removing a property

void DBo::remove(Property* property);

Removes the property <property> from the set of properties of the object.

void Occurrence::remove(Property* property);

The function searches for the quark associated to the occurence.

If the quark doesn't exist, there is nothing to do, the occurence has no properties.

Else the property is removed from the set of quark properties by calling the previous function. Furthermore if this removed property is the last one, the quark is automatically deleted.

Important:\n The message onReleasedBy is called upon as explained

above. This call will decide of the future of the removed property.

Clearing all properties

void DBo::clearProperties();

Removes all properties attached to the object.

void Occurrence::clearProperties();

First searches for the quark associated to the occurence.

If the quark exist it is simply destroyed after removing all its private properties and detaching it from all its shared properties (wich may lead to their removal). Without quark the occurence looses all its properties.

Important:\n Here again the message onReleasedBy is called upon for

each removed property.

Creation process

The creation process is similar to the data base objects creation one. Therefore a property must be created by the special function Create and not by the usual new (which is not available).

Deletion process

Hurricane::Property::destroy

Naming Conventions

Properties being named and the their management being based on that name, it could occur conflicts between Hurricane which use some properties and the different tools which will be plugged above, or between different tools themselves.

In order to avoid that you must take some precautions in the choice of the property names.

So Hurricane uses properties prefixed by the string "Hurricane::",like for instance "Hurricane::Selector" for the property of type Selector.

So I suggest that different tools use a similar namming strategy which would keep confident all the community of hurricaners

Remarks

Using names like "ZenTek::TimingNode" for the TimingNode type property managed by tools from the ZenTek society decreases name conflicts, unless with other tools from the same society. A property name "SocietyName::ToolName::PropertyName" would be more secure.

Furthermore, if the community adopts this convention it will be possible to simplify some parts of the code by avoiding for example calls to the macro is_a to check that the collected property is of the expected type, as shown in the following example :

Property* property = occurence.getProperty("Hurricane::Selector");
 
if (property && is_a<Selector*>(property)) {
  Selector* selector = (Selector*)property;
  // ...
}

Which could become :

Selector* selector = (Selector*)occurence.getProperty("Hurricane::Selector");
 
if (selector) {
  // ...
}

Remarks

The name of properties being of type Name and not of type string, the comparison between two names operates on their pointers and not on their character strings. The length of the name doesn't affect the comparison performance.

on the other hand, the time to create a property name depends obviously of its length and of the number of names (which fortunately are managed by efficient map containers).

Therefore in order to avoid building names at each property access, you must provide a specific function which returns a Name object allocated once and once only.

As a matter of fact if you write, like in the previous example :

Property* property = occurence.getProperty("Hurricane::Selector");

Each time the name is built and this will degrade performance.

on the other hand if the following static member function is provided :

const Name& Selector::getPropertyName ()
{
  static Name NAME = "Hurricane::Selector";
  return NAME;
}

You could write later :

Property* property = occurence.getProperty(Selector::getPropertyName());

This approach is much more efficient and presents an other interest : you don't need to know the name of the property being handled. This allows to change property names without affecting existing code.

Therefore I propose, for every new instanciable property (whose name depends of the property type), that a static member function be systematically provided.

Furthermore, both StandardPrivateProperty and StandardSharedProperty have, as we shall see later, an attribute giving their name. Here again, for accessing the propety, a name must be created.

So I propose also that a global function (which can't be a static member function) be defined for each new property name.

That way, by defining (i.e. for the property ObjectId) the function :

const Name& getObjectIdPropertyName ()
{
  static Name NAME = "Hurricane::ObjectId";
  return NAME;
}

You can write later :

Property* property = occurence.getProperty(getObjectIdPropertyName());

Member Function Documentation

destroy()

void Hurricane::Property::destroy ( )

virtual

Like the data base objects, properties can be destroyed by calling upon this function and not the standard C++ destructor (which is not available).

getName()

Name Hurricane::Property::getName ( ) const

pure virtual

Returns: the name of the property : this method must absolutely be overloaded for all new property classes, because the property name is not a "wired in" attribute. A property being a real object, this name derives naturally from the property type name (so don't loose room uselessly to store it in a record slot).

onCapturedBy()

void Hurricane::Property::onCapturedBy ( DBo *  dbo )

pure virtual

This message is called upon when the property is added to the properties of <dbo>.

By default this function does nothing particular, but it must be overloaded for all property sub-classes. We will detail later the reaction to this message as taken by the private and shared property classes.

Remarks

This message being already overloaded for private and shared property classes there is no need to overload it again when specializing any of those two classes.

onReleasedBy()

void Hurricane::Property::onReleasedBy ( DBo *  dbo )

pure virtual

This message is called upon when the property is removed from the <dbo> properties.

Important:\n The argument <dbo> is not (or no more) necessarily the

owner of the property which receives the message. The processing to be done in reaction to this message often depends on this observation. We will better understand this subtlety when studying private properties.

Remarks

This message being already overloaded for private and shared property classes there is no need to overload it again when specializing any of those two classes.

---

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

• Property.h
• Property.dox