Source Package

Overview

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:

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 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:

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:

The Source package depends on the following packages:

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:

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
Semantics

KDM assumes that a source file is a sequence of lines, identified by a linenumber. Each line is a sequence of characters, identified by a position within the line. Whitespace characters like tabulation are considered to be a single character. The "end of line" character is not considered to be part of the line.

KDM tools may use the information from the artifacts of existing software system, accessible through the SourceRegion mechanism. It is recognized that different encodings are used around the world, and it may be desired for KDM processors to read code snippets from the files that use them. The requirement for KDM tools is to read information in UTF-8.

Specification of encoding is aligned with XML specification from W3C. Each artifact of an existing system may use a different encoding for its characters. The default encoding for SourceFile is "UTF-8". Encodings other that UTF-8 should be explicitly specified in the optional encoding attribute of the SourceFile using a standard encoding label. For example, "UTF-16", "ISO-10646-UCS-2", "ISO-8859-2", ISO-2022-JP", "Shift_JIS", and "EUC-JP", etc. Encoding of the characters in the SourceFile should be taken into account by KDM consumer tools that make use of the information in the source file, through the mechanism of the SourceRegion.

 

Image Class

The Image is used to represent image files.

Superclass

InventoryItem

Semantics

Configuration Class

The Configuration is used to represent various configuration files.

Superclass

InventoryItem

Semantics

ResourceDescription Class

The ResourceDescription is used to represent resource description files.

Superclass

InventoryItem

Semantics

BinaryFile Class

The BinaryFile is used to represent binary files.

Superclass

InventoryItem

Semantics

ExecutableFile Class

The ExecutableFile is used to represent executable files for a particular platform.

Superclass

InventoryItem

Semantics

 

InventoryContainer class (generic)

The InventoryContainer meta-model element provides a container for instances of InventoryItem elements.

Superclass

AbstractInventoryElement

Associations

 

inventoryElement:AbstractInventoryElement[0..*]

The set of inventory elements owned by the container
Constraints
InventoryContainer should have at least one stereotype
Semantics

Concrete instances of the InventoryContainer element own other inventory elements (both inventory containers and individual inventory items). InventoryContainer instances represent tree-like container structures in which the leaf elements are individual IntentoryItem instances. Each InventoryContainer represents the entity set of InventoryItems owned by that container directly or indirectly.

Directory Class

The Directory class represents directories as containers that own inventory items.

Superclass

InventoryContainer

Attributes

 

path:String

Location of the directory.
Semantics

Directory items represent physical containers for the artifacts of the existing software systems, for example directories in file systems.

In addition to the general semantics of the InventoryContainer, Directory ownership structure determines the full "path" for each individual inventory item in the following way. For a given Directory item, the full "path" to an inventory item, owned by this Directory directly or indirectly, is a sequence of strings, the first element of which is the "path" attribute of the Directory, and subsequent elements are name attributes of the directory items such that each directory item is owned by the previous directory item and that last directory item owns the inventory item. Any Project containers, involved in this ownership structure are ignored.

Project class

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.

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.

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.
Semantics

KDM assumes that a source file is a sequence of lines, identified by a linenumber. Each line is a sequence of characters, identified by a position within the line. Whitespace characters like tabulation are considered to be a single character. The "end of line" character is not considered to be part of the line.

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.