Remove and Set Parent-Child relationship through plugin

com.ibm.team.links.common.ILink

Links represent directed relationships between two endpoints, the source and target. Each endpoint is represented by an IReference , which can refer to a Jazz item, or to anything else (via a URI). Links that are intended to be undirected (symmetric) can be handled as described below.

Links have types that indicate the kind of relationship, such as duplicate or blocks. These types are specified by means of link type ids, which are expected to be unique across an entire Jazz repository, and hence are usually dotted strings that include a component name, such as "com.ibm.team.workitem.linktype.duplicateworkitem" or "com.ibm.team.workitem.linktype.blocksworkitem" from the work item component. Each link (instance) contains the appropriate link type id, and methods are provided for finding links of specified types.

The link type ids are usually not suitable for display purposes. Also, the appropriate display name might differ depending on the direction: the target being viewed from the point of view of the source, or the source being viewed from the point of view of the target. Accordingly, link types have two IEndPointDescriptor s, one describing the source and the other the target. Each can specify a display name and icon for the endpoint, appropriate for use when that endpoint is displayed from the point of view of the other. For example, the "com.ibm.team.workitem.linktype.blocksworkitem" link type has a source end point descriptor with display name "Depends On" and a target end point descriptor with display name "Blocks". In an editor for the source, the links page will show the target under "Blocks," whereas in an editor for the target, the links page will show the source under "Depends On." Methods are provided for getting the other end point reference and descriptor given the one in hand, to allow uniform coding of this kind of display without the client having to worry about whether it is starting from the source or target.

An IEndPointDescriptor can also specify some further details of its end point. For end points that are references to items, the descriptor can specify the required IItemType . If this is not specified, any item is allowed. The multiplicity can also be specified, either "0..1" indicating single- valued or "0..n" indicating multi-valued. Multiplicity is currently for use by clients only; the link component does not check that it is observed as links are created.

Link types are defined to the link component using the com.ibm.team.repository.common.linkTypes extension point. It allows specification of the link type id and the end point details noted above. If no end point descriptors are specified, the link component creates default ones. If only one end point descriptor is specified, the link component creates the other one with the same details; this effectively supports undirected (symmetric) links, which are treated the same in either direction (e.g., "Related"). The definitions are stored in the singleton registry ILinkTypeRegistry.INSTANCE , where they are available to clients.

Link are IAuditable s. They are immutable. If an end point of a link is changed, the result is deemed to be a different link - the change must be effected by deleting the current link and creating a new one.

The link component provides for manipulation of links either client-side or server-side, using similar methods. ILinkManager provides client-side operations for creating, deleting, saving and finding links. It is a Jazz client library that can be obtained from a ITeamRepository in the usual way. ILinkServiceLibrary provides similar server-side access, as a service library. An instance can be obrained from the ILinkService