Hurricane::Hook Class Reference

Hook description (API) More...

Inheritance diagram for Hurricane::Hook:

Public Member Functions
virtual Component *	getComponent () const =0
Hook *	getNextHook () const
Hook *	getPreviousHook () const
Hook *	getMasterHook () const
Hook *	getNextMasterHook () const
Hook *	getPreviousMasterHook () const
Hooks	getHooks () const
Hooks	getSlaveHooks () const
virtual bool	isMaster () const =0
bool	isAttached () const
Hook *	detach ()
Hook *	attach (Hook *hook)
Hook *	merge (Hook *hook)

Detailed Description

Hook description (API)

Introduction

The hook is an object which is nested inside a component and which represents some specific part of this component (like its body, its origin or its extremity ...).

The Hook class is an abstract one, that means that for any new type of part a new hook subclass must be derived. Each hook specialization will be described altogether with the component which includes it.

The Component for instance introduces the concept of BodyHook representing the body of the component (which can be assimilated to the component itself).

Rings

Hooks are assembled into a ring (circular link) thanks to a special field pointing to the next hook within the ring.

This field is never NULL, by default it points to itself, generating a minimal ring.

Master and Slave hook types

There are two kinds of hooks : the masters and the slaves.

Rings are organized such that all slave hooks of a master hook are placed in the ring immediately before it (the ordering of slaves is not significant).

Therefore, to find the master of a given slave, it's enough to follow the ring pointers, starting from the slave, until a master is found.

Explicit connections

This dependency between a slave and its master means that the part of the component represented by the slave is anchored on the part of the component represented by the master.

This dependence relationship is indeed an explicit connection.

Implicit connections

Within a ring many relationships master-slaves can cohabit.

This cohabitation has a specific meaning for the different masters of the ring. In fact, the ring must be considered as a connection request between the different masters of the ring.

In other words, this means that the different masters remains to be connected together, or more generaly stated, that the different connected subsets of components associated to those masters remains to be connected together.

The ordering of masters within a ring has no particular signification.

Concepts of HyperHooks and HyperRings

We can imagine the master-slaves relation as a kind of hyper-hook representing the associated sub-ring, and the ring containing multiple master-slaves relations as an hyper-ring made up of hyper-hooks needing to be connected.

Therefore there will be two different levels of ring processing functions depending on wether we handle hooks stricktly speaking or we handle hyper-hooks representing multiple master hooks.

Constructor and Destructor

There is no Hook constructor available because they are created by the components themselves.

On the same way, hooks disapear automatically with their owner.

Member Function Documentation

getComponent()

Component * Hurricane::Hook::getComponent ( ) const

pure virtual

Returns: the component whose hook represents a part.

Remarks

The result is never NULL because hooks are byforce nested objects in their component.

getNextHook()

Hook * Hurricane::Hook::getNextHook

(

)

const

Returns: the next hook within the ring.

Remarks

The result is never NULL because every hook has by construction its next one (which may be itself is the ring is empty).

getPreviousHook()

Hook * Hurricane::Hook::getPreviousHook

(

)

const

Returns: the previous hook within the ring.

Remarks

Less efficient than getNextHook because it requires a complete ring loop.

getMasterHook()

Hook * Hurricane::Hook::getMasterHook

(

)

const

Returns: the master of the relation master-slaves identified by the hook.

Remarks

May return itself if the hook is a master and return NULL if the hook is a slave and has no associated master.

getNextMasterHook()

Hook * Hurricane::Hook::getNextMasterHook

(

)

const

Returns: the first master found when starting the search immediately after the given hook.

Remarks

May return NULL if there is no master within the ring or return the hook itself if it is a master and the only one in the ring.

getPreviousMasterHook()

Hook * Hurricane::Hook::getPreviousMasterHook

(

)

const

Returns: the first master found when starting a backwards search immediately before the given hook.

Remarks

May return NULL if there is no master within the ring or return the hook itself if it is a master and the only one in the ring.

Of course the search is done in the natural forward direction (else it would be trully inefficient).

getHooks()

Hooks Hurricane::Hook::getHooks

(

)

const

Returns: the collection of hooks of the ring containing the given hook.

Remarks

Hooks are always visited in the natural order starting from the hook itself.

getSlaveHooks()

Hooks Hurricane::Hook::getSlaveHooks

(

)

const

Returns: the hook collection which are slaves of the given hook.

Remarks

This collection will be empty if the given hook is not a master or if it has no attached slaves.

When visiting the slaves of a master, those are accessed in the assembly order : the first one is the oldest inserted (they are accessed starting from the first slave found when starting a ring loop from the master itself).

The master is not included in this collection.

isMaster()

bool Hurricane::Hook::isMaster ( ) const

pure virtual

Returns: true if the hook must be considered as a master, else false.

Remarks

For any new kind of hook this predicate must be overloaded.

isAttached()

bool Hurricane::Hook::isAttached

(

)

const

If the hook is a slave :

Returns: true if the hook has an associated master, else false.

Remarks

You can't find two slaves in the same ring without at least a master.

If the hook is a master :

Let us consider the hyper-ring made upon hyper-hooks. Then the function returns true if the ring contains at least an other master else false.

Caution: The meaning here is very different than for a slave hook!

detach()

Hook * Hurricane::Hook::detach

(

)

If the hook is a slave :

detaches the hook from its ring and returns its old predecessor.

Remarks

Will return NULL if the hook is the only one in the ring.

If the hook is a master :

Let us consider the hyper-ring made upon hyper-hooks. Then, the function detaches the hyper-hook (the sub-ring made up of the master and its slaves, if any) from the hyper-ring and returns the old predecessor of the hyper-hook.

Within the detached hyper-hook, the relationship master hook

• slave hooks remains unaltered and forms a new ring.

Remarks

May return NULL if the hook is the only master of the ring.

The returned hook, if not NULL, is byforce a master.

attach()

Hook * Hurricane::Hook::attach

(

Hook *

masterHook

)

If the hook (this) is a slave :

The function inserts the hook immediately before <masterHook> and returns this masterHook.

Caution: Might throw an exception if the hook already has a master or

if <masterHook> is not a master hook.

If the hook (this) is a master :

Let us consider the hyper-ring made upon hyper-hooks. Then, the function attaches the the hyper-hook (the sub-ring made up of this master hook and its slaves, if any) before the <masterHook> and returns this masterHook.

Caution: Might throw an exception if the hyper-hook is already

attached within a ring including an other master or if <masterHook> is not a master hook.

merge()

Hook * Hurricane::Hook::merge

(

Hook *

masterHook

)

merges the rings represented by the two hooks which both must be masters, returns <masterHook>.

Remarks

Throws an exception if both hooks are not masters.

This function doesn't change the two relatioships master-slaves but modifies the connection request between corresponding hyper-hooks.

---

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

• Hook.h
• Hook.dox