Skip navigation links

Package com.ibm.xtools.transform.core

This package provides the API of the Transformation Service and the default Transformation Engine.

See: Description

Package com.ibm.xtools.transform.core Description

This package provides the API of the Transformation Service and the default Transformation Engine.

Package Specification

Transformations are used to convert models from one level of abstraction to another. Typically the conversion is from a higher level of abstraction, such as a UML model, to a lower level, such as Java code. The execution of a transformation requires one or more properties to be defined, such as the source model elements that are to be transformed and the container where the target transformation elements are to be created or updated. Other properties can be defined to enable customization of the transformation.

An extension to a transformation can be defined by someone other than the transformation author, where the extension augments the behaviour of that transformation. An extension can also define properties to enable customization of that extension.

The transformation framework provides the following features:

Transformation Service

Transformation authors define transformation descriptors in XML using the transformation provider extension point (com.ibm.xtools.transform.core.transformationProviders). The actual logic for the transformation is typically defined in code and is based upon the Transformation Engine. The Transformation Service examines its extension points at startup and populates registries of the available transformations, transformation extensions and transformation property metatypes.

The helper class TransformationServiceUtil is provided to access the available transformations. Transformations are registered in XML and can be specified as either public or private. A public transformation is visible in the UI but a private transformation can only be accessed by client code.

Transformation Properties

A transformation descriptor in XML may also specify one or more properties that a transformation can access when it is executing. These properties can be used to customize the execution of the transformation. If a read-write property is defined for a public transformation, the user will be able to change that property's value before the transformation is executed.

Every property defined by a transformation or by a transformation extension has an associated "metatype". This metatype indicates the type of value the property contains. Default metatypes supported by the Transformation Service include string, boolean, integer, resource, etc. For example, a property defined with the metatype boolean will contain a value of type Boolean.

Transformation Source and Target Model Types

As part of the transformation descriptor in XML, the author must define one or more metatypes for the source and target model types that are applicable for the transformation. The transformation UI will attempt to adapt the selected UI objects into appropriate objects based upon the specified metatypes. If UML transformation support is available, the Transformation Service also defines metatypes for UML2 semantic and UML2Notation elements.

For example, suppose a transformation requires a UML semantic element as its source and a UI object that represents a UML semantic element is selected in some model content explorer or on a diagram. The UI object selected in the explorer usually represents the UML semantic element whereas the UI object selected in a diagram represents the notational element that corresponds to the UML semantic element. Specifying a source model type of "UML2" in the XML transformation descriptor enables the transformation UI to automatically adapt the selected UI objects to the appropriate UML semantic elements before executing the transformation.

Transformation Metatypes

Using the metatype converter extension point (com.ibm.xtools.transform.core.metatypeConverters), a transformation author may define custom metatypes. These metatypes can be used either as the type for transformation properties or they can be used as transformation source and target model types. The metatype descriptor in XML defined two flags to indicate how the metatype can be used and also defines a class to perform the actual conversions. This class must be derived from AbstractMetatype.

One flag indicates the metatype converter can adapt the selection (a UI object) into a corresponding data object. only if this flag is set can the metatype be used as a transformation source or target model type.

The second flag indicates the value for this metatype can be represented by a user editable string. If this flag is set, the metatype can be used as the type for a transformation property. However, in addition to this metatype flag, the corresponding property must also be read-write before the metatype value is displayed as a string in a property sheet that the user can modify. This flag also require the metatype converter be able to resolve the user modified string back into a corresponding data object.

Transformation Extensions

A transformation extension enables a client to augment an existing transformation by inserting logic into the transformation. The extension is defined in XML using the transformation extensions extension point (com.ibm.xtools.transform.core.transformationExtensions). An extension can only augment a transformation that is based upon the Transformation Engine by inserting Rules and Extractors into the transformation hierarchy. See Transformation Engine below for more details. When an instance of a transformation is requested, the Transformation Service will automatically incorporate all appropriate extensions into that transformation instance. Thus when the transformation is executed, the original logic and the extended logic will be executed at the same time as if it were one entity.

Transformation Service Extension Points

The following Eclipse extension points are defined by the Transformation Service:


Transformation Engine

The transformation engine does not assume any structure within the source model other than the model is probably hierarchical in nature. The engine has been tailored for traversing models that are based upon a hierarchical containment meta-model, such as UML. For example, in UML a package can contain classes and other packages. A class can contain attributes, operations and other classes.

The transformation engine architecture consists of transforms, rules and content extractors, also referred to as just extractors. A transform, derived from AbstractTransform, is a container that has an ordered list of transform elements, which can be rules, extractors and other transforms (subtransforms). A transform executes a source object by executing that same object sequentially with its transform elements. A rule, derived from AbstractRule, executes the source object by converting it to one or more objects in the target model. A content extractor, derived from AbstractContentExtractor, executes a source object by extracting the appropriate contents from that source object and then executing each resulting object with the corresponding transform. A subtransform is simply a transform contained directly by a parent transform and effectively executes the same source object as if the transform elements of the subtransform were part of the parent transform. Each transform element can have an associated condition that must be accepted before the transform element is executed.

The connections between transforms, rules and extractors (the transformation hierarchy) determine how the source model is to be traversed. In most cases, a transform will contain rules and extractors and indirect references to other transforms via its extractors. These indirect references to other transforms enable the source model to be walked.

One or more rules within a transform perform the necessary processing of the source object to the target model, and one or more extractors within a transform perform the walking of the source model. The contained rules, extractors and subtransforms are kept in a single ordered list. Thus the transformation author decides how the source model is to be traversed and processed. To traverse the source model containment hierarchy, a rule would execute first on a given source model object so that one or more target model objects can be created. Then, one or more extractors would be executed (on the same source object) to process the elements contained by that source object.

Therefore, the transformation hierarchy of transforms, rules and extractors will be similar to the containment hierarchy of the source meta-model but during transformation execution, the transforms, rules and extractors are typically called recursively.

Transformation Context

The hierarchical nature of source models and the recursive nature of the transformation hierarchy require that the context in which the transforms, extractors and rules are executed must be kept in a stack-like fashion. ITransformContext is responsible for maintaining this execution contextual information, which includes the current source, target and target container objects. It also includes a local property table that enables rules to define data that can be accessed by sibling rules or by rules in nested transforms.

A new execution context object is created each time a transform is executed, with one exception. When an extractor is executed and it returns multiple source objects to be executed by its associated transform, only one new context is created that is used multiple times. All rules and extractors associated with the transform use the same context object so if one rule defines a new (temporary) property, a sibling rule can access or modify that property. When a nested transform is executed, the new execution context created is linked to its parent context. Therefore, rules within the nested transforms have access to the properties defined in all of its parent contexts in addition to the properties defined in their own context. However, the properties in parent contexts are read-only.

Custom Transformation Engine

If the transformation author wishes to use the default transformation engine, all of the transforms in the transformation will either be Transform or will be a subclass. If the author wishes to use his own transformation engine, there must still be a transformation provider and a transformation descriptor in XML. The root transform of the transformation (returned by the provider) must be derived from AbstractTransform and its execute() method starts the custom engine. In this case, the author would not be using default engine rules or extractors but would be using concepts applicable to his custom transformation engine. As a result, the transformation extension mechanism will not work.

Skip navigation links