11. Source Package

The Source package defines a set of meta-model elements whose purpose is to represent the physical artifacts of the existing system, such as source files, images, configuration files, resource descriptions, etc. The Source package also represents traceability links between instances of KDM meta-elements and the regions of source code, which is represented by these meta-model elements. It represents the convergence between the KDM intermediate representation and the application source it represents.

The Source package offers two capabilities for linking instances of the KDM representation to the corresponding artifacts:

Inlining the corresponding source code in the form of a “snippet” into KDM representation
Linking a KDM element to a region of the source code within some physical artifact of the system being modeled

A given KDM representation can implement either of the approaches, both of them, or none.

When a KDM element is linked to the source code within a particular physical artifact of the existing system (regardless of the existence of the corresponding snippet), KDM offers further two options:

The link can utilize the element of the KDM inventory model to identify the particular physical artifact, in which case the path to the artifact is determined through the Inventory Model.
The link can be made stand-alone and explicitly specify the path to the artifact.

The nature of the “source code” represented by a particular KDM element is unspecified within KDM. In KDM, this is indicated by the “language” attribute.

The Source package defines the KDM Inventory model which corresponds in part to the engineering view of the existing software system. It is determined by the entire software development environment of the existing software system. As a general rule, in a given KDM instance, each instance of the inventory model represents a file, or a set of files. Exceptions to this rule are:

InventoryModel element which is a part of the KDM instance infrastructure. This meta-model element is a container the instances of other inventory meta-model elements
SourceRef and SourceRegion meta-elements which represent traceability links between other instances of KDM meta-model elements and source code of the existing software system.

Inventory meta-model elements are part of the KDM instance infrastructure because they determine the traceability mechanism between other KDM elements and the regions of the physical artifacts of the existing software system that they represent.

Organization of the Source Package

The Source package consists of the following 5 class diagrams:

InventoryModel
InventoryInheritances
InventoryRelations
SourceRef
ExtendedInventoryElements

The Source package depends on the following packages:

Core
kdm

InventoryModel class diagram

InventoryModel class diagram defines meta-model elements which represent the artifacts of existing software system as “first class citizens” on the KDM instance. This model corresponds to the inventory of the artifacts. The InventoryModel class diagram follows the uniform pattern for KDM model to extend the KDM Framework with specific meta-model elements related to the engineering view of existing software systems. InventoryModel defines the following meta-model elements determined by the KDM model pattern:

InventoryModel class
AbstractInventoryElement class
AbstractInventoryRelationship class

In addition, the InventoryModel class diagram defines a concrete KDM entity for each artifact, such a SourceFile, an Image, a ResourceDescription, a Configuration description, a BinaryFile and an ExecutableFile. These meta-model elements are subclasses of the common parent class InventoryItem. The Inventory model also provides a generic KDM container called InventoryContainer and two specific containers: Directory and Project.

The classes and associations of the InventoryModel are shown at See – InventoryModel Class Diagram..

– InventoryModel Class Diagram

InventoryModel Class

The InventoryModel is a specific KDM model which corresponds to the physical (engineering) view of the existing software system. InventoryModel is a container for the instances of IInventoryItems. InventoryModel corresponds to the inventory of the physical artifacts of the existing software system..

Superclass

KDMModel

Associations

inventoryElement:AbstractInventoryElement[0..*]

The set of inventory elements owned by the inventory model

Constraints

Semantics

InventoryModel is a container for instances of inventory elements. It is the implementer’s responsibility to arrange inventory elements into one or more inventory models. KDM import tools should not make any assumptions about the organization of inventory items into inventory models.

AbstractInventoryElement Class (abstract)

The AbstractInventoryElement is the abstract parent class for all inventory entities.

Superclass
KDMEntity

Associations

inventoryRelationship:AbstractInventoryRelationship[0..*]

The set of inventory relations owned by the inventory element

Constraints

Semantics

From the meta-model perspective, this element is a common parent for all inventory entities. This element is abstract and can not occur in KDM instances. The name of the meta-model element can be used as the type constraint in stereotype definitions. Inventory package provides a concrete class InventoryElement with under specified semantics, which can be used as an extension point for defining new “virtual” inventory entities.

AbstractInventoryRelationship Class (abstract)

The AbstractInventoryRelationship is the abstract parent class for all inventory relationships.

Superclass
KDMRelationship

Constraints

Semantics
From the meta-model perspective, this element is a common parent for all inventory relationships. This element is abstract and can not occur in KDM instances. The name of the meta-model element can be used as the type constraint in stereotype definitions. Inventory package provides a concrete class InventoryRelationship with under specified semantics, which can be used as an extension point for defining new “virtual” inventory relationships.

InventoryItem class (generic)

InventoryItem is a generic meta-model element that represents any artifact of an existing software system. This class is further subclasses by several concrete meta-model elements with more precise semantics. However, InventoryItem can be used as an extended modeling element with a stereotype.

Superclass
AbstractInventoryElement

Attributes

version:String	Provides the ability to track version or revision numbers.
path:String	Location of the build resource.

Semantics
It is the implementer’s responsibility to provide a mapping from concrete types of the physical artifacts involved in the engineering of the existing software system into concrete subclasses of the InventoryItem. It is the implementer’s responsibility to map each artifact of the existing software system to some instance of KDM InventoryItem.

SourceFile Class

The SourceFile class represents source files. This meta-model element is the key part of the traceability mechanism of KDM whose purpose is to provide links between code elements and their physical implementations using the SourceRegion mechanism from the Source package.

Instances of the SourceRegion meta-model element refer to certain regions of source files to identify the original representation corresponding to a certain KDM element. In order to achieve interoperability between KDM tools that take advantage of the traceability links between the KDM elements and the regions of existing software system artifacts, KDM specification explicitly defines semantics of source files.

Superclass
InventoryItem

Attributes

language:String	Indicates the language of the source file.
encoding:String	an optional attribute that represents the encoding of the characters in the file

The Project meta-model element represents an arbitrary logical container for inventory items.

Superclass
InventoryContainer

Semantics
Project is an arbitrary container for Inventory items. It can be used in combination with Directory containers.

Example

<?xml version="1.0" encoding="UTF-8"?>

<kdm:Segment xmi:version="2.1"

xmlns:xmi="http://www.omg.org/XMI"

xmlns:kdm="http://kdm.omg.org/kdm"

xmlns:source="http://kdm.omg.org/source" name="Inventory Example">

<model xmi:id="id.0" xmi:type="source:InventoryModel">

<inventoryElement xmi:id="id.1" xmi:type="source:SourceFile" name="a.c">

<inventoryRelation xmi:id="id.2" xmi:type="source:DependsOn" to="id.5" from="id.1"/>

</inventoryElement>

<inventoryElement xmi:id="id.3" xmi:type="source:SourceFile" name="b.c">

<inventoryRelation xmi:id="id.4" xmi:type="source:DependsOn" to="id.5" from="id.3"/>

</inventoryElement>

<inventoryElement xmi:id="id.5" xmi:type="source:SourceFile" name="ab.h"/>

<inventoryElement xmi:id="id.6" xmi:type="source:Directory">

<inventoryElement xmi:id="id.7" xmi:type="source:Image"/>

<inventoryElement xmi:id="id.8" xmi:type="source:Image"/>

</inventoryElement>

<inventoryElement xmi:id="id.9" xmi:type="source:SourceFile" name="makefile"/>

<inventoryElement xmi:id="id.10" xmi:type="source:ExecutableFile" name="ab.exe"/>

</model>

</kdm:Segment>

InventoryInheritances class diagram

InventoryInheritances class diagram is determined by the KDM model pattern. This diagram defines how the classes of the InventoryModel extend the KDM Framework.
The classes and associations for this diagram are shown at See – InventoryInheritances Class Diagram..

– InventoryInheritances Class Diagram

InventoryRelations class diagram

InventoryRelations class diagram defines an optional relationship “DependsOn” between inventory elements.

The classes and associations for this diagram are shown at See – InventoryRelations Class Diagram..

– InventoryRelations Class Diagram

DependsOn class

DependsOn class is a meta-model element that represents an optional relationship between two inventory items, in which one inventory element requires another inventory element during one or more steps of the engineering process.

Associations:

from:AbstractInventoryElement[1]	the base inventory item
to:AbstractInventoryElement[1]	another inventory item on which the base item depends

Constraints:

An inventory item should not depend on itself

Semantics:
The DependsOn relationship is optional. It is the implementer’s responsibility to capture certain aspects knowledge of the engineering process in the form of “DependsOn” relations between inventory items. “DependsOn” relationship is part of the Infrastructure Layer, which is available to all KDM implementations at various compliance levels. KDM Build package which constitutes a separate L1.Build compliance point, defines more precise meta-model elements to represent the engineering view of the software system.

When the origin of the DependsOn relationship is an Inventory container, this means that all elements owned by this container (directly or indirectly) depend on the target of the relationship.

When the target of the “DependsOn” relationship is an Inventory container, this means that the one or more base inventory elements (the origin of the relationship) depends on all elements owned by the container (directly or indirectly).

SourceRef Class Diagram

The SourceRef class diagram defines a set of meta-model elements whose purpose is to provide traceability links between the elements of the KDM model of the existing software system and the physical artifacts of that system.

The class diagram shown in See – SourceRef Class Diagram. captures these classes and their relations.

– SourceRef Class Diagram

SourceRef Class

The SourceRef class represents a traceability link between a particular model element and the corresponding source code.

Superclass
Element

Attributes

language: String	Optional attribute. Indicates the source language of the snippet attribute.
snippet:String	Optional attribute. The source snippet for the given KDM element. The snippet may have some internal structure, for example XML tags corresponding to an abstract syntax tree of the code fragment. The interpretation of code snippets is outside the scope of the KDM.

Constraints
Language indicator has to be provided using at least one of the following methods:

As the attribute of the SourceRef element.
As the attribute of the SourceRegion element.
As the attribute of the SourceFile element (part of the Inventory Model), accessible via the SourceRegion element.

If both the snippet and the language attributes of the SourceRef element are present, then the language attribute should describe the nature of the code snippet, in which case the nature of the source code region accessible through the SourceRegion may be different from the nature of the code snippet. If the snippet attribute is not present, then the language attribute of the SourceRef element overrides the language attribute of the SourceRegion element, which in turn overrides the one at the SourceFile element.

Semantics
SourceRef meta-model element represents a traceability link between an instance of a KDM element to its original “source” representation as part of a physical artifact of the existing software system. KDM element that defines a traceability link to its original representation owns one or more SourceRef elements.

The Source package offers two capabilities for linking instances in KDM representation to their corresponding artifacts:

Inlining the corresponding source code in the form of a “snippet” into KDM representation
Linking a KDM element to a region of the source code within some physical artifact of the system being modeled

A given KDM representation can implement either of the approaches, both of them, or none.

The link can utilize the element of the KDM inventory model to identify the particular physical artifact, in which case the path to the artifact is determined through the Inventory Model.
The link can be made stand-alone and explicitly specify the path to the artifact.

KDM element can define more than one SourceRef traceability links. The first SourceRef element is considered as the primary one. Other elements are considered secondary. Secondary traceability links may be used to represent alternative views of the code, links to other artifacts, such as design and documentation, represent generated code, or target code during the software modernization process. Usually, secondary SourceRef elements have distinct “language” attributes, so that KDM tools can select the appropriate representation to display.

It is the implementer’s responsibility to provide adequate traceability links.

SourceRegion Class

The SourceRegion class provides a pointer to a single region of source. The SourceRegion element provides the capability to precisely map model elements to a particular region of source which is not necessarily text. The nature of the source code within the physical artifact is indicated by the language attribute of the SourceRegion element or the language attribute of the SourceFile element. The language attribute of the SourceRegion element overrides that of the SourceFile element if both are present.

The source region is located within some physical artifact of the existing software system (a source file).

Superclass
Element

Attributes

startLine: Integer	The line number of the first character of the source region.
startPosition:Integer	Provides the position of the first character.of the source region.
endLine:Integer	The line number of the last character of the source region.
endPosition:Integer	The position of the last character of the source region.
language:String	Optional attribute. The language indicator of the source code for the given source region.
path:String	Optional attribute. The location of the physical artifact that contains the given source region.

Associations

file:SourceFile[0..1]

This association allows zero or more SourceRegion elements to be associated with a single SourceFile element of the Inventory Model.

Constraints
The location of the source file should be provided using at least one of the following methods:

Path attribute of the SourceRegion element.
Path attribute of the SourceFile element of the Inventory model.

The path attribute should uniquely identify the physical artifact. The nature of the path attribute is outside of the scope of the KDM. For example, this can be a URI.

Individual SourceRef element may own multiple SourceRegion elements which represents a situation where there are multiple disjoint regions of source code that correspond to the given KDM element.

ExtenededInventoryElements Class Diagram

The ExtendedInventoryElements class diagram defines two “wildcard” generic elements for the inventory model as determined by the KDM model pattern: a generic inventory entity and a generic inventory relationship.

The classes and associations of the ExtendedInventoryElements diagram are shown in See – ExtendedInventoryElements Class Diagram..

– ExtendedInventoryElements Class Diagram

InventoryElement class (generic)

The InventoryElement class is a generic meta-model element that can be used to define new “virtual” meta-model elements through the KDM light-weight extension mechanism.

Superclass
AbstractInventoryElement

Constraints

InventoryElement should have at least one stereotype

Semantics
An inventory entity with under specified semantics. It is a concrete class that can be used as the base element of a new “virtual” meta-model entity types of the inventory model. This is one of the KDM extension points which can integrate additional language-specific, application-specific or implementer-specific pieces of knowledge into the standard KDM representation.

InventoryRelationship class (generic)

The InventoryRelationship class is a generic meta-model element that can be used to define new “virtual” inventory relationships through the KDM light-weight extension mechanism.

Superclass
AbstractInventoryRelationship

Associations

from:AbstractInventoryElement[1]	The inventory element origin endpoint of the relationship
to:KDMEntity[1]	the target of the relationship

Constraints

InventoryRelationship should have at least one stereotype

Semantics

An inventory relationship with under specified semantics. It is a concrete class that can be used as the base element of a new “virtual” meta-model relationship types of the inventory model. This is one of the KDM extension points which can integrate additional language-specific, application-specific or implementer-specific pieces of knowledge into the standard KDM representation.