
 // -*- C++ -*-


 namespace Hurricane {

 /*! \class        Quark
  *  \brief        Quark description (\b API)
  *
  *  \section      secQuarkIntro  Introduction
  *
  *                As explained in the Occurence class, occurences are very 
  *                simple objects used to designate any entity of the virtually 
  *                unfolded hierarchy. However, those occurences, which are 
  *                built and deleted very easily, are very volatile objects to 
  *                which we can't, of course, attach properties directly. 
  *
  *                But the usefullness of occurences lies in their ability to 
  *                attach them properties. 
  *
  *                In order to do that, properties must be stored in a secure 
  *                place, where they can be found when needed. That is the 
  *                purpose of quarks : they are data base objects and then can 
  *                own the properties of the occurences. 
  * 
  * 
  *  \section      secQuarkImportant  Important
  *
  *                A quark designates all occurences refering to the same entity 
  *                of the virtually unfolded hierarchy. 
  *
  *                This means that a property put on an occurence can be 
  *                recovered by an other occurence refering the same entity of 
  *                the virtually unfolded hierarchy. 
  * 
  * 
  *  \section      secQuarkConstructionAndDestruction  Construction and destruction
  *
  *                Quarks being completely managed by the system, there is no 
  *                constructor provided. 
  *
  *                They are themselves volatile because they need to exist only 
  *                if there is at least a property attached to them (you must 
  *                never store pointers to them !). 
  *
  *                An occurence may have, during its life, different quarks 
  *                representing it. 
  *
  *                Nevertheless, it is possible to destroy a quark. This one 
  *                will carry away with it the destruction of all its owned 
  *                properties (like any other data base object). This is 
  *                equivalent to destroying the properties associated to the 
  *                occurences whom it is the unique representative. 
  *                Conceptually, it is wiser to use the call : 
  *                <b>occurence.ClearProperties()</b> which does the same. 
  * 
  * 
  *  \section      secQuarkExample  Example
  *
  *                The following sample code shows how to print the set of 
  *                owners of a shared property : 
\code
Property* property = ...; // we get a property
 
if (is_a<SharedPropery*>(property)) {
   for_each_dbo(dbo, ((SharedProperty*)property)getOwners()) {
      if (!is_a<Quark*>(dbo))
         cerr << dbo << endl;
      else
         cerr << ((Quark*)dbo)getOccurence() << endl;
      end_for;
   }
}
\endcode
  */



 /*! \name         Accessors
  */
 //  \{

 /*! \function     const Occurrence& Quark::getOccurrence() const;
  *  \Return       an occurence of which this quark is a representative. 
  */

 //  \}



 }
