Transformation extensions

You can use transformation extensions to extend and enhance custom transformations or the transformations that are available in the product.

Someone other than the author of the target transformation can create a transformation extension.

The transformation framework extensibility is based on the Eclipse plug-in architecture. Transformation extensions are plug-ins that contain the following items:

An extension to this extension point: com.ibm.xtools.transform.core.transformationExtensions
One or more TransformationExtension elements, which define the rules, extractors, or transforms that enhance the functionality of the extended transformation
One or more ExtendTransform elements, which define the transform to extend

In a TransformationExtension element, the targetTransformation attribute specifies the transformation to extend, which is also called the target transformation. A transformation extension plug-in can contain multiple TransformationExtension elements; however, if the domains of the target transformations are different, you should create a separate plug-in for each transformation extension instead of creating multiple TransformationExtension elements in one plug-in.

To extend a transformation, you must verify that the extensible and public properties of the target transformation are set to true; you must also obtain the extension point information and the identifier of the target transformation, and the identifiers of the transforms in the target transformation. You can obtain this information from the document that is specified in the document property in the manifest file of the target transformation.

You can also specify the identifier of a target transformation that is not in the current workspace; however, you cannot run the extension by running the target transformation until the target transformation is registered.

After you create a transformation extension, you can declare the rules, extractors, transforms, and properties that enhance the behavior of the target transformation. Declaring these elements does not specify their processing order in the transformation extension. For each rule, extractor, or transform that you declare, a RuleDefinition, ExtractorDefinition, or TransformDefinition element is added to the TransformationExtension element. When you run the target transformation, the core transformation functionality attempts to load the specified class for the element and adds an instance of the element to the instance of the target transformation.

You can also define properties that refine the behavior of the transformation extension. For each property that you define, a Property element is added to the TransformationExtension element. The core transformation functionality does not distinguish between the properties of the transformation extension and the properties of the target transformation. If the property that you create exists in the target transformation already, the following events occur:

If the property in the target transformation is readable and writable, the property that you create in the transformation extension overrides the default value in the target transformation.
If the property in the target transformation is read-only, the core transformation functionality ignores the property that you create.

When you create a transformation extension, you can extend multiple transforms. The extended transforms, also called target transforms, must exist in the target transformation. When you specify a transform to extend, an ExtendTransform element is added to the manifest file of the transformation extension plug-in.

After you declare the rules, extractors, and transforms of the transformation extension, you can specify the order in which they run within a target transform. An extensible transform contains a list of elements, which is a zero-based index. This list specifies the order in which the transformation engine runs the elements in the transform. When you add an element to a target transform, you can indicate where to insert the element in the existing elements of the target transform by specifying an index value or indicating which element runs after the new element:

You can specify an index value in the following ways:

To insert an element at the beginning of the target transform, specify an index value equal to zero.
To insert an element between other elements of the target transform, specify the appropriate index value.
Note: If you are not familiar with the internal structure of a transform, you should insert elements only at the beginning or at the end of the extended transform.
To insert an element at the end of the target transform, do not specify an index value.

If you do not specify an index value, the element is inserted at the end of the target transform.

For example, you can extend a transformation and declare a rule called ExtensionRule that specifies how a transformation processes a particular model element, such as a stereotyped class. You can add this rule to the specific target transform that transforms a class element in a source model. In this example, suppose that the target transform contains the following elements:

RuleA, which has an index value of 0
ExtractorB, which has an index value of 1
RuleC, which has an index value of 2

To specify that the ExtensionRule rule should run after ExtractorB, specify an index value of 2.

You can also specify the order of elements by specifying the identifier of the element that runs next in sequence after the new element. You might use this method in the following cases:

Another transformation extension might change the existing order of transformation elements
The order of the transformation elements is likely to change in future versions

After you define the elements in the transformation extension, specify the transforms to extend, and add elements to the target transforms, you can compile the transformation extension plug-in and test it in a runtime workbench. During the development and testing phases of creating transformation extension, you can enable or disable individual TransformationExtension elements. After you deploy the plug-in that contains the transformation extension, ensure that each TransformationExtension element is enabled.

To run the transformation extension, you must run the target transformation. When an instance of the target transformation is requested, the transformation service incorporates all the associated extensions into that instance of the target transformation.

If multiple transformation extensions extend the same transform, and if the index values for the transform elements conflict or do not exist, the order in which the elements run is determined by the parsing of the plug-in manifest file that Eclipse performs at startup.

Feedback