Resolution While Operating Outside a Workspace
If you do not request a specific version and you are not operating within a workspace, the repository engine generally returns the most recently created version of an object. In one situation, however, the repository engine first tries to find another, preferable version of the requested object. If you are navigating from an origin object to a destination object, and there is a pinned version of the target object, the repository engine returns an interface pointer to the pinned version. If there is no pinned version, the repository engine simply returns an interface pointer to the most recently created version of the target object that participates in the relationship.
Following are some basic facts about pinning:
- The repository engine can return a pinned version (see Example One).
- If there is not a pinned version, the repository engine can return the most recent version (see Example Two).
- A destination object version can be pinned to several origin object versions (see Example Three).
- If a target object version is pinned for one versioned relationship, it is not necessarily pinned for others (see Example Four).
- You can pin at most one version of the destination object for each relationship.
- You can pin a version of the destination object only; you cannot pin an item within the target versions collection of a destination relationship.
Pinning Example One
The following figure shows a two-item collection: TestSuites-of-Version 3-of-Main. The two items are SuiteB and SuiteC. If you are not operating in a workspace and you navigate to SuiteB, the repository engine discovers a pinned version of the target object. (The figure shows the pinned version with a dashed arrow.) Thus, the repository engine returns Version 2-of-SuiteB to your program, even though Version 3-of-SuiteB was created more recently and is related to the source object version.
Pinning Example Two
The following figure shows a two-item collection: TestSuites-of-Version 3-of-Main. The two items are SuiteB and SuiteC. If you are not operating in a workspace and you navigate to SuiteC, the repository engine finds no pinned version, so it returns Version 2-of-SuiteC.
Note Although Version 3-of-SuiteC was created more recently, the repository engine does not return it because there is no relationship between it and the source object version (Version 3-of-ProductX). The repository engine returns Version 2-of-SuiteC because, among the versions related to the source object version, Version 2-of-SuiteC is the most recently created version.
Pinning Example Three
A destination object version can be pinned to any number of origin object versions. For example, the following figure shows that Version 3-of-SuiteD is the pinned destination object version of two different items.
Pinning Example Four
If a target object version is pinned for one versioned relationship, it is not necessarily pinned for others. For example, the following figure simultaneously shows three versions of Product Z, each of which has a collection containing Suite D. All three versions of Product Z use SuiteD as the target object. The top item uses Version 3-of-SuiteD as the pinned version of the target object. The middle item, even though it includes the same version (Version 3) of the target object, does not have it pinned; it uses Version 5-of-SuiteD as the pinned version of the target object. The bottom item includes both Version 3 and Version 5 of SuiteD, but it includes no pinned version at all.
