This topic describes behind the scene details of the deep cloning process. Understanding these details is necessary for implementing cloning functionality for custom objects.
Initiating the Deep Clone Process
Copying Stage
Translation Stage
Initiating the Deep Clone Process
The deep cloning process can be initiated by calling one of the following
methods of the OdDbDatabase class object:
The deep cloning process is divided into two major stages:
- Copying stage
- Translation stage
Copying Stage
The copying stage physically copies the object being cloned. Deep clone functions utilize special filer objects of the
OdDbDeepCloneFiler or
OdDbWblockCloneFiler class to transfer content from the
source object to its clone. The sequence is as follows:
- A new object of the same type as the source object is created in the target location.
- The content of the source object is filed out using its
dwgOut()method to the filer. - The new object uses its
dwgIn()method to read data from the filer. - A pair of IDs of the source object and its clone is appended to the ID map.
deepClone() or wblockClone() method of each object.
To implement deep clone
functionality of a custom object, you need to override implementations
of these methods.
Translation Stage
During the translation stage, references contained in copied entities are translated to validate their values. There are three possible cases for cloned entities containing pointers to other objects depending on whether referenced objects are also cloned:
- Case 1 — The referenced object is cloned.
- Case 2 — The referenced object is not cloned. The entity is cloned to the same database.
- Case 3 — The referenced object is not cloned. The entity is cloned to a different database.
The table below illustrates how four possible situations correspond to the appropriate cases.
| Destination database | |||
| Same | Different | ||
| Referenced object | Cloned | Case 1 | Case 1 |
| Not cloned | Case 2 | Case 3 | |
Each of the cases is illustrated by the next examples.
Initially, the objects being cloned are in the following state:
In this example there are two entities "A" and "B." Entity A contains a pointer to entity B; therefore entity B is a referenced object for entity A. To show relations between objects and actions performed on them, the following symbols are used:
Case 1. After the copying stage is complete, entities A' and B' appear which are clones of entities A and B accordingly. Because entity B is the referenced object of entity A and both of them are cloned, the clone of entity B should become a referenced object of the clone of entity A. For this reason it doesn't matter whether cloned entities are in the same database as the originals or in a different database.
During the translation step, the pointer contained in entity A' is translated to a pointer to entity B'. In this way, the result of the deep clone operation is a full copy of objects including the relations between them.
Case 2. After the copying stage is complete, an entity A' appears — a clone of entity A.
Though the referenced object (entity B) has not been cloned, a pointer in cloned entity A' stays valid and no translation is required. The resulting state of objects in this case is the following:
Case 3. Like in case 2, after the copying stage is complete, an entity A' appears. The difference is that it appears in another database.
In this case the pointer to entity B contained in entity A' is not valid because there is no entity B in database DB2. The pointer now is pointing to a place in database DB2 where entity B was located in the original database DB1. During the translation stage the pointer is set to NULL because the referenced object is no longer available for cloned entity A'.
After the translation stage is finished, the result looks like this: