company logo

Property :: tryGet - Try selecting an instance in a collection

The function allows selecting an instance in a property handle by key or position. The function can also be used to locate an instance in an array attribute or to access single attribute instance.

Before a new instance is selected the current selection in the property handle is reset. In case of instance modifications on the previously selected instance, those are saved automatically. Resetting the current selection will also reset the selection for all subordinated property handles.

When no instance with the passed key or at passed position could be located (e.g. because of a filter condition), the function returns false. When an instance has been selected, the function returns true. In case of read errors or when the property handle is not accessible, the function throws an exception.
Return value:  Success ( bool  )

The value is true when the function was executed successfully. Otherwise the value is set to false.

Implementation overview

Implementation details

  1. Select located instance
    bool Property  :: tryGet (  )

    The function returns true, when an instance has been located in the property handle. When no instance is located the function returns false.

    When the instance is located but not selected, the function reads the instance.

    When an instance is already selected in the property handle and the current access mode does not correspond to the required access mode, the function will reread the instance. Thus, the function can be used to update the access mode when the selected instance was write protected. Selections in subordinated property handles are reset when rereading the instance.
    2. to list
  2. Locate instance by instance
    bool Property  :: tryGet ( odaba::Instance &cInstance )

    The function tries to locate an instance by an instance passed in vInstance. The instance type for the instance has to be the same or has to inherit from the instance type in the current property handle.

    In order to locate the instance in the property handle, an appropriate access key will be extracted from the instance.

    When no access key is available for the property handle, when types differ or when the instance does not contain data, the function throws an exception.

    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    3. to list
  3. Get instance by key value
    bool Property  :: tryGet ( odaba::Key vSortKey )

    When reading an instance by key, the key value passed in cKey is considered as key value for the currently selected access key (changeAccessKey()).

    For unordered collections, a key value for the primary key might be passed.

    When accessing instances in the VOID extent, The key can also be an LOID or a GUID string when the property handle has been opened for reading by local object identities (__LOID) or by global unique identifiers (__GUID).

    When positioning the instance for a path property the key is composed by all access keys along the path.
    • vSortKey - Access key

      The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    4. to list
  4. Get Instance by index position
    bool Property  :: tryGet ( int32 iPosition )

    Reading an instance by position selects the instance at requested position (iPosition) for the selected access key. The value passed in iPosition must be a value greater or equal to 0. In case of an invalid position value, the function throws an exception. The selected instance for a certain position depends on the selected access key.

    Using index positions for reading is also a weak point when collections are updated simultaneously, since the instance position might change when other users insert or remove entries from the collection. To avoid this one may use the lockSet() function in order to prevent other applications from updating the collection.

    Access by position cannot be used for LOID or GUID property handles. Passing a number to an LOID handle interprets the number as local object identity.

    For a path property get() by position automatically changes the selection for higher properties in the path when the end of collection is signaled for a level that is not the top level for the path property.

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    5. to list
  5. Get instance by property handle
    bool Property  :: tryGet ( odaba::Property &cProperty )

    The function tries to locate an instance by an instance selected in another property handle (rProperty). The instance type for the instance selected in rProperty has to be the same or has to inherit from the instance type in the current property handle.

    In order to locate the instance in the property handle, an appropriate access key will be extracted from the instance selected in rProperty.

    When no access key is available for the property handle, when no instance is selected in rProperty or when types differ, the function throws an exception.

    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
    6. to list
to top previous next upper table of contents Comment