10. KDM Package
The KDM package defines key infrastructure elements that determine patterns for constructing KDM representations of existing software systems. KDM representations (also referred to as KDM instances) are instances of the KDM (which is a meta-model), where each KDM element represents a certain element of the existing system. Although in the technical sense, KDM instance is a model of the corresponding existing software system, KDM instance is not a model that represents constraints, like the ones used during the design phase, rather, this is an intermediate representation that captures precise knowledge about the application
Implementers of KDM tools are responsible for defining a mapping from the elements of programming languages, runtime platforms, and other artifacts of existing software systems into KDM elements, using semantic description and implementer’s guidelines of this specification. Kdm package describes several infrastructure elements which are present in each KDM instance. Together with the elements defined in the Core package these elements constitute the so-called KDM framework. The remaining KDM packages provide meta-model elements that represent the artifacts of existing systems.
Each KDM package follows a uniform meta-model pattern for extending the KDM framework (the Framework Extension meta-model pattern). KDM Framework is part of the KDM Infrastructure together with the elements defined in the Source package.
The Kdm package is a collection of classes and associations that define the overall structure of KDM instances. From the infrastructure perspective, KDM instances are organized into segments and then further into specific models. There are 9 kinds of models, corresponding to some well-known concerns of software engineering. From the architectural perspective, each KDM model represents a particular view of the existing system. From the infrastructure perspective, a KDM model is a typed container for model element instances. From the meta-model perspective, KDM model is represented by a separate package that defines a collection of the meta-model elements, which can be used to build representations of the particular view of existing systems. KDM framework defines a common superclass model element for all models – the KDMModel class. KDM specification uses the term “KDM model” to refer both to a meta-model element corresponding to a particular model kind and to a particular instance of such element in a concrete representation of some existing system. Explicit disambiguation (KDM model meta-model element vs. KDM model instance) will be provided when necessary.
A segment is a coherent collection of one or more related models that represents a self-contained perspective on the artifacts of the existing system. It is expected that a complete segment is extracted as a unit. It is expected that each model segment describe artifacts that involve a single programming language and a single platform.
- Framework – defines the basic elements of the kdm framework.
- Audit -defines audit information for KDM model elements.
- Annotations – provides user-defined attributes and annotations to the modeling elements
- Extensions – a class diagram that defines the overall organization of the light-weight extension mechanism of KDM
- ExtendedValues – the tagged values used by the light-weight extension mechanism
The Framework class diagram defines the meta-model elements that constitute the so-called KDM Framework: a collection of KDM models organized into nested segments. These meta-model elements determine the structure of KDM instances.
The classes and association of the Framework diagram are shown in See – Framework Class Diagram..
The KDMFramework meta-model element is an abstract class that describes the common properties of all KDM Framework elements. KDMFramework class is extended by KDMSegment and KDMModel classes. Each KDM Framework is the container for KDM light-weight extensions (extension property). The KDM extension mechanism is described further in this chapter.
|name: String [0..*]||The name of the framework element.|
|extension: ExtensionFamily [0..*]||Extensions for the current model segment.|
- to arrange instances of the KDM model elements into models (constrained only by the definition of each model)
- to arrange KDM models into one or more segments
- to provide names to KDM models and KDM segments
From the meta-model perspective, KDMModel extends the Element class. Each concrete KDM model follows the so-called Framework Extension meta-model pattern. This pattern involves the following naming conventions. Lets’ assume that “foo” is the name of the KDM model. The following rules describe the Framework Extension meta-model pattern:
- The meta-model elements for KDM model “foo” are described in a separate package, called “foo”.
- The package defines a concrete subclass of the KDMModel, called “FooModel”.
- The package defines a common abstract parent for all KDM entities specific to this KDM model, called “AbstractFooElement”. This class extends the KDMEntity class from the Core package.
- The package defines a common abstract parent for all KDM relationship specific to this KDM model, called “AbstractFooRelationship”. This class extends KDMRelationship class from the Core package
- Class “FooModel” owns class “AbstractFooElement”. This association subsets the association between the KDMModel and KDMEntity defined at the Framework class diagram.
- Class “AbstractFooElement” owns zero or more AbstractFooRelationship elements
- The package “foo” includes a “FooInheritances” class diagram, describing inheritances of “FooModel”, “AbstractFooElement” and “AbstractFooRelationship” classes, as well any other common properties related to the KDM Infrastructure, such as properties related to the Source package.
- The package “foo” includes “ExtendedFooElements” diagram which defines two generic meta-model elements “FooElement” and “FooRelationship”. These meta-model elements are extension points to package “foo”.
|ownedElement: KDMEntity[0..*]||Instances of KDM entities owned by the model. Each KDM model defines specific subclasses of KDMEntity class.|
|aggregatedRelation:AggregatedRelationship[0..*]||Instances of KDM aggregated relations owned by the model.|
It is the implementer’s responsibility to arrange instances of the KDM model elements into models (constrained only by the definition of each model) and to provide name attributes for each KDM model instance. A KDM model instance may be empty or may contain one or more instances of the elements allowed for this KDM model. A particular KDM instance may contains no KDM models of a given kind, or several such models.
Usually, KDM models corresponding to the KDM Resource Layer and Abstractions Layer have associations to the models in KDM Program Elements and Infrastructure layer. There should be no associations from the Program Elements and Infrastructure layer models to Resource and Abstractions layer models.
|getModel(): KDMModel[0..1]||This operation returns the KDM model which owns the current KDM Entity|
The Segment element represents a coherent set of logically related KDM models that together provide a useful view of an existing software system. Segment is a unit of exchange between the tools of the KDM ecosystem. Segment without owners is the top segment of the KDM model.
It is the implementer’s responsibility to arrange KDM models into segments and to provide name attributes for each KDM segment instance. A KDM segment instance may be empty or may not contain KDM models of a given kind or may contain one or more KDM models of a given kind.
KDM meta-model patterns make is possible to arrange KDM instances in such a way that the models in KDM Program Elements and Infrastructure layers are placed in a separate KDM segment, which becomes a reusable asset for multiple derivative models from the Program Elements and Infrastructure layer.
<?xml version="1.0" encoding="UTF-8"?> <kdm:Segment xmi:version="2.1" xmlns:xmi="http://www.omg.org/XMI" xmlns:code="http://kdm.omg.org/code" xmlns:kdm="http://kdm.omg.org/kdm" xmlns:source="http://kdm.omg.org/source" name="Framework Example"> <audit xmi:id="id.0" description="Illustration of KDM Framework" author="KDM FTF" date="04-03-2007"> <attribute xmi:id="id.1" tag="approved" value="yes"/> </audit> <segment xmi:id="id.2" name="foobar"/> <model xmi:id="id.3" xmi:type="code:CodeModel" name="foo"> <annotation xmi:id="id.4" text="This is a sample instance of a Code model"/> </model> <model xmi:id="id.5" xmi:type="source:InventoryModel" name="bar"> <annotation xmi:id="id.6" text="This is a sample of an Inventory model"/> </model> </kdm:Segment>
The classes and associations of the Audit class diagram are shown in See – Audit Class Diagram..
Each Framework element can have zero or more Audit instances associated with it. The collection of Audit elements is not ordered however the data property can be used to establish the temporal ordering. The Date format is “dd-mm-yyyy”, where “dd” is the date, the “mm” is the number of the month, with leading zero, if needed, and “yyyy” is the year. For example, “04-03-2007” corresponds to the “4th of March 2007”.
The implementers of KDM import tools should not make any assumptions regarding the content of the Audit element, other than the “human-readable text”. It is however expected that at least one Audit element is related to the origin of the model or segment.
The Extensions class diagram defines the meta-model elements that constitute the basis of the KDM light-weight extensions mechanism. Some additional meta-model elements are defined by the ExtendedValues class diagram.
The KDM light-weight extension mechanism is a standard way of adding new “virtual” meta-model elements to KDM. A “virtual” meta-model element is a base meta-model element with extended meaning, and possibly with extended attributes. The base meta-model element can be a “regular” element (a concrete class, not marked as “generic”), or “generic” (concrete class with under specified semantics, marked as “generic”). This mechanism is defined as part of KDM. The light-weight extensions mechanism allows introducing new “extended” meta-model element kinds (called stereotypes). The exact meaning and the intention of the “extended” meta-model elements is outside of KDM and should be communicated by implementers to the users of the extended representations.
- a stereotype definition includes the name of class of the allowed base elements. This class can be a particular concrete meta-model element, a generic element or an abstract meta-model element
2) define tags associated with a stereotype. Tags are additional attributes to the extended elements. Tag definition includes the name of the extended attribute and the name of the type of the element (represented as a string). Values of extended attributes can take the form of a string, or reference to some modeling element. Each stereotype defines its own set of tags. Tag definitions are owned by the corresponding stereotype definition.
- concrete tag values can be added to the “virtual” element if the stereotype defines tags
- each tag value is associated with the corresponding tag definition
- The complete kind of the new element is defined as the union of all stereotypes added to the element
KDM supports the light-weight extension mechanism through a Generic Element meta-model pattern. KDM defines a relatively large number of concrete meta-model elements with under specified semantic. In KDM these elements are the common superclasses for classes with specific semantics. However, generic elements can be used as extension points of the light-weight extension mechanism by using them in KDM instances with a stereotype. In addition, each KDM model defines two “wildcard” generic elements: a generic entity and a generic relationship for the given KDM model. They too can be used as extension points.
Pure KDM instances should use only concrete meta-model elements which have semantics specified in KDM, without stereotypes. KDM instances which use stereotypes are called extended KDM instances. Extended KDM instances can add stereotypes to concrete meta-model elements.
KDM light-weight extension mechanism does not support multiplicity of tags, constraints on tags, relationships between tags or stereotypes. It is the implementer’s responsibility to select the most specific extension points, by defining stereotypes in such a way that they use the base elements with the most specific semantic description (closer to the bottom of the KDM class hierarchy).
The classes and associations of the Extensions diagram are shown in See – Extensions Class Diagram.
The stereotype concept provides a way of branding (classifying) model elements so that they behave as if they were the instances of new virtual meta-model constructs. These model elements have the same structure (attributes, associations, operations) as similar non-stereotyped model elements of the same kind. The stereotype may specify additional required tagged values that apply to model elements. In addition, a stereotype may be used to indicate a difference in meaning or usage between two model elements with identical structure.
|name:String||Specifies the name of the stereotype.|
|type:String||Specifies the name of the model element to which the stereotype applies.|
|tag:TagDefinition[0..*]||Stereotype owns the set of tag definitions that determine the additional tagged values associated with the model elements that are branded with the given stereotype.|
- Tags associated with model element should not clash with any meta attributes associated with this model element.
- A model element should have at most one tagged value with a given tag name.
- A stereotype should not extend itself.
- A Stereotype can be added to ModelElement if its class is the same as the baseClass, or one of its subclasses
- The values of the Type attribute of the TagDefinition are restricted to the names of the KDM meta-elements. Names of the core datatypes (“Boolean”, “String”, “Integer”) define attributes of the extended meta-model element. The corresponding values are represented as instances of the TaggedValue class. Names of other KDM meta-elements (for example, “KDMEntity”, or “Audit”) define associations of the extended meta-element and the corresponding values are represented as instances of the TaggedRef class.
A KDM model element with one or more stereotypes has the semantics of the base element with some additional semantic constraints. The complete kind of the new element is defined as the union of all stereotypes added to the element. Extended values are the attributes of the extended element. A KDM element with one or more stereotypes is equivalent to a situation in which KDM has been extended by adding a new meta-model class that extends the base class, with the new attributes corresponding to the tag definitions.
<?xml version="1.0" encoding="UTF-8"?> <kdm:Segment xmi:version="2.1" xmlns:xmi="http://www.omg.org/XMI" xmlns:action="http://kdm.omg.org/action" xmlns:code="http://kdm.omg.org/code" xmlns:kdm="http://kdm.omg.org/kdm" name="Stereotype Example"> <extensionFamily xmi:id="id.0" name="Example extensions"> <stereotype xmi:id="id.1" name="Java method"/> <stereotype xmi:id="id.2" name="C++ method"/> <stereotype xmi:id="id.3" name="C++ procedure"/> <stereotype xmi:id="id.4" name="C++ friend"> <tag xmi:id="id.5" tag="friend_of" type="ClassUnit"/> </stereotype> <stereotype xmi:id="id.6" name="IsFriendOf"/> <stereotype xmi:id="id.7" name="native call"> <tag xmi:id="id.8" tag="implemented in" type="String"/> </stereotype> </extensionFamily> <model xmi:id="id.9" xmi:type="code:CodeModel" name="Example"> <codeElement xmi:id="id.10" xmi:type="code:ClassUnit" name="myclass"> <codeElement xmi:id="id.11" xmi:type="code:MethodUnit" stereotype="id.2" name="foo" type="id.12"> <codeElement xmi:id="id.12" xmi:type="code:Signature" name="foo"/> </codeElement> </codeElement> <codeElement xmi:id="id.13" xmi:type="code:CallableUnit" stereotype="id.4 id.3" name="bar" type="id.16" kind="regular"> <taggedValue xmi:id="id.14" xmi:type="kdm:TaggedRef" tag="id.5" reference="id.10"/> <codeRelation xmi:id="id.15" xmi:type="code:CodeRelationship" stereotype="id.6" to="id.10" from="id.13"/> <codeElement xmi:id="id.16" xmi:type="code:Signature" name="bar"/> </codeElement> </model> <model xmi:id="id.17" xmi:type="code:CodeModel"> <codeElement xmi:id="id.18" xmi:type="code:ClassUnit" stereotype="id.1"> <codeElement xmi:id="id.19" xmi:type="code:MethodUnit" stereotype="id.1" name="foobar" type="id.23"> <codeElement xmi:id="id.20" xmi:type="action:ActionElement" stereotype="id.7" name="a1"> <actionRelation xmi:id="id.21" xmi:type="action:Calls" stereotype="id.7" to="id.13" from="id.20"> <taggedValue xmi:id="id.22" xmi:type="kdm:TaggedValue" tag="id.8" value="C"/> </actionRelation> </codeElement> <codeElement xmi:id="id.23" xmi:type="code:Signature" name="foobar"/> </codeElement> </codeElement> </model> </kdm:Segment>
Lightweight extensions allows information to be attached to any model element in the form of a “tagged value” pair, (i.e., name=value). The interpretation of tagged value semantics is outside of the scope of KDM. It must be determined by the user or tool conventions. It is expected that tools will define tags to supply information needed for their operations beyond the basic semantics of KDM. Such information could include specific entities, relationships and attributes for a particular programming language, runtime platform or engineering environment.
Even though TaggedValues is a simple and straightforward extension technique, their use restricts semantic interchange of extended information about existing software systems to only those tools that share a common understanding of the specific tagged value names.
|tag:String||Contains the name of the tagged value. This name determines the semantics that are applicable to the contents of the value attribute.|
|type:String||Specifies the type of the value attribute.|
- The “value” attribute of the TaggedValue should be valid according to the type specified in the corresponding TagDefinition.
- The target of the “ref” association of the TaggedRef should be of the type specified in the corresponding TagDefinition, or one of its subtypes.
- If the type of the TaggedDefinition is one of the primitive datatypes (for example, “BooleanType”, “StringType”, “IntegerType”) the corresponding value should be an instance of the TaggedValue class.
- If the type of the TaggedDefinition is a names of some other KDM meta-elements (for example, “KDMEntity”, or “Audit”) the corresponding value should be an instance of the TaggedRef class.
Names of the tags, defined by each stereotype constitute an isolated namespace which does not interfere with the names of other stereotypes or the names of the attributes of the base type. The meaning and the intention of the stereotypes and tags is outside of the KDM specification and should be communicated by implementers to the users of the extended models. Extensions should not change the semantics of the base KDM meta-model elements, so that the model with extensions can still be interpreted as an approximation of the full extended meaning when extensions are ignored and only the basic KDM semantic rules are applied.
|name:String||Provides the name of the extension family.|
|stereotype:Stereotype[0..*]||The set of stereotypes that are owned by the extension family.|
ExtensionFamily provides a named container for stereotype definitions. It is implementer’s responsibility to arrange stereotype definitions into meaningful families. Some stereotype definitions may be made available as reusable assets in a separate segment. KDM analysis tools should not make any assumptions regarding the organization of stereotypes into families.
|taggedValue:TaggedValue[0..*]||The set of tagged values determined by the stereotype.|
- Each tagged value added to a ModelElement must conform to a certain tag definition owned by the stereotype of that ModelElement (the tag association of the TaggedValue should refer to a TaggedDefinition that is owned by a Stereotype of the ModelElement). A tagged value conforms to a tag definition when the value conforms to the type of the TagDefinition. Conformance of lightweight extensions can only be validated dynamically by a suitable KDM import tool, since lightweight extensions are not defined by the KDM standard.
- stereotype can be associated with a certain instance of a ModelElement if the type of the ModelElement is the same as the type property in the stereotype definition, or one of its subclasses
ExtendedValues class diagram defines additional meta-model constructs as part of the KDM light-weight extension mechanism. These constructs represent extended values that can be added to extended KDM model elements. The key of the light-weight extension mechanism is a meta-model construct called stereotype. Stereotypes provide additional meaning to KDM meta-model constructs. While the meaning o a stereotype is not defined within the KDM, stereotypes allow differentiation within existing KDM metamodel elements and allow adding attributes to them with extended value construct.
The classes and associations involved in the definition of extended values are shown at See – ExtendedValue Class Diagram..
ExtendedValue class is an abstract superclass for the two concrete classes that represent tagged values: the TaggedValue and the TaggedRef. ExtendedValue class defines common properties for these classes.
|tag :TagDefinition||the reference to the tag definition of the corresponding stereotype|
ExtendedValue is a “virtual” attribute to an extended KDM meta-model element. ExtendedValue element represents the value of the attribute. KDM defines two concrete subclasses of ExtendedValue: TaggedValue and TaggedRef. The definition of the attribute is provided by the TagDefinition element owned by a Stereotype element. The Stereotype element defines the “virtual” meta-model element which provides the context for the new attributes. “Virtual” attributes are instantiated every time a new “virtual” meta-model element, defined by a Stereotype is instantiated. This is an important difference between ExtendedValues and KDM attributes, which are not related to any particular meta-model element.
A tagged value allows information to be attached to any model element in the form of a “tagged value” pair, (i.e., name=value). The interpretation of tagged value semantics is outside of the scope of KDM. It must be determined by the user or tool conventions. It is expected that tools will define tags to supply information needed for their operations beyond the basic semantics of KDM. Such information could include specific entities, relationships and attributes for a particular programming language, runtime platform or engineering environment.
|Value:String||Contains the current value of the TaggedValue.|
TaggedValue element represents simple atomic “virtual” attributes. The type constraint of the value, defined in the corresponding TagDefinition can be the name of any KDM primitive type, for example “StringType”, “BooleanType”, etc.
A TaggedRef allows information to be attached to any model element in the form of a reference to another exiting model element. Each TaggedRef must conform to the corresponding TagDefinition: the actual type of the model element that is the target of the TaggedRef must be same as the type specified in the corresponding TagDefinition, or one of its subtypes. In the meta-model, TaggedRef is a subclass of ExtendedValue.
|ref:ModelElement||Designates the model element referred to by the extended value.|
- The model element that is the target of the ref association must be of the type, specified by the type attribute of the tag definition that is the target of the tag association of the tagged ref element.
TagRef represents complex “virtual” attributes, which are associations to other KDM elements. TagDefinition can be a name of any KDM meta-model element, for example, “KDMEntity”, “AbstractCodeElement”, “ControlElement”, or “CallableUnit”.
The Annotation class diagram defines meta-model elements that allow ad hoc user-defined attributes and annotations to instances of KDM elements. The mechanism of ad hoc user-defined attributes provides a capability to add pairs <tag, value> to an individual element instance. This is complimentary to the light-weight extension mechanism, which provides a new meta-model element, each instance of which has <tag, value> pair specified by the definition of the extended element. An ad hoc user-defined attribute is owned to an individual element instance. This means that different instances of the same meta-model element may own completely different user-defined attributes (and some may have none at all).
An Annotation is an ad hoc note owned by an individual element instance. Annotations and attributes are applied to the elements of KDM instances. They may be used by implementer to add specific information to an individual element. They may also be used by an analyst, annotating a given KDM instance. On the other hand, stereotypes and tag definitions as first defined as extensions to the KDM (meta-model) and then systematically used by the implementer.
The classes and associations that make up the Annotations diagram are shown in See – Annotations Class Diagram..
An attribute allows information to be attached to any model element in the form of a “tagged value” pair (i.e., name=value). Attribute add information to the instances of model elements, as opposed to stereotypes and tagged values, which apply to meta-model elements. Tagged value is part of the extension mechanism (stereotypes define virtual new model element, and tagged values specify additional attributes of these virtual model elements). Tagged values are only associated with model elements branded by a stereotype, and the set of tagged values for a particular instance of a model element is determined by its stereotype. On the other hand, arbitrary attributes may be associated with individual instances of model element. In particular, two different instances of the same model element may be annotated by different attributes.
|tag:Name||Contains the name of the attribute. This name determines the semantics that are applicable to the contents of the value attribute.|
|value:String||Contains the current value of the attribute.|
The interpretation of attribute semantics is outside the scope of KDM. It must be determined by the user or the implementer conventions. It is expected that some tools will provide capability to add arbitrary attributes to the instances of the model to supply information needed for their operations beyond the basic semantics of KDM. Such information could support analysis of KDM models by analysis, etc.
An attribute element is not related to a particular meta-model element. It does not define a “virtual” attribute to an extended meta-model element, that is instantiated with every instantiation of the new element. Instead, an attribute element can be added to any KDM element. It defines a property of a particular instance, not a property of a class of instances.
|text:String||Contains the text of the annotation to the target model element.|
|attribute:Attribute[0..*]||The set of attributes owned by the given element.|
|annotation:Annotation[0..*]||The set of annotations owned by the given element.|