Deep Clone Basics

A set of functions for deep cloning is implemented as methods of the class OdDbDatabase. Deep clone functions can copy an object or a set of objects within a single database or between different databases. "Deep" means that when a selected primary object is cloned, the deep clone functions also clone the objects that the primary object owns. If you need to clone just a single object without its ownership, use the shallow clone function. There are three deep clone functions:

OdDbDatabase::deepCloneObjects() — Deep clones objects within a single database.
OdDbDatabase::wblock() — Deep clones objects from the current database to a new one.
OdDbDatabase::insert() — Deep clones objects to the current database from another one.

Different deep clone functions handle object references in different ways.

The deep clone function OdDbDatabase::deepCloneObjects() makes a copy of an object (a set of objects) and appends it in the same database. The ownership references of the cloned objects are followed and referenced objects are also cloned. All references of clones are then translated if necessary. Pointer references are ignored during cloning.

To clone objects to a new database, use the wblock clone function OdDbDatabase::wblock(). Unlike OdDbDatabase::deepCloneObjects(), this function follows hard ownership and hard pointer references of the object being cloned. Soft references are ignored.

To clone objects to the current database from another database, use the insert function OdDbDatabase::insert(). It processes references of cloned objects in the same way as OdDbDatabase::deepCloneObjects().

The following table summarizes the differences in approaches for handling references by deep clone functions.

	Owner		Pointer
	Hard	Soft	Hard	Soft
deepCloneObjects() insert()	+	+	-	-
wblock()	+	-	+	-

Translation of object references is an important step of the deep cloning procedure. It is responsible for validating references of the newly created clone. References of the clone can become invalid in some cases. For more details, see Deep Cloning Process. As a result of a deep cloning operation, a copy of the original object with translated references appears in the destination database.

To keep track of the deep clone process, an ID map is used. The ID map contains pairs of object IDs. Each pair consists of the ID of the original object and the ID of the cloned object, so that the original and cloned objects are mapped to each other. The ID map may also contain ID pairs of non-cloned objects if they have to be referenced by cloned objects. When the objects being cloned are copied, the ID map is filled in. Later, at the stage of translation, the ID map is used to validate and translate references of the cloned object.

Deep clone functions can clone multiple objects within a single call. But you must ensure that all cloned objects have the same owner. To simultaneously clone multiple objects from different owners, call a deep clone function for each owner, but using the same ID map for all of the calls. Using the same ID map is necessary for operating the deep clone function at the translation stage. See Typical Deep Clone Operations for details.

In general, using deep clone functions does not require advanced knowledge of the exact cloning process. However, if you develop a custom object and want to override default cloning functionality, see Advanced Deep Clone Topics.

See Also