Property :: move - Move instance to another collection

The function moves an instance from the source collection ( rSourceProperty ) to the collection of the current property handle. This is the only way, to move dependent or owned instances from one collection to another one. It is also a save way to copy instances avoiding duplicate key problems, that may result from the inverse reference for local collections. The function allows also moving instances between distinct sub-collections of an extent.

The function cannot be called in order to move an instance within the same collection, i.e. source and target have to refer to different collections. The type of the target collection must be identical to the type of the instance to be moved. When the target collection is weak-typed, the source instance must inherit from the type of the target collection. Finally, one cannot move instances to not owning collections, which have not got a superset.

When the type of source and target instance is the same and when both, source and target property handle have been opened for the same database handle, the instance is removed from the source collection and inserted into the target collection. In this case the instance does not change local or global identity. When the collections differ in type, the instance is copied from the source to the target collection and removed/deleted from the source collection afterwards.

When the access key selected for the target property handle refers to a unique index and an instance with the same key value as extracted from the source instance does already exist, the function will replace an existing instance when passing a replace option or throws an exception otherwise.

The function returns the selected property handle. In case of an error, the function throws an exception.

Notes:

For extents and relationships super sets are not yet maintaind by this function!

Return value: Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Move without rename
Property :: move ( rSourceProperty )
Move with rename
Property :: move ( rSourceProperty, vNewKey )
Rename and replace while moving
Property :: move ( rSourceProperty, vNewKey, eReplace )
Move and replace
Property :: move ( rSourceProperty, eReplace )

Implementation details

Move without rename
odaba::Property & Property :: move ( odaba::Property &rSourceProperty )

The function moves the instance without renaming. When the instance does already exist in the target collection, the function throws an exception.
- rSourceProperty - Source property handle
  The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.

to list

Move with rename
odaba::Property & Property :: move ( odaba::Property &rSourceProperty, odaba::Key vNewKey )

The function allows renaming an instance while moving it to the target collection. When the new key does already exist in the target collection the function throws an exception.
- rSourceProperty - Source property handle
  The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.
- vNewKey - New key value for instance
  The key passed for renaming the instance must be structured according to the currently selected sort order. Key components within a key must be separated by '|' or ';'. An empty string can be passed in order to indicate no key value.
  
  In order to pass no key value, an empty string ( String() ) has to be passed.

to list

Rename and replace while moving
odaba::Property & Property :: move ( odaba::Property &rSourceProperty, odaba::Key vNewKey, odaba::ReplaceOptions eReplace )

The function allows renaming an instance while moving it to the target collection. When the new key does already exist in the target collection the instance is overwritten depending on the value passed in eReplace .

In order to replace an existing instance in the target collection, ReplaceLocal should to be passed in eReplace . When an instance with the new key value ( vNewKey ) does already exist in the target collection, it will be removed from the target collection before moving the source instance to the target collection.
- rSourceProperty - Source property handle
  The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.
- vNewKey - New key value for instance
  The key passed for renaming the instance must be structured according to the currently selected sort order. Key components within a key must be separated by '|' or ';'. An empty string can be passed in order to indicate no key value.
  
  In order to pass no key value, an empty string ( String() ) has to be passed.
- eReplace - Replace option
  Replace options can be passed in order to control the behavior of copy functions.

to list

Move and replace
odaba::Property & Property :: move ( odaba::Property &rSourceProperty, odaba::ReplaceOptions eReplace )

The function moves the instance without renaming. In order to replace an existing instance in the target collection, ReplaceLocal should to be passed in eReplace . When the instance does already exist in the target collection, it will be removed from the target collection before moving the source instance to the target collection.
- rSourceProperty - Source property handle
  The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.
- eReplace - Replace option
  Replace options can be passed in order to control the behavior of copy functions.

to list

to top Comment