0029116: [Regression] OCAF attributes insertion order is violated again
[occt.git] / 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_True) 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