company logo

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 super set.

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 source to 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 maintained 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

Implementation details

  1. 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.

    2. to list
  2. 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.
    3. to list
  3. 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.

    4. to list
  4. 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.

    5. to list
to top previous next upper table of contents Comment