0028654: Existed tool (gendoc) for generation documentation does not take into accoun...
[occt.git] / dox / user_guides / tobj / tobj.md
1 TObj Package  {#occt_user_guides__tobj}
2 ==================
3
4 @tableofcontents
5
6 @section occt_tobj_1 Introduction
7
8 This document describes the package TObj, which is an add-on 
9 to the Open CASCADE Application Framework (OCAF).
10
11 This package provides a set of classes and auxiliary tools facilitating 
12 the creation of object-oriented data models on top of low-level OCAF data structures. 
13 This includes: 
14
15   * Definition of classes representing data objects. Data objects store their data using primitive OCAF attributes, taking advantage of OCAF mechanisms for Undo/Redo and persistence. At the same time they provide a higher level abstraction over the pure OCAF document structure (labels / attributes).
16   * Organization of the data model as a hierarchical (tree-like) structure of objects.
17   * Support of cross-references between objects within one model or among different models. In case of cross-model references the models should depend hierarchically.
18   * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without writing additional code to support persistence. 
19
20 This document describes basic principles of logical and physical organization 
21 of TObj-based data models and typical approaches to implementation of classes representing model objects.
22
23 @subsection occt_tobj_1_1 Applicability
24
25 The main purpose of the *TObj* data model is rapid development 
26 of the object-oriented data models for applications, using the existing 
27 functionality provided by OCAF (Undo/Redo and persistence) 
28 without the necessity to redevelop such functionality from scratch.
29
30 As opposed to using bare OCAF (at the level of labels and attributes), 
31 TObj facilitates dealing with higher level abstracts, which are closer 
32 to the application domain. It works best when the application data are naturally 
33 organized in hierarchical structures, and is especially useful for complex data 
34 models with dependencies between objects belonging to different parts of the model.
35
36 It should be noted that *TObj* is efficient for representing data structures containing 
37 a limited number of objects at each level of the data structure (typically less than 1000).
38 A greater number of objects causes performance problems due to list-based organization of OCAF documents. Therefore, other methods of storage, such as arrays, are advisable for data models or their sub-parts containing a great number of uniform objects. However, these methods 
39 can be combined with the usage of *TObj* to represent the high-level structure of the model.
40
41 @section occt_tobj_2 TObj Model
42
43 @subsection occt_tobj_2_1 TObj Model structure
44
45 In the *TObj* data model the data are separated from the interfaces that manage them.
46
47 It should be emphasized that *TObj* package defines only the interfaces and the basic structure of the model and objects, while the actual contents and structure of the model of a particular application are defined by its specific classes inherited from *TObj* classes. The implementation can add its own features or even change the default behaviour and the data layout, though this is not recommended. 
48
49 Logically the *TObj* data model is represented as a tree of model objects, with upper-level objects typically being collections of other objects (called *partitions*, represented by the class *TObj_Partition*). The root object of the model is called the *Main partition* and is maintained by the model itself. This partition contains a list of sub-objects called its *children* each sub-object may contain its own children (according to its type), etc. 
50
51 @figure{/user_guides/tobj/images/tobj_image003.png,"TObj Data Model",240}
52
53 As the *TObj* Data Model is based on OCAF (Open CASCADE Application Framework) technology, 
54 it stores its data in the underlying OCAF document. The OCAF document consists of a tree of 
55 items called *labels*. Each label has some data attached to it in the form of *attributes*, 
56 and may contain an arbitrary number of sub-labels. Each sub-label is identified by its sequential 
57 number called the *tag*. The complete sequence of tag numbers of the label 
58 and its parents starting from the document root constitutes the complete *entry* 
59 of the label, which uniquely identifies its position in the document.
60
61 Generally the structure of the OCAF tree of the *TObj* data 
62 model corresponds to the logical structure of the model and can be presented as in the following picture: 
63
64 @figure{/user_guides/tobj/images/tobj_image004.png,"TObj Data Model mapped on OCAF document",360}
65
66 All data of the model are stored in the root label (0:1) of the OCAF document. 
67 An attribute *TObj_TModel* is located in this root label. It 
68 stores the object of type *TObj_Model*. This object serves as a main interface tool 
69 to access all data and functionalities of the data model.
70
71 In simple cases all data needed by the application may be 
72 contained in a single data model. Moreover, *TObj* gives the possibility to 
73 distribute the data between several interconnected data models. This can be 
74 especially useful for the applications dealing with great amounts of data. because 
75 only the data required for the current operation is loaded in the memory at one time. 
76 It is presumed that the models have a hierarchical (tree-like) structure, 
77 where the objects of the child models can refer to the objects of the parent 
78 models, not vice-versa. Provided that the correct order of loading and closing 
79 of the models is ensured, the *TObj* classes will maintain references between the objects automatically.
80
81 @subsection occt_tobj_2_2 Data Model basic features
82
83 The class *TObj_Model* describing the data model provides the following functionalities: 
84
85   * Loading and saving of the model from or in a file (methods *Load* and *Save*)
86   * Closing and removal of the model from memory (method *Close*)
87   * Definition of the full file name of the persistence storage for this model (method *GetFile*)
88   * Tools to organize data objects in partitions and iterate on objects (methods *GetObjects*, *GetMainPartition*, *GetChildren*, *getPartition*, *getElementPartition*)
89   * Mechanism to give unique names to model objects 
90   * Copy (*clone*) of the model (methods *NewEmpty* and *Paste*)
91   * Support of earlier model formats for proper conversion of a model loaded from a file written by a previous version of the application (methods *GetFormatVersion* and *SetFormatVersion*)
92   * Interface to check and update the model if necessary (method *Update*)
93   * Support of several data models in one application. For this feature use OCAF multi-transaction manager, unique names and GUIDs of the data model (methods *GetModelName*, *GetGUID*)
94
95 @subsection occt_tobj_2_3 Model Persistence
96
97 The persistent representation of any OCAF model is contained in an XML or a binary file, 
98 which is defined by the format string returned by the method *GetFormat*. 
99 The default implementation works with a binary OCAF document format (*BinOcaf*). 
100 The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default 
101 implementation of two virtual methods: 
102
103 ~~~~~{.cpp}
104     virtual Standard_Boolean Load (const char* theFile); 
105     virtual Standard_Boolean SaveAs (const char* theFile); 
106 ~~~~~
107
108 which retrieve and store the model from or 
109 in the OCAF file. The descendants 
110 should define the following protected method to support Load and Save operations:
111
112 ~~~~~{.cpp}
113     virtual Standard_Boolean initNewModel (const Standard_Boolean IsNew); 
114 ~~~~~
115
116 This method is called by *Load* after creation of a new model 
117 or after its loading from the file; its purpose is to perform 
118 the necessary initialization of the model (such as creation of necessary top-level 
119 partitions, model update due to version changes etc.). Note that if 
120 the specified file does not exist, method *Load* will create 
121 a new document and call *initNewModel* with the argument **True**. 
122 If the file has been normally loaded, the argument **False** is passed. 
123 Thus, a new empty *TObj* model is created by calling *Load* with an empty 
124 string or the path to a nonexistent file as argument. 
125
126 The method *Load* returns **True** if the model has been retrieved successfully 
127 (or created a new), or **False** if the model could not be loaded. 
128 If no errors have been detected during initialization (model retrieval or creation),
129 the virtual method *AfterRetrieval* is invoked for all objects of the model. 
130 This method initializes or updates the objects immediately after the model initialization. 
131 It could be useful when some object data should be imported from an OCAF attribute into transient 
132 fields which could be changed outside of the OCAF transaction mechanism. 
133 Such fields can be stored into OCAF attributes for saving into persistent storage during the save operation.
134
135 To avoid memory leaks, the *TObj_Model* class destructor invokes *Close* method 
136 which clears the OCAF document and removes all data from memory before the model is destroyed.
137
138 For XML and binary persistence of the *TObj* data model the corresponding drivers are implemented 
139 in *BinLDrivers*, *BinMObj* and *XmlLDrivers*, *XmlMObj* packages. 
140 These packages contain retrieval and storage drivers for the model, model objects and custom attributes 
141 from the *TObj* package. The schemas support persistence for the standard OCAF and *TObj* attributes. 
142 This is sufficient for the implementation of simple data models, but 
143 in some cases it can be reasonable to add specific OCAF attributes to 
144 facilitate the storage of the data specific to the application. 
145 In this case the schema should be extended using the standard OCAF mechanism. 
146
147 @subsection occt_tobj_2_4 Access to the objects in the model
148
149 All objects in the model are stored in the main partition and accessed by iterators.
150 To access all model objects use: 
151
152 ~~~~~{.cpp}
153     virtual Handle(TObj_ObjectIterator) GetObjects () const; 
154 ~~~~~
155
156 This method returns a recursive iterator on all objects stored in the model.
157
158 ~~~~~{.cpp}
159     virtual Handle(TObj_ObjectIterator) GetChildren () const; 
160 ~~~~~
161
162 This method returns an iterator on child objects of the main partition.
163 Use the following method to get the main partition: 
164
165 ~~~~~{.cpp}
166     Handle(TObj_Partition) GetMainPartition() const; 
167 ~~~~~
168
169 To receive the iterator on objects of a specific type *AType* use the following call: 
170
171 ~~~~~{.cpp}
172     GetMainPartition()->GetChildren(STANDARD_TYPE(AType) ); 
173 ~~~~~
174
175 The set of protected methods is provided for descendant classes to deal with partitions: 
176
177 ~~~~~{.cpp}
178     virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Boolean  theHidden) const; 
179 ~~~~~
180
181 This method returns (creating if necessary) a partition in the specified label of the document. 
182 The partition can be created as hidden (*TObj_HiddenPartition* class). 
183 A hidden partition can be useful to distinguish the data that 
184 should not be visible to the user when browsing the model in the application. 
185
186 The following two methods allow getting (creating) a partition 
187 in the sub-label of the specified label in the document 
188 (the label of the main partition for the second method) and with the given name: 
189
190 ~~~~~{.cpp}
191     virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean  theHidden) const; 
192     virtual Handle(TObj_Partition) getPartition (const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean  theHidden) const; 
193 ~~~~~
194
195 If the default object naming and the name register mechanism 
196 is turned on, the object can be found in the model by its unique name: 
197
198 ~~~~~{.cpp}
199     Handle(TObj_Object) FindObject (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary) const; 
200 ~~~~~
201
202 @subsection occt_tobj_2_5 Own model data
203
204 The model object can store its own data in the Data label 
205 of its main partition, however, there is no standard API for 
206 setting and getting these data types. The descendants can add 
207 their own data using standard OCAF methods. The enumeration DataTag is defined 
208 in *TObj_Model* to avoid conflict of data labels used by this class 
209 and its descendants, similarly to objects (see below). 
210
211 @subsection occt_tobj_2_6 Object naming
212
213 The basic implementation of *TObj_Model* provides the default 
214 naming mechanism: all objects must have unique names, 
215 which are registered automatically in the data model dictionary. 
216 The dictionary is a *TObj_TNameContainer* 
217 attribute whose instance is located in the model root label.
218 If necessary, the developer can add several dictionaries into 
219 the specific partitions, providing the name registration in the 
220 correct name dictionary and restoring the name map after document is loaded from file.
221 To ignore name registering it is necessary to redefine the methods *SetName*, 
222 *AfterRetrieval* of the *TObj_Object* class and skip the registration of the object name. 
223 Use the following methods for the naming mechanism: 
224
225 ~~~~~{.cpp}
226     Standard_Boolean IsRegisteredName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const; 
227 ~~~~~
228
229 Returns **True** if the object name is already registered in the indicated (or model) dictionary. 
230
231 ~~~~~{.cpp}
232     void RegisterName (const Handle(TCollection_HExtendedString)& theName, const TDF_Label& theLabel, const Handle(TObj_TNameContainer)& theDictionary ) const; 
233 ~~~~~
234
235 Registers the object name with the indicated label where the object 
236 is located in the OCAF document. Note that the default implementation 
237 of the method *SetName* of the object registers the new name automatically 
238 (if the name is not yet registered for any other object) 
239
240 ~~~~~{.cpp}
241     void UnRegisterName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const; 
242 ~~~~~
243
244 Unregisters the name from the dictionary. Ther names of *TObj* model 
245 objects are removed from the dictionary when the objects are deleted from the model. 
246
247 ~~~~~{.cpp}
248     Handle(TObj_TNameContainer) GetDictionary() const;
249 ~~~~~
250
251 Returns a default instance of the model dictionary (located at the model root label). 
252 The default implementation works only with one dictionary. 
253 If there are a necessity to have more than one dictionary for the model objects, 
254 it is recommended to redefine the corresponding virtual method of TObj_Object 
255 that returns the dictionary where names of objects should be registered.
256
257 @subsection occt_tobj_2_7 API for transaction mechanism
258
259 Class *TObj_Model* provides the API for transaction mechanism (supported by OCAF): 
260
261 ~~~~~{.cpp}
262     Standard_Boolean HasOpenCommand() const; 
263 ~~~~~
264
265 Returns True if a Command transaction is open 
266
267 ~~~~~{.cpp}
268     void OpenCommand() const; 
269 ~~~~~
270
271 Opens a new command transaction. 
272
273 ~~~~~{.cpp}
274     void CommitCommand() const; 
275 ~~~~~
276
277 Commits the Command transaction. Does nothing If there is no open Command transaction. 
278
279 ~~~~~{.cpp}
280     void AbortCommand() const; 
281 ~~~~~
282
283 Aborts the Command transaction. Does nothing if there is no open Command transaction. 
284
285 ~~~~~{.cpp}
286     Standard_Boolean IsModified() const; 
287 ~~~~~
288
289 Returns True if the model document has a modified status (has changes after the last save) 
290
291 ~~~~~{.cpp}
292     void SetModified( const Standard_Boolean ); 
293 ~~~~~
294
295 Changes the modified status by force. For synchronization of transactions 
296 within several *TObj_Model* documents use class *TDocStd_MultiTransactionManager*. 
297
298 @subsection occt_tobj_28 Model format and version
299
300 Class *TObj_Model* provides the descendant classes with a means to control 
301 the format of the persistent file by choosing the schema used to store or retrieve operations. 
302
303 ~~~~~{.cpp}
304     virtual TCollection_ExtendedString GetFormat () const; 
305 ~~~~~
306
307 Returns the string *TObjBin* or *TObjXml* indicating 
308 the current persistent mechanism. The default value is *TObjBin*. 
309 Due to the evolution of functionality of the developed application, 
310 the contents and the structure of its data model vary from version to version. 
311 *TObj* package provides a basic mechanism supporting backward versions compatibility, 
312 which means that newer versions of the application will be able to read 
313 Data Model files created by previous versions (but not vice-versa) with a minimum loss of data. 
314 For each type of Data Model, all known versions of the data format 
315 should be enumerated in increasing order, incremented with every change 
316 of the model format. The current version of the model 
317 format is stored in the model file and can be checked upon retrieval. 
318
319 ~~~~~{.cpp}
320     Standard_Integer GetFormatVersion() const; 
321 ~~~~~
322
323 Returns the format version stored in the model file 
324
325 ~~~~~{.cpp}
326     void SetFormatVersion(const Standard_Integer theVersion); 
327 ~~~~~
328
329 Defines the format version used for save. 
330
331 Upon loading a model, the method *initNewModel()*, called immediately 
332 after opening a model from disk (on the level of the OCAF document), 
333 provides a specific code that checks the format version stored in that model. 
334 If it is older than the current version of the application, the data update can be performed. 
335 Each model can have its own specific conversion code 
336 that performs the necessary data conversion to make them compliant with the current version. 
337
338 When the conversion ends the user is advised of that by the messenger interface 
339 provided by the model (see messaging chapter for more details), 
340 and the model version is updated. If the version of data model is not supported 
341 (it is newer than the current or too old), the load operation should fail. 
342 The program updating the model after version change can be implemented as static 
343 methods directly in C++ files of the corresponding Data Model classes, 
344 not exposing it to the other parts of the application. 
345 These codes can use direct access to the model and objects data (attributes) 
346 not using objects interfaces, because the data model API and object classes 
347 could have already been changed. 
348
349 Note that this mechanism has been designed to maintain version compatibility 
350 for the changes of data stored in the model, not for the changes of 
351 low-level format of data files (such as the storage format of a specific OCAF attribute). 
352 If the format of data files changes, a specific treatment on a case-by-case basis will be required. 
353
354 @subsection occt_tobj_2_9 Model update
355
356 The following methods are used for model update to ensure its consistency 
357 with respect to the other models in case of cross-model dependencies: 
358
359 ~~~~~{.cpp}
360     virtual Standard_Boolean Update(); 
361 ~~~~~
362
363 This method is usually called after loading of the model. 
364 The default implementation does nothing and returns **True**. 
365
366 ~~~~~{.cpp}
367     virtual Standard_Boolean initNewModel( const Standard_Boolean IsNew); 
368 ~~~~~
369
370 This method performs model initialization, check and updates (as described above). 
371
372 ~~~~~{.cpp}
373     virtual void updateBackReferences( const Handle(TObj_Object)& theObj); 
374 ~~~~~
375
376 This method is called from the previous method to update back references 
377 of the indicated object after the retrieval of the model from file 
378 (see data model - object relationship chapter for more details) 
379
380 @subsection occt_tobj_2_10 Model copying
381
382 To copy the model between OCAF documents use the following methods: 
383
384 ~~~~~{.cpp}
385     virtual Standard_Boolean Paste (Handle(TObj_Model) theModel, Handle(TDF_RelocationTable) theRelocTable = 0 ); 
386 ~~~~~
387
388 Pastes the current model to the new model. The relocation table 
389 ensures correct copying of the sub-data shared by several parts of the model. 
390 It stores a map of processed original objects of relevant types in their copies. 
391
392 ~~~~~{.cpp}
393     virtual Handle(TObj_Model) NewEmpty() = 0; 
394 ~~~~~
395
396 Redefines a pure virtual method to create a new empty instance of the model. 
397
398 ~~~~~{.cpp}
399     void CopyReferences ( const Handle(TObj_Model)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable); 
400 ~~~~~
401
402 Copies the references from the current model to the target model. 
403
404 @subsection occt_tobj_2_11 Messaging
405
406 The messaging is organised using Open CASCADE Messenger from the package Message. 
407 The messenger is stored as the field of the model instance 
408 and can be set and retrieved by the following methods: 
409
410 ~~~~~{.cpp}
411     void SetMessenger( const Handle(Message_Messenger)& ); 
412     Handle(Message_Messenger) Messenger() const; 
413 ~~~~~
414
415 A developer should create his own instance of the Messenger 
416 bound to the application user interface, and attribute it to the model 
417 for future usage. In particular the messenger is used for reporting 
418 errors and warnings in the persistence mechanism. 
419 Each message has a unique string identifier (key). 
420 All message keys are stored in a special resource file TObj.msg. 
421 This file should be loaded at the start of the application 
422 by call to the appropriate method of the class *Message_MsgFile*. 
423
424 @section occt_tobj_3 Model object
425
426 Class *TObj_Object* provides basic interface and default implementation 
427 of important features of *TObj* model objects. This implementation defines 
428 basic approaches that are recommended for all descendants, 
429 and provides tools to facilitate their usage. 
430
431 @figure{/user_guides/tobj/images/tobj_image005.png,"TObj objects hierarchy",170}
432
433 @subsection occt_tobj_3_1 Separation of data and interface
434
435 In the *TObj* data model, the data are separated from the interfaces that manage them. 
436 The data belonging to a model object are stored in its root label and sub-labels 
437 in the form of standard OCAF attributes. This allows using standard OCAF mechanisms 
438 for work with these data, and eases the implementation of the persistence mechanism. 
439
440 The instance of the interface which serves as an API for managing object data 
441 (e.g. represents the model object) is stored in the root label of the object, 
442 and typically does not bring its own data. The interface classes are organized in a hierarchy 
443 corresponding to the natural hierarchy of the model objects according to the application. 
444
445 In the text below the term 'object' is used to denote either the instance 
446 of the interface class or the object itself (both interface and data stored in OCAF). 
447
448 The special type of attribute *TObj_TObject* is used for storing instances of objects interfaces 
449 in the OCAF tree. *TObj_TObject* is a simple container for the object of type *TObj_Object*. 
450 All objects (interfaces) of the data model  inherit this class. 
451
452 @figure{/user_guides/tobj/images/tobj_image006.png,"TObj object stored on OCAF label",360}
453
454
455 @subsection occt_tobj_3_2 Basic features
456
457 The *TObj_Object* class provides some basic features that can be inherited (or, if necessary, redefined) by the descendants: 
458
459   * Gives access to the model to which the object belongs (method *GetModel*) and to the OCAF label in which the object is stored (method *GetLabel*). 
460   * Supports references (and back references) to other objects in the same or in another model (methods *getReference*, *setReference*, *addReference*, *GetReferences*, *GetBackReferences*, *AddBackReference*, *RemoveBackReference*, *ReplaceReference*)
461   * Provides the ability to contain child objects, as it is actual for partition objects (methods *GetChildren*, *GetFatherObject*)
462   * Organizes its data in the OCAF structure by separating the sub-labels of the main label intended for various kinds of data and providing tools to organize these data (see <a href="../../../../Documents%20and%20Settings/TEMP/obj-inher">below</a>). The kinds of data stored separately are: 
463           * Child objects stored in the label returned by the method *GetChildLabel* 
464           * References to other objects stored in the label returned by the method *GetReferenceLabel* 
465           * Other data, both common to all objects and specific for each subtype of the model object, are stored in the label returned by the method *GetDataLabel* 
466   * Provides unique names of all objects in the model (methods *GetDictionary*, *GetName*, *SetName*)
467   * Provides unified means to maintain persistence (implemented in descendants with the help of macros *DECLARE_TOBJOCAF_PERSISTENCE* and *IMPLEMENT_TOBJOCAF_PERSISTENCE*)
468   * Allows an object to remove itself from the OCAF document and check the depending objects can be deleted according to the  back references (method *Detach*)
469   * Implements methods for identification and versioning of objects 
470   * Manages the object interaction with OCAF Undo/Redo mechanism (method *IsAlive*, *AfterRetrieval*, *BeforeStoring*)
471   * Allows make a clone (methods *Clone*, *CopyReferences*, *CopyChildren*, *copyData*)
472   * Contains additional word of bit flags (methods *GetFlags*, *SetFlags*, *TestFlags*, *ClearFlags*)
473   * Defines the interface to sort the objects by rank (methods *GetOrder*, *SetOrder*)
474   * Provides a number of auxiliary methods for descendants to set/get the standard attribute values, such as int, double, string, arrays etc.
475
476 An object can be received from the model by the following methods: 
477
478 ~~~~~{.cpp}
479     static Standard_Boolean GetObj ( const TDF_Label& theLabel, Handle(TObj_Object)& theResObject, const Standard_Boolean isSuper = Standard_False ); 
480 ~~~~~
481
482 Returns *True* if the object has been found in the indicated label (or in the upper level label if *isSuper* is *True*). 
483
484 ~~~~~{.cpp}
485     Handle(TObj_Object) GetFatherObject ( const Handle(Standard_Type)& theType = NULL ) const; 
486 ~~~~~
487
488 Returns the father object of the indicated type 
489 for the current object (the direct father object if the type is NULL). 
490
491 @subsection occt_tobj_3_3 Data layout and inheritance
492
493 As far as the data objects are separated from the interfaces and stored in the OCAF tree, 
494 the functionality to support inheritance is required. Each object has its own data 
495 and references stored in the labels in the OCAF tree. All data are stored in the sub-tree 
496 of the main object label. If it is necessary to inherit a class from the base class, 
497 the descendant class should use different labels for data and references than its ancestor. 
498
499 Therefore each *TObj* class can reserve the range of tags in each of 
500 *Data*, *References*, and *Child* sub-labels. 
501 The reserved range is declared by the enumeration defined 
502 in the class scope (called DataTag, RefTag, and ChildTag, respectively). 
503 The item *First* of the enumeration of each type is defined via the *Last* item 
504 of the corresponding enumeration of the parent class, thus ensuring that the tag numbers 
505 do not overlap. The item *Last* of the enumeration defines the last tag reserved by this class. 
506 Other items of the enumeration define the tags used for storing particular data items of the object. 
507 See the declaration of the TObj_Partition class for the example. 
508
509 *TObj_Object* class provides a set of auxiliary methods for descendants 
510 to access the data stored in sub-labels by their tag numbers: 
511
512 ~~~~~{.cpp}
513     TDF_Label getDataLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; 
514     TDF_Label getReferenceLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; 
515 ~~~~~
516
517 Returns the label in *Data* or *References* sub-labels at a given tag number (theRank1). 
518 The second argument, theRank2, allows accessing the next level of hierarchy 
519 (theRank2-th sub-label of theRank1-th data label). 
520 This is useful when the data to be stored are represented by multiple OCAF attributes 
521 of the same type (e.g. sequences of homogeneous data or references). 
522
523 The get/set methods allow easily accessing the data located in the specified data label 
524 for the most widely used data types (*Standard_Real*, *Standard_Integer*, *TCollection_HExtendedString*,
525  *TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*). 
526 For instance, methods provided for real numbers are: 
527
528 ~~~~~{.cpp}
529     Standard_Real getReal (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; 
530     Standard_Boolean setReal (const Standard_Real theValue, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0, const Standard_Real theTolerance = 0.) const; 
531 ~~~~~
532
533 Similar methods are provided to access references to other objects: 
534
535 ~~~~~{.cpp}
536     Handle(TObj_Object) getReference (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const; 
537     Standard_Boolean setReference (const Handle(TObj_Object) &theObject, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0); 
538 ~~~~~
539
540 The method *addReference* gives an easy way to store a sequence of homogeneous references in one label. 
541
542 ~~~~~{.cpp}
543     TDF_Label addReference (const Standard_Integer theRank1, const Handle(TObj_Object) &theObject); 
544 ~~~~~
545
546 Note that while references to other objects should be defined by descendant classes 
547 individually according to the type of object, *TObj_Object* provides methods 
548 to manipulate (check, remove, iterate) the existing references in the uniform way, as described below. 
549
550 @subsection occt_tobj_3_4 Persistence
551
552 The persistence of the *TObj* Data Model is implemented with the help 
553 of standard OCAF mechanisms (a schema defining necessary plugins, drivers, etc.). 
554 This implies the possibility to store/retrieve all data that are stored 
555 as standard OCAF attributes., The corresponding handlers are added 
556 to the drivers for *TObj*-specific attributes. 
557
558 The special tool is provided for classes inheriting from *TObj_Object* 
559 to add the new types of persistence without regeneration of the OCAF schema. 
560 The class *TObj_Persistence* provides basic means for that: 
561
562   * automatic run-time registration of object types
563   * creation of a new object of the specified type (one of the registered types) 
564
565 Two macros defined in the file TObj_Persistence.hxx have to be included in the definition 
566 of each model object class inheriting TObj_Object to activate the persistence mechanism: 
567
568 ~~~~~{.cpp}
569     DECLARE_TOBJOCAF_PERSISTENCE (classname, ancestorname) 
570 ~~~~~
571
572 Should be included in the private section of declaration of each class inheriting 
573 *TObj_Object* (hxx file). This macro adds an additional constructor to the object class, 
574 and declares an auxiliary (private) class inheriting *TObj_Persistence* 
575 that provides a tool to create a new object of the proper type. 
576
577 ~~~~~{.cpp}
578     IMPLEMENT_TOBJOCAF_PERSISTENCE (classname) 
579 ~~~~~
580
581 Should be included in .cxx file of each object class that should be saved and restored. 
582 This is not needed for abstract types of objects. This macro implements the functions 
583 declared by the previous macro and creates a static member 
584 that automatically registers that type for persistence. 
585
586 When the attribute *TObj_TObject* that contains the interface object is saved, 
587 its persistence handler stores the runtime type of the object class. 
588 When the type is restored the handler dynamically recognizes the type 
589 and creates the corresponding object using mechanisms provided by *TObj_Persistence*. 
590
591 @subsection occt_tobj_3_5 Names of objects
592
593 All *TObj* model objects  have names by which the user can refer to the object. 
594 Upon creation, each object receives a default name, constructed 
595 from the prefix corresponding to the object type (more precisely, the prefix is defined 
596 by the partition to which the object belongs), and the index of the object in the current partition. 
597 The user has the possibility to change this name. The uniqueness of the name in the model is ensured 
598 by the naming mechanism (if the name is already used, it cannot be attributed to another object). 
599 This default implementation of *TObj* package works with a single instance of the name container (dictionary) 
600 for name registration of objects and it is enough in most simple projects. 
601 If necessary, it is easy to redefine a couple of object methods 
602 (for instance *GetDictionary*()) and to take care of  construction and initialization of containers. 
603
604 This functionality is provided by the following methods: 
605
606 ~~~~~{.cpp}
607     virtual Handle(TObj_TNameContainer) GetDictionary() const; 
608 ~~~~~
609
610 Returns the name container where the name of object should be registered. 
611 The default implementation returns the model name container. 
612
613 ~~~~~{.cpp}
614     Handle(TCollection_HExtendedString) GetName() const; 
615     Standard_Boolean GetName( TCollection_ExtendedString& theName ) const; 
616     Standard_Boolean GetName( TCollection_AsciiString& theName ) const; 
617 ~~~~~
618
619 Returns the object name. The methods with in / out argument return False if the object name is not defined. 
620
621 ~~~~~{.cpp}
622     virtual Standard_Boolean SetName ( const Handle(TCollection_HExtendedString)& theName ) const; 
623     Standard_Boolean SetName         ( const Handle(TCollection_HAsciiString)& theName ) const; 
624     Standard_Boolean SetName         ( const Standard_CString theName ) const; 
625 ~~~~~
626
627 Attributes a new name to the object and returns **True** if the name has been attributed successfully. 
628 Returns False if the name has been already attributed to another object. 
629 The last two methods are short-cuts to the first one. 
630
631 @subsection occt_tobj_3_6 References between objects 
632
633 Class *TObj_Object* allows creating references to other objects in the model. 
634 Such references describe relations among objects which are not adequately reflected 
635 by the hierarchical objects structure in the model (parent-child relationship). 
636
637 The references are stored internally using the attribute TObj_TReference. 
638 This attribute is located in the sub-label of the referring object (called *master*) 
639 and keeps reference to the main label of the referred object. 
640 At the same time the referred object can maintain the back reference to the master object. 
641
642 @figure{/user_guides/tobj/images/tobj_image007.png,"Objects relationship",360}
643
644
645
646 The back references are stored not in the OCAF document but as a transient field 
647 of the object; they are created when the model is restored from file, 
648 and updated automatically when the references are manipulated. 
649 The class *TObj_TReference* allows storing references between objects 
650 from different *TObj* models, facilitating the construction of complex relations between objects. 
651
652 The most used methods for work with references are: 
653
654 ~~~~~{.cpp}
655     virtual Standard_Boolean HasReference( const Handle(TObj_Object)& theObject) const; 
656 ~~~~~
657
658 Returns True if the current object refers to the indicated object. 
659
660 ~~~~~{.cpp}
661     virtual Handle(TObj_ObjectIterator) GetReferences ( const Handle(Standard_Type)& theType = NULL ) const; 
662 ~~~~~
663
664 Returns an iterator on the object references. The optional argument *theType* 
665 restricts the types of referred objects, or does not if it is NULL. 
666
667 ~~~~~{.cpp}
668     virtual void RemoveAllReferences(); 
669 ~~~~~
670
671 Removes all references from the current object. 
672
673 ~~~~~{.cpp}
674     virtual void RemoveReference( const Handle(TObj_Object)& theObject ); 
675 ~~~~~
676
677 Removes the reference to the indicated object. 
678
679 ~~~~~{.cpp}
680     virtual Handle(TObj_ObjectIterator) GetBackReferences ( const Handle(Standard_Type)& theType = NULL ) const; 
681 ~~~~~
682
683 Returns an iterator on the object back references. 
684 The argument theType restricts the types of master objects, or does not if it is NULL. 
685
686 ~~~~~{.cpp}
687     virtual void ReplaceReference  ( const Handle(TObj_Object)& theOldObject,  const Handle(TObj_Object)& theNewObject ); 
688 ~~~~~
689
690 Replaces the reference to theOldObject by the reference to *theNewObject*. 
691 The handle theNewObject may be NULL to remove the reference. 
692
693 ~~~~~{.cpp}
694     virtual Standard_Boolean RelocateReferences  ( const TDF_Label& theFromRoot,  const TDF_Label& theToRoot, const Standard_Boolean theUpdateackRefs = Standard_True ); 
695 ~~~~~
696
697 Replaces all references to a descendant label of *theFromRoot* 
698 by the references to an equivalent label under *theToRoot*. 
699 Returns **False** if the resulting reference does not point at a *TObj_Object*. 
700 Updates back references if theUpdateackRefs is **True**. 
701
702 ~~~~~{.cpp}
703     virtual Standard_Boolean CanRemoveReference ( const Handle(TObj_Object)& theObj) const; 
704 ~~~~~
705
706 Returns **True** if the reference can be removed and the master object 
707 will remain valid (*weak* reference). 
708 Returns **False** if the master object cannot be valid without the referred object (*strong* reference). 
709 This affects the behaviour of objects removal from the model -- if the reference cannot be removed, 
710 either the referred object will not be removed, or both the referred 
711 and the master objects will be removed (depends on the deletion mode in the method **Detach**) 
712
713 @subsection occt_tobj_3_7 Creation and deletion of objects
714
715 It is recommended that all objects inheriting from *TObj_Object*
716  should implement the same approach to creation and deletion. 
717  
718 The object of the *TObj* data model cannot be created independently 
719 of the model instance, as far as it stores the object data in OCAF data structures. 
720 Therefore an object class cannot be created directly as its constructor is protected. 
721
722 Instead, each object should provide a static method *Create*(), which accepts the model, 
723 with the label, which stores the object and other type-dependent parameters 
724 necessary for proper definition of the object. This method creates a new object with its data 
725 (a set of OCAF attributes) in the specified label, and returns a handle to the object's interface. 
726
727 The method *Detach*() is provided for deletion of objects from OCAF model. 
728 Object data are deleted from the corresponding OCAF label; however, 
729 the handle on object remains valid. The only operation available after object deletion 
730 is the method *IsAlive*()  checking whether the object has been deleted or not, 
731 which returns False if the object has been deleted. 
732
733 When the object is deleted from the data model, the method checks 
734 whether there are any alive references to the object. 
735 Iterating on references the object asks each referring (master) object 
736 whether the reference can be removed. If the master object can be unlinked, 
737 the reference is removed, otherwise the master object will be removed too 
738 or the referred object will be kept alive. This check is performed by the method *Detach* , 
739 but the behavior depends on the deletion mode *TObj_DeletingMode*: 
740
741   * **TObj_FreeOnly** -- the object will be destroyed only if it is free, i.e. there are no references to it from other objects
742   * **TObj_KeepDepending** -- the object will be destroyed if there are no strong references to it from master objects (all references can be unlinked)
743   * **TObj_Force** -- the object and all depending master objects that have strong references to it will be destroyed.
744
745 The most used methods for object removing are: 
746
747 ~~~~~{.cpp}
748     virtual Standard_Boolean CanDetachObject (const TObj_DeletingMode theMode = TObj_FreeOnly ); 
749 ~~~~~
750
751 Returns **True** if the object can be deleted with the indicated deletion mode. 
752
753 ~~~~~{.cpp}
754     virtual Standard_Boolean Detach ( const TObj_DeletingMode theMode = TObj_FreeOnly ); 
755 ~~~~~
756
757 Removes the object from the document if possible 
758 (according to the indicated deletion mode). 
759 Unlinks references from removed objects. 
760 Returns **True** if the objects have been successfully deleted. 
761
762 @subsection occt_tobj_3_8 Transformation and replication of object data
763
764 *TObj_Object* provides a number of special virtual methods  to support replications of objects. These methods should be redefined by descendants when necessary. 
765
766 ~~~~~{.cpp}
767     virtual Handle(TObj_Object) Clone (const TDF_Label& theTargetLabel, Handle(TDF_RelocationTable) theRelocTable = 0); 
768 ~~~~~
769
770 Copies the object to theTargetLabel. The new object will have all references of its original. 
771 Returns a handle to the new object (null handle if fail). The data are copied directly, 
772 but the name is changed by adding the postfix *_copy*. 
773 To assign different names to the copies redefine the method: 
774
775 ~~~~~{.cpp}
776     virtual Handle(TCollection_HExtendedString) GetNameForClone ( const Handle(TObj_Object)& ) const; 
777 ~~~~~
778
779 Returns the name for a new object copy. It could be useful to return the same object name 
780 if the copy will be in the other model or in the other partition with its own dictionary. 
781 The method *Clone* uses the following public methods for object data replications: 
782
783 ~~~~~{.cpp}
784     virtual void CopyReferences (const const Handle(TObj_Object)& theTargetObject, const Handle(TDF_RelocationTable) theRelocTable); 
785 ~~~~~
786
787 Adds to the copy of the original object its references. 
788
789 ~~~~~{.cpp}
790     virtual void CopyChildren (TDF_Label& theTargetLabel, const Handle(TDF_RelocationTable) theRelocTable); 
791 ~~~~~
792
793 Copies the children of an object to the target child label. 
794
795 @subsection occt_tobj_3_9 Object flags
796
797 Each instance of *TObj_Object* stores a set of bit flags, 
798 which facilitate the storage of auxiliary logical information assigned to the objects 
799 (object state). Several typical state flags are defined in the enumeration *ObjectState*: 
800
801   * *ObjectState_Hidden* -- the object is marked as hidden
802   * *ObjectState_Saved* -- the object has (or should have) the corresponding saved file on disk
803   * *ObjectState_Imported* -- the object is imported from somewhere
804   * *ObjectState_ImportedByFile* -- the object has been imported from file and should be updated to have correct relations with other objects
805   * *ObjectState_Ordered* -- the partition contains objects that can be ordered.
806
807 The user (developer) can define any new flags in descendant classes. 
808 To set/get an object, the flags use the following methods: 
809
810 ~~~~~{.cpp}
811     Standard_Integer GetFlags() const; 
812     void SetFlags( const Standard_Integer theMask ); 
813     Stadnard_Boolean TestFlags( const Standard_Integer theMask ) const; 
814     void ClearFlags( const Standard_Integer theMask = 0 ); 
815 ~~~~~
816
817 In addition, the generic virtual interface stores the logical properties 
818 of the object class in the form of a set of bit flags. 
819 Type flags can be received by the method: 
820
821 ~~~~~{.cpp}
822     virtual Standard_Integer GetTypeFlags() const; 
823 ~~~~~
824
825 The default implementation returns the flag **Visible** 
826 defined in the enumeration *TypeFlags*. This flag is used to define visibility 
827 of the object for the user browsing the model (see class *TObj_HiddenPartition*). 
828 Other flags can be added by the applications. 
829
830 @subsection occt_tobj_310 Partitions
831
832 The special kind of objects defined by the class *TObj_Partition* 
833 (and its descendant *TObj_HiddenPartition*) is provided for partitioning 
834 the model into a hierarchical structure. This object represents the container 
835 of other objects. Each *TObj* model contains the main partition that is placed 
836 in the same OCAF label as the model object, and serves as a root of the object's tree. 
837 A hidden partition is a simple partition with a predefined hidden flag. 
838
839 The main partition object methods: 
840
841 ~~~~~{.cpp}
842     TDF_Label NewLabel() const; 
843 ~~~~~
844
845 Allocates and returns a new label for creation of a new child object. 
846
847 ~~~~~{.cpp}
848     void SetNamePrefix  ( const Handle(TCollection_HExtendedString)& thePrefix); 
849 ~~~~~
850
851 Defines the prefix for automatic generation of names of the newly created objects. 
852
853 ~~~~~{.cpp}
854     Handle(TCollection_HExtendedString) GetNamePrefix() const; 
855 ~~~~~
856
857 Returns the current name prefix. 
858
859 ~~~~~{.cpp}
860     Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const; 
861 ~~~~~
862
863 Generates the new name and increases the internal counter of child objects if theIsToChangeCount is **True**. 
864
865 ~~~~~{.cpp}
866     Standard_Integer GetLastIndex() const; 
867 ~~~~~
868
869 Returns the last reserved child index. 
870
871 ~~~~~{.cpp}
872     void SetLastIndex( const Standard_Integer theIndex ); 
873 ~~~~~
874
875 Sets the last reserved index. 
876
877 @section occt_tobj_4 Auxiliary classes
878
879 Apart from the model and the object, package *TObj* provides a set of auxiliary classes: 
880
881   * *TObj_Application* -- defines OCAF application supporting existence and operation with *TObj* documents.
882   * *TObj_Assistant* -- class provides an interface to the static data to be used during save and load operations on models. In particular, in case of cross-model dependencies it allows passing information on the parent model to the OCAF loader to correctly resolve the references when loading a dependent model.
883   * *TObj_TReference* -- OCAF attribute describes the references between objects in the *TObj* model(s). This attribute stores the label of the referred model object, and provides transparent cross-model references. At runtime, these references are simple Handles; in persistence mode, the cross-model references are automatically detected and processed by the persistence mechanism of *TObj_TReference* attribute. 
884   * Other classes starting with *TObj_T...* -- define OCAF attributes used to store TObj-specific classes and some types of data on OCAF labels. 
885   * Iterators -- a set of classes implementing *TObj_ObjectIterator* interface, used for iterations on *TObj* objects:
886           * *TObj_ObjectIterator* -- a basic abstract class for other *TObj* iterators. Iterates on *TObj_Object* instances. 
887           * *TObj_LabelIterator* -- iterates on object labels in the *TObj* model document 
888           * *TObj_ModelIterator* -- iterates on all objects in the model. Works with sequences of other iterators. 
889           * *TObj_OcafObjectIterator* -- Iterates on *TObj* data model objects. Can iterate on objects of a specific type. 
890           * *TObj_ReferenceIterator* -- iterates on object references. 
891           * *TObj_SequenceIterator* -- iterates on a sequence of *TObj* objects. 
892           * *TObj_CheckModel* -- a tool that checks the internal consistency of the model. The basic implementation checks only the consistency of references between objects.
893
894 The structure of *TObj* iterators hierarchy is presented below: 
895
896 @figure{/user_guides/tobj/images/tobj_image008.png,"Hierarchy of iterators",420}
897
898
899 @section occt_tobj_5 Packaging
900
901 The *TObj* sources are distributed in the following packages: 
902
903   * *TObj* -- defines basic classes that implement *TObj* interfaces for OCAF-based modelers.
904   * *BinLDrivers, XmlLDrivers* -- binary and XML driver of *TObj* package
905   * *BinLPlugin, XmlLPlugin* -- plug-in for binary and XML persistence
906   * *BinMObj, XmlMObj* -- binary and XML drivers to store and retrieve specific *TObj* data to or from OCAF document
907   * *TKBinL, TKXmlL* -- toolkits of binary and XML persistence
908
909
910