Package wt.vc.struct

See:
Description

Interface Summary

StructService

This service for the struct package contains "navigetters" to navigate the IteratedUsageLink, IteratedReferenceLink and IteratedDescribeLink to both Mastered and Iterated objects.

Class Summary

AbstractStructLinkRIEHandler	Supported API: false Extendable: false
IteratedDescribeLink	A link specifying that an iteration provides descriptive information for a another iteration.
IteratedDescribeLinkRIEHandler	Returns a user friendly message when a ReferentialIntegrityException occurs when deleting an IteratedDescribeLink.
IteratedReferenceLink	A link specifying that an iteration (implementation) refers to another master.
IteratedReferenceLinkRIEHandler	Supported API: false Extendable: false
IteratedUsageLink	The IteratedUsageLink is an association between an iteration and a master.
IteratedUsageLinkRIEHandler	Supported API: false Extendable: false
StandardStructService	This implementation of StructService has adds several listeners in StandardStructService.performStartupProcess() that deal primarily with copying links and validating deletes.
StructHelper	This helper is for the StructService and accesses that service via StructHelper.service.
StructServiceFwd	This service for the struct package contains "navigetters" to navigate the IteratedUsageLink, IteratedReferenceLink and IteratedDescribeLink to both Mastered and Iterated objects.

Package wt.vc.struct Description

vc package - Version Structuring Service

The wt.vc.struct package introduces an associative model for relating versions. Versioned data forms links to other versioned data to further describe that data - parts associate to other parts to form structures, indicating that a part is composed of or built from other parts. Similarly, it is common for a document to refer to other documentation. The struct package defines a "uses" and a "references" concept to reflect these kinds of associations.

The following figure illustrates the uses concept.

Link Representing the Uses Concept

The uses concept is a structuring concept indicating a tight coupling. An object that uses another object identifies that object as essential to its implementation. For example, a part built from other parts is not complete without these part; they are required components. The struct package encapsulates the uses concept for use by versioned data in the IteratedUsageLink.

The following figure illustrates the references concept.

Link Representing the References Concept

The references association couples data more loosely than the uses association. For example, the referenced data may be important to a document, but the document can be disseminated without it. For example, a design specification that references the requirements specification it was written for is still complete on its own. The struct package's IteratedReferenceLink allows versioned data to participate in references associations.

The wt.vc.struct package's IteratedUsageLink and IteratedReferenceLink both link Iterated data (versions) to Mastered data (masters). The fact that a master, not an iteration (or version), is used or referenced by an implementation is an important aspect of the links definition. They assume the versions for the master are interchangeable and that changes that are not interchangeable result in a new master (not a new, incompatible version). Note that the shared aggregation modeled on the IteratedUsageLink shows its tighter coupling.

The following figure illustrates the struct package APIs.

struct Package APIs

The struct package provides navigate APIs for both the IteratedUsageLink and IteratedReferenceLink for convenience and because of minor behavioral nuances. The navigateUses and navigateReferences APIs behave exactly as would PersistenceManager's navigate, however navigateUsedBy and navigateReferencedBy return only versions; they filter out any iteration that is not the latest iteration. The navigateUsesToIteration and navigateReferencesToIteration APIs navigate the links to the masters, then resolve the masters to their appropriate versions using the passed ConfigSpec. The masters for which there are no appropriate versions are returned to indicate that the association exists but has no qualifying representation given the ConfigSpec. The return value for the navigate to iterations API, a QueryResult, consists of those versions (and possibly masters) if onlyOtherSide is true. If it is false (that is, the links are desired as well) a QueryResult containing Persistable's as elements is returned. Each element is an array of length 2 with the link in the 0th position and the version (or master) in the 1st position.

The IteratedUsageLink and IteratedReferenceLink, while conceptually different, have the same internal behavior. This following characteristics are shared by both associations:

• When an Iterated object is created from an existing one (as a consequence of a check-out, new version, or new branch), all IteratedUsageLinks and IteratedReferenceLinks to that iteration are copied. This copy uses PersistenceManagerSvr's copyLink API, which allows listeners of the COPY_LINK event to copy any links to the IteratedUsageLink/IteratedReferenceLink that should be copied.
• To create, delete, or update IteratedUsageLinks or IteratedReferenceLinks, the user must have permission to modify the Iterated object.
• Creating these links between an iteration and its own master is not allowed.
• A master can not be deleted if it has IteratedUsageLinks or IteratedReferenceLinks to it.

The customization, via extension, of the IteratedUsageLink and the IteratedReferenceLink follows the same process as does any ObjectToObjectLink. Note that the links are protected by the iterations; if the iteration is frozen, so are these links. For this reason, it should not be necessary to build a lot of business knowledge into the links; the business knowledge should be put on the versions. Also note that struct's navigate APIs will navigate at the abstract IteratedUsageLink/IteratedReferenceLink level. If extended and it is desired to navigate only the new, concrete link, new APIs are required to guarantee that only the new link is navigated.