The difference between artifacts and items is that you can only access and update artifacts through items. Since
StarTeam blends item and artifact properties into a single object (both graphically and in the SDK), you may think of them as a single
concept. Although either term works equally well in most cases, we usually use the term
item when we mean to include folder/view context that items add to artifacts. When the context is not important to the discussion,
we use the term
artifact.
The most important things to know about items are summarized below:
- Artifacts can only be accessed through items
- With
StarTeam, you can only fetch or update an artifact by directing your request to a specific item. There are no commands to directly
access an artifact independent of an item. This means that all artifact access is influenced by the context of the associated
item such as its parent folder and the view in which it lives.
- Items form folder trees
- Paths are formed by each view’s
item tree. This means that folder artifacts do not define their contents. Instead, what appears inside a folder is determined by the
items that refer to the folder’s item as their parent. You don’t really move artifacts—you move items. Moving an item from
one folder to another causes the item’s parent to be modified—the artifact referred to by the item isn’t touched. Under the
hood, items are versioned similarly to artifacts. This means that changes such as moving an item to a new folder really creates
a new item revision, causing the previous item to become historic.
- Items facilitate sharing
- Items allow an artifact to appear in multiple folders, views, and projects. To make an artifact, including its entire history,
appear in a new location, we only have to create a new item, which is pretty cheap. Sharing is analogous to “hard links” used
in UNIX file systems.
- Items influence version behavior
- An item has properties that control what artifact revision is referenced and how updates through the item are handled. Items
store an OID that determines what artifact branch is referenced. An item also stores a
configuration timestamp to indicate whether it
floats to the tip revision or is
pinned to a specific revision of the referenced branch. An item’s
branch-on-change (BOC) flag indicates if the referenced artifact should branch when modified through the item. For example, if an item currently
refers to artifact revision
1.7, and
branch-on-change is true, and an update is directed at the item, the artifact is branched by storing the updates to a new revision identified
as
1.7.1.0. Additionally, the item is modified to point to the new branch (since it has a new OID), and its BOC flag is set to
false. Note that
branch-on-change cannot be true for items that point to artifacts that can’t branch (such as topics). Also, an item with
branch-on-change equal to false and a pinned configuration timestamp is read-only because we can’t update a historic revision and we can’t
start a new branch!
- Items create promotion trees
- This is an advanced concept, so we’ll just touch on it briefly here. Items that are shared to a new location “remember” the
item from which they were shared. This “share parent” relationship is different than the “containment parent” relationship
that forms item paths. It facilitates a concept called
automatic promotion.