src/TDF/TDF_Label.hxx

   1 // Created on: 1997-02-04
   2 // Created by: DAUTRY Philippe
   3 // Copyright (c) 1997-1999 Matra Datavision
   4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 //
   6 // This file is part of Open CASCADE Technology software library.
   7 //
   8 // This library is free software; you can redistribute it and/or modify it under
   9 // the terms of the GNU Lesser General Public License version 2.1 as published
  10 // by the Free Software Foundation, with special exception defined in the file
  11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 // distribution for complete text of the license and disclaimer of any warranty.
  13 //
  14 // Alternatively, this file may be used under the terms of Open CASCADE
  15 // commercial license or contractual agreement.
  16
  17 #ifndef _TDF_Label_HeaderFile
  18 #define _TDF_Label_HeaderFile
  19
  20 #include <Standard.hxx>
  21 #include <Standard_DefineAlloc.hxx>
  22 #include <Standard_Handle.hxx>
  23
  24 #include <TDF_LabelNodePtr.hxx>
  25 #include <Standard_Integer.hxx>
  26 #include <Standard_Boolean.hxx>
  27 #include <Standard_OStream.hxx>
  28 #include <TDF_AttributeIndexedMap.hxx>
  29 class Standard_DomainError;
  30 class Standard_OutOfRange;
  31 class Standard_NullObject;
  32 class TDF_ChildIterator;
  33 class TDF_Attribute;
  34 class TDF_AttributeIterator;
  35 class TDF_Data;
  36 class TDF_LabelMapHasher;
  37 class Standard_GUID;
  38 class TDF_IDFilter;
  39
  40
  41 //! This class provides basic operations  to define
  42 //! a label in a data structure.
  43 //! A label is a feature in the feature hierarchy. A
  44 //! label is always connected to a Data from TDF.
  45 //! To a label is attached attributes containing the
  46 //! software components information.
  47 //!
  48 //! Label information:
  49 //!
  50 //! It is possible to know the tag, the father, the
  51 //! depth in the tree of the label, if the label is
  52 //! root, null or equal to another label.
  53 //!
  54 //! Comfort methods:
  55 //! Some methods useful on a label.
  56 //!
  57 //! Attributes:
  58 //!
  59 //! It is possible to get an attribute in accordance
  60 //! to an ID, or the yougest previous version of a
  61 //! current attribute.
  62 class TDF_Label
  63 {
  64 public:
  65
  66   DEFINE_STANDARD_ALLOC
  67
  68
  69   //! Constructs an empty label object.
  70     TDF_Label();
  71
  72   //! Nullifies the label.
  73     void Nullify();
  74
  75   //! Returns the Data owning <me>.
  76     Handle(TDF_Data) Data() const;
  77
  78   //! Returns the tag of the label.
  79   //! This is the integer assigned randomly to a label
  80   //! in a data framework. This integer is used to
  81   //! identify this label in an entry.
  82     Standard_Integer Tag() const;
  83
  84   //! Returns the label father. This label may be null
  85   //! if the label is root.
  86     const TDF_Label Father() const;
  87
  88   //! Returns True if the <aLabel> is null, i.e. it has
  89   //! not been included in the data framework.
  90     Standard_Boolean IsNull() const;
  91
  92   //! Sets or unsets <me> and all its descendants as
  93   //! imported label, according to <aStatus>.
  94   Standard_EXPORT void Imported (const Standard_Boolean aStatus) const;
  95
  96   //! Returns True if the <aLabel> is imported.
  97     Standard_Boolean IsImported() const;
  98
  99   //! Returns True if the <aLabel> is equal to me (same
 100   //! LabelNode*).
 101     Standard_Boolean IsEqual (const TDF_Label& aLabel) const;
 102   Standard_Boolean operator == (const TDF_Label& aLabel) const
 103 {
 104   return IsEqual(aLabel);
 105 }
 106
 107     Standard_Boolean IsDifferent (const TDF_Label& aLabel) const;
 108   Standard_Boolean operator != (const TDF_Label& aLabel) const
 109 {
 110   return IsDifferent(aLabel);
 111 }
 112
 113     Standard_Boolean IsRoot() const;
 114
 115   //! Returns true if <me> owns an attribute with <anID> as ID.
 116   Standard_EXPORT Standard_Boolean IsAttribute (const Standard_GUID& anID) const;
 117
 118   //! Adds an Attribute  to the current label. Raises if
 119   //! there is already one.
 120   Standard_EXPORT void AddAttribute (const Handle(TDF_Attribute)& anAttribute, const Standard_Boolean append = Standard_False) const;
 121
 122   //! Forgets an  Attribute   from the  current  label,
 123   //! setting its   forgotten status true and  its valid
 124   //! status false. Raises if   the attribute is not in
 125   //! the structure.
 126   Standard_EXPORT void ForgetAttribute (const Handle(TDF_Attribute)& anAttribute) const;
 127
 128   //! Forgets the  Attribute of  GUID <aguid> from   the
 129   //! current label   . If the   attribute doesn't exist
 130   //! returns False. Otherwise returns True.
 131   Standard_EXPORT Standard_Boolean ForgetAttribute (const Standard_GUID& aguid) const;
 132
 133   //! Forgets all the attributes. Does it on also on the
 134   //! sub-labels if <clearChildren> is set to true. Of
 135   //! course, this method is compatible with Transaction
 136   //! & Delta mecanisms.
 137   Standard_EXPORT void ForgetAllAttributes (const Standard_Boolean clearChildren = Standard_True) const;
 138
 139   //! Undo Forget action, setting its forgotten status
 140   //! false and its valid status true. Raises if the
 141   //! attribute is not in the structure.
 142   Standard_EXPORT void ResumeAttribute (const Handle(TDF_Attribute)& anAttribute) const;
 143
 144   //! Finds an attribute of the current label, according
 145   //! to <anID>.
 146   //! If anAttribute is not a valid one, false is returned.
 147   //!
 148   //! The method returns True if found, False otherwise.
 149   //!
 150   //! A removed attribute cannot be found.
 151   Standard_EXPORT Standard_Boolean FindAttribute (const Standard_GUID& anID, Handle(TDF_Attribute)& anAttribute) const;
 152
 153   //! Safe variant of FindAttribute() for arbitrary type of argument
 154   template <class T>
 155   Standard_Boolean FindAttribute (const Standard_GUID& theID, Handle(T)& theAttr) const
 156   {
 157     Handle(TDF_Attribute) anAttr = theAttr;
 158     return FindAttribute (theID, anAttr) && ! (theAttr = Handle(T)::DownCast(anAttr)).IsNull();
 159   }
 160
 161   //! Finds an attribute of the current label, according
 162   //! to <anID> and <aTransaction>. This attribute
 163   //! has/had to be a valid one for the given
 164   //! transaction index . So, this attribute is not
 165   //! necessary a valid one.
 166   //!
 167   //! The method returns True if found, False otherwise.
 168   //!
 169   //! A removed attribute cannot be found nor a backuped
 170   //! attribute of a removed one.
 171   Standard_EXPORT Standard_Boolean FindAttribute (const Standard_GUID& anID, const Standard_Integer aTransaction, Handle(TDF_Attribute)& anAttribute) const;
 172
 173   //! Returns true if <me> or a DESCENDANT of <me> owns
 174   //! attributes not yet available in transaction 0. It
 175   //! means at least one of their attributes is new,
 176   //! modified or deleted.
 177     Standard_Boolean MayBeModified() const;
 178
 179   //! Returns true if <me> owns attributes not yet
 180   //! available in transaction 0. It means at least one
 181   //! attribute is new, modified or deleted.
 182     Standard_Boolean AttributesModified() const;
 183
 184   //! Returns true if this label has at least one attribute.
 185   Standard_EXPORT Standard_Boolean HasAttribute() const;
 186
 187   //! Returns the number of attributes.
 188   Standard_EXPORT Standard_Integer NbAttributes() const;
 189
 190   //! Returns the depth of the label in the data framework.
 191   //! This corresponds to the number of fathers which
 192   //! this label has, and is used in determining
 193   //! whether a label is root, null or equivalent to another label.
 194   //! Exceptions:
 195   //! Standard_NullObject if this label is null. This is
 196   //! because a null object can have no depth.
 197   Standard_EXPORT Standard_Integer Depth() const;
 198
 199   //! Returns True if <me> is a descendant of
 200   //! <aLabel>. Attention: every label is its own
 201   //! descendant.
 202   Standard_EXPORT Standard_Boolean IsDescendant (const TDF_Label& aLabel) const;
 203
 204   //! Returns the root label Root of the data structure.
 205   //! This has a depth of 0.
 206   //! Exceptions:
 207   //! Standard_NullObject if this label is null. This is
 208   //! because a null object can have no depth.
 209   Standard_EXPORT const TDF_Label Root() const;
 210
 211   //! Returns true if this label has at least one child.
 212     Standard_Boolean HasChild() const;
 213
 214   //! Returns the number of children.
 215   Standard_EXPORT Standard_Integer NbChildren() const;
 216
 217   //! Finds a child label having <aTag> as tag. Creates
 218   //! The tag aTag identifies the label which will be the parent.
 219   //! If create is true and no child label is found, a new one is created.
 220   //! Example:
 221   //! //creating a label with tag 10 at Root
 222   //! TDF_Label lab1 = aDF->Root().FindChild(10);
 223   //! //creating labels 7 and 2 on label 10
 224   //! TDF_Label lab2 = lab1.FindChild(7);
 225   //! TDF_Label lab3 = lab1.FindChild(2);
 226   Standard_EXPORT TDF_Label FindChild (const Standard_Integer aTag, const Standard_Boolean create = Standard_True) const;
 227
 228   //! Create  a new child   label of me  using autoamtic
 229   //! delivery tags provided by TagSource.
 230     TDF_Label NewChild() const;
 231
 232   //! Returns the current transaction index.
 233   Standard_EXPORT Standard_Integer Transaction() const;
 234
 235   //! Returns true if node address of <me> is lower than
 236   //! <otherLabel> one. Used to quickly sort labels (not
 237   //! on entry criterion).
 238   //!
 239   //! -C++: inline
 240   Standard_EXPORT Standard_Boolean HasLowerNode (const TDF_Label& otherLabel) const;
 241
 242   //! Returns true if node address of <me> is greater
 243   //! than <otherLabel> one. Used to quickly sort labels
 244   //! (not on entry criterion).
 245   //!
 246   //! -C++: inline
 247   Standard_EXPORT Standard_Boolean HasGreaterNode (const TDF_Label& otherLabel) const;
 248
 249   //! Dumps the minimum information about <me> on
 250   //! <aStream>.
 251   Standard_EXPORT Standard_OStream& Dump (Standard_OStream& anOS) const;
 252 Standard_OStream& operator<< (Standard_OStream& anOS) const
 253 {
 254   return Dump(anOS);
 255 }
 256
 257   //! Dumps the label on <aStream> and its attributes
 258   //! rank in <aMap> if their IDs are kept by <IDFilter>.
 259   Standard_EXPORT void ExtendedDump (Standard_OStream& anOS, const TDF_IDFilter& aFilter, TDF_AttributeIndexedMap& aMap) const;
 260
 261   //! Dumps the label entry.
 262   Standard_EXPORT void EntryDump (Standard_OStream& anOS) const;
 263
 264
 265 friend class TDF_ChildIterator;
 266 friend class TDF_Attribute;
 267 friend class TDF_AttributeIterator;
 268 friend class TDF_Data;
 269 friend class TDF_LabelMapHasher;
 270
 271
 272 protected:
 273
 274
 275
 276
 277
 278 private:
 279
 280
 281   //! Reserved to the friends.
 282     TDF_Label(const TDF_LabelNodePtr& aNode);
 283
 284   //! Adds an Attribute to <toNode>. Raises if there is
 285   //! already one.
 286   Standard_EXPORT void AddToNode (const TDF_LabelNodePtr& toNode, const Handle(TDF_Attribute)& anAttribute, const Standard_Boolean append) const;
 287
 288   //! Forgets an Attribute from <fromNode>.  Raises if
 289   //! the attribute is not in the structure.
 290   Standard_EXPORT void ForgetFromNode (const TDF_LabelNodePtr& fromNode, const Handle(TDF_Attribute)& anAttribute) const;
 291
 292   //! Resumes a forgotten Attribute to <toNode>.  Raises
 293   //! if the attribute is not in the structure.
 294   Standard_EXPORT void ResumeToNode (const TDF_LabelNodePtr& fromNode, const Handle(TDF_Attribute)& anAttribute) const;
 295
 296   Standard_EXPORT TDF_LabelNodePtr FindOrAddChild (const Standard_Integer aTag, const Standard_Boolean create) const;
 297
 298   Standard_EXPORT void InternalDump (Standard_OStream& anOS, const TDF_IDFilter& aFilter, TDF_AttributeIndexedMap& aMap, const Standard_Boolean extended) const;
 299
 300
 301   TDF_LabelNodePtr myLabelNode;
 302
 303
 304 };
 305
 306
 307 #include <TDF_Label.lxx>
 308
 309
 310
 311
 312
 313 #endif // _TDF_Label_HeaderFile