Transformation extensibility

Transformation extensibility allows you to modify transformation output. For instance, you can generate a member variable and a specific constructor for UML classes stereotyped <<singleton>>. To do this, you have to provide several things:

• An Eclipse plug-in to hold extended functionality
• A description in the plugin.xml of the transformation?s extension point(s) used by the plug-in
• Rule(s) that implement this functionality

Once you complete and install the plug-in containing a transformation extension, the transformation engine picks it up and runs it as a part of the transformation. For the UML to C++ transformation, this means that -- in addition to the normal transformation process -- rules added by the plug-in will run on the UML elements being processed by the transformation.

The transformation extensibility mechanism is based on the generic extensibility mechanisms built into Eclipse. Transformations provide extension points that serve as points to which new processing can be added. Typically, you will use transformation rules to describe this new processing. Also, you can add new transformations and extractors to the extension points.

Back to top

Quick overview of the UML to C++ transformation extensibility

With IBM® Rational® Software Architect version 6.0.0.1 and later, the UML to C++ transformation has three extension points:

• Class and interface extensibility (com.ibm.xtools.transform.uml2.cpp.ClassExtendTransform)
• Enumeration extensibility (com.ibm.xtools.transform.uml2.cpp.EnumerationExtendTransform)
• Operation extensibility (com.ibm.xtools.transform.uml2.cpp.OperationExtendTransform)

You can add extractors, transformations, or rules to these extension points. The following abstract rules supplied by the transformation help you extend classes, interfaces, and enumerations:

• CPPExtendClassRule: Inherit from this rule to alter code generation for UML classes. This rule supports the addition of attributes, operations, standard operations, inclusions, generalizations, prefixes, and suffixes.
• CPPExtendInterfaceRule: Inherit from this rule to alter code generation for UML interfaces. This rule supports the addition of attributes, operations, standard operations, inclusions, generalizations, prefixes, and suffixes.
• CPPExtendEnumerationRule: Inherit from this rule to alter code generation for UML enumerations. This rule supports the addition of attributes, prefixes, and suffixes.
• CPPExtendOperationRule: Inherit from this rule to extend code generation for UML operations. This rule supports the addition of operation bodies.

Back to top

Extension points

The UML to C++ transformation has three extension points that support adding extended functionality to the processing of UML classes, interfaces, enumerations, and operations.

All transformation extensions follow a common format. The Eclipse extension is declared in the plugin.xml of the extension point com.ibm.xtools.transform.core.transformationExtensions. This Eclipse extension contains a transformation extension that specifies target transformation (com.ibm.xtools.transform.uml2.cpp.CPPTransformation for the UML to C++ transformation), and an ExtendTransform section shown in Listing 1:

<extension
         point="com.ibm.xtools.transform.core.transformationExtensions">
      <TransformationExtension
            targetTransformation="com.ibm.xtools.transform.uml2.cpp.CPPTransformation"
            ...>
         <ExtendTransform targetTransform="...">
            ...
         </ExtendTransform>
      </TransformationExtension>
   </extension>

The ExtendTransform section adds some transformation elements required for you to get the desired extended functionality.

You have to define the transformation elements (rules, transformations, and extractors) before they can be used in the ExtendTransform section. The code sample in Listing 2 shows how you can add a rule to the UML class processing:

<extension
         point="com.ibm.xtools.transform.core.transformationExtensions">
      <TransformationExtension
            targetTransformation="com.ibm.xtools.transform.uml2.cpp.CPPTransformation"
            ...>
         <RuleDefinition
               class="com.ibm.xtools.transform.uml2.cpp.tests.actions.TestClassRule"
               id="com.ibm.xtools.transform.uml2.cpp.tests.TestInheritanceRuleClass"/>
         <ExtendTransform targetTransform="&">
            <AddRule id="com.ibm.xtools.transform.uml2.cpp.tests.TestInheritanceRuleClass"/>
         </ExtendTransform>
      </TransformationExtension>
   </extension>

The ExtendTransform section adds some transformation elements required for you to get the desired extended functionality. Note that the RuleDefinition section ties a Java? class implementing a rule with the string ID. To avoid ambiguity, you should make this ID a unique string. To create the ID used in this example, the plug-in name was concatenated with some phrase describing the rule?s functionality.

Extensions have to specify the transformation extension point they connect to in the ExtendTransform section. To add processing to the UML classes and interfaces, specify a target transform with the following ID: com.ibm.xtools.transform.uml2.cpp.ClassExtendTransform

In Listing 3, a code sample from the plugin.xml file illustrates how to extend the transformation at this point:

<extension
         point="com.ibm.xtools.transform.core.transformationExtensions">
      <TransformationExtension
            targetTransformation="com.ibm.xtools.transform.uml2.cpp.CPPTransformation"
            id="com.ibm.xtools.transform.uml2.cpp.CPPTestExtentionClass"
            version="1.0.0">
         <RuleDefinition
               class="com.ibm.xtools.transform.uml2.cpp.tests.actions.TestClassRule"
               id="com.ibm.xtools.transform.uml2.cpp.tests.TestInheritanceRuleClass"/>
         <ExtendTransform targetTransform="com.ibm.xtools.transform.uml2.cpp.ClassExtendTransform">
            <AddRule id="com.ibm.xtools.transform.uml2.cpp.tests.TestInheritanceRuleClass"/>
         </ExtendTransform>
      </TransformationExtension>
   </extension>

In this example, TestClassRule is the rule that performs additional processing for UML classes and interfaces.

You can add multiple rules to extension points. You can also use this extension point to add rules for both specialized class processing and specialized interface processing.

The second transformation extension point allows extra processing for UML enumerations. This extension point uses a target transform with the following ID: com.ibm.xtools.transform.uml2.cpp.EnumerationExtendTransform

The code sample from the plugin.xml file in Listing 4 illustrates how to extend the transformation at this point:

<extension
         point="com.ibm.xtools.transform.core.transformationExtensions">
      <TransformationExtension
            targetTransformation="com.ibm.xtools.transform.uml2.cpp.CPPTransformation"
            id="com.ibm.xtools.transform.uml2.cpp.CPPTestExtentionEnumeration"
            version="1.0.0">
         <RuleDefinition
               class="com.ibm.xtools.transform.uml2.cpp.tests.actions.TestEnumRule"
               id="com.ibm.xtools.transform.uml2.cpp.tests.TestInheritanceRuleEnumeration"/>
         <ExtendTransform targetTransform="com.ibm.xtools.transform.uml2.cpp.EnumerationExtendTransform">
            <AddRule id="com.ibm.xtools.transform.uml2.cpp.tests.TestInheritanceRuleEnumeration"/>
         </ExtendTransform>
      </TransformationExtension>
   </extension>

In this example, TestEnumRule is the rule that performs additional processing for UML enumerations.

The last transformation extension point allows you to specify the body of the operation. This extension point uses a target transform with the following ID: com.ibm.xtools.transform.uml2.cpp.OperationExtendTransform

Listing 5 shows a code sample from the plugin.xml file that illustrates how to extend the transformation at this point:

 <extension
         point="com.ibm.xtools.transform.core.transformationExtensions">
      <TransformationExtension
            targetTransformation="com.ibm.xtools.transform.uml2.cpp.CPPTransformation"
            id="com.ibm.xtools.transform.uml2.cpp.CPPTestExtentionOperation"
            version="1.0.0">
         <RuleDefinition
               class="com.ibm.xtools.transform.uml2.cpp.tests.actions.TestOperationRule"
               id="com.ibm.xtools.transform.uml2.cpp.tests.TestOperationRule"/>
         <ExtendTransform targetTransform="com.ibm.xtools.transform.uml2.cpp.OperationExtendTransform">
            <AddRule id="com.ibm.xtools.transform.uml2.cpp.tests.TestOperationRule"/>
         </ExtendTransform>
      </TransformationExtension>
   </extension>

In this example, TestOperationRule is the rule that performs additional processing for UML operations.

Table 1 shows a summary of the transformation extension points of the UML to C++ transformation.

Back to top

Transformation rules

You can use the abstract rules supplied in the com.ibm.xtools.transform.uml2.cpp package to gain access to C++ code generation:

• CPPExtendClassRule: Provides functionality for UML classes
• CPPExtendInterfaceRule: Provides functionality for UML interfaces
• CPPExtendEnumerationRule: Provides functionality for UML enumerations
• CPPExtendOperationRule: Provides functionality for UML operations

This paper refers to these rules as extensibility rules.

The following three classes provide common functionality to the extensibility rules. Typically, the transformation extensions do not use them directly:

• CPPExtendFramework: This framework establishes the mechanism for the extensions
• CPPExtendRule: This base rule provides text-level functionality
• CPPExtendClassifierRule: This rule provides functionality for both UML classes and interfaces

Figure 1 illustrates the relationship between these rules.

Back to top

Common functionality of the UML to C++ extensibility rules

The extensibility rules expose two methods to add new functionality:

• createTargetExt: Implement this method to provide extra processing for the UML element
• canAcceptExt: If necessary, override this method to narrow the acceptance conditions for your rules

Table 2 summarizes the methods available to all C++ extensibility rules:

Typically, you pass the rule execution context unchanged from createTargetExt and canAcceptExt to these methods.

CPPExtendOperationRule has the specific goal of adding an operation body, and is separate from the other extensibility rules. It supports createTargetExt and canAcceptExt, but not the prefix or suffix methods.

Back to top

UML class and interface extensibility

You can use CPPExtendClassRule to extend the transformation functionality for UML classes. Similarly, you can use the CPPExtendInterfaceRule to extend the transformation functionality for UML interfaces.

In addition to the common functionality of the extensibility rules, the following functionality (see Table 3) is also available in CPPExtendClassRule and CPPExtendInterfaceRule:

The rule in the code sample shown in Listing 6 adds inheritance from CObject to every generated class:

public class TestClassRule extends CPPExtendClassRule {
	
	public TestClassRule() {
		super("com.ibm.xtools.transform.uml2.cpp.tests.Inheritance"); //$NON-NLS-1$
	}
	
	public void createTargetExt(final ITransformContext ruleContext) {

		addGeneralization(CPPExtendClassifierRule.InheritanceKind.PUBLIC,"CObject",ruleContext)
		;//$NON-NLS-1$
	}
}

Note that methods addGeneralization and addInclusion have two forms. One form accepts a UML element as an argument. Proper inclusion processing (file path determination and inclusion coalescing) is performed by those methods. Another form accepts String as an argument, allowing references to objects residing outside of the UML model. It is the responsibility of the extension to ensure that proper inclusion paths are used in those methods.

Back to top

UML enumeration extensibility

You can use CPPExtendEnumerationRule to extend the transformation functionality for UML enumerations. In addition to the common functionality of the extensibility rules, the following functionality (see Table 4) is also available:

The rule in the sample shown in Listing 7 adds the attribute none with a constant expression of 0 to every generated enumeration:

public class TestEnumRule extends CPPExtendEnumerationRule {
	
	public TestEnumRule() {
		super("com.ibm.xtools.transform.uml2.cpp.tests.Enumeration"); //$NON-NLS-1$
	}
	
	public void createTargetExt(final ITransformContext ruleContext) {
		addAttribute("none", "0", null, ruleContext); //$NON-NLS-2$//$NON-NLS-1$
	}
}

Back to top

UML operation extensibility

You can use CPPExtendOperationRule to extend the transformation functionality for UML operations. This class supplies the functionality shown in Table 5:

Listing 8 shows a rule providing a body for UML operations:

public class TestOperationRule extends CPPExtendOperationRule {
	
	public TestOperationRule() {
		super("com.ibm.xtools.transform.uml2.cpp.tests.Operation");
	}
	
	public boolean canAcceptExt(ITransformContext context) {
		Operation myOperation = getSourceOperation(context);
		if (myOperation == null)
			return false;
		else
			return myOperation.getName().startsWith("ABC");
	}
	
	public void createTargetExt(ITransformContext ruleContext) {
		Operation myOperation = getSourceOperation(ruleContext);
		String variableName = "theInt_" + myOperation.getName().substring(3);
		// creates code: int theInt_var = 90; theInt_var++;
		String operationBody = "int " + variableName + " = 90; " + variableName + "++;";
		addBody(operationBody, ruleContext);
	}
}

Note that this example overwrites the canAcceptExt method to add bodies only to the methods with names starting with "ABC". It then uses the rest of the operation name to construct the variable name for the operation?s body.

For a detailed description of the UML to C++ extension points and extensibility rules, use the product help by clicking IBM Rational Software Modeler Extensibility help > API Reference > Transformations > com.ibm.xtools.transform.uml2.cpp.

Back to top

Tutorial: Acme Enterprise extension

To illustrate the extensibility of the transformation, you can create a simple plug-in that does the following things:

• Makes every generated C++ class inherit from CObject
• Adds a copyright line to the top of the header files
• Provides a skeleton for the Serialize method

You can follow these step-by-step instructions, or jump to the end and use the provided source code (see Download section). If you receive a compiling error, ensure that the entries in the plugin.xml file are typed correctly, as this is the most common source of errors. You can consult Figure 4 to check the contents of your plugin.xml file.

Creating plug-in

Start by creating a sample plug-in to hold the extended functionality:

1. Start Rational Software Architect.
2. Switch to the Plug-in Development perspective.
3. On the menu, click File > New > Plug-in Project.
4. In the New Plug-in wizard, specify com.acme.test as the project name and click Next.
5. In the wizard, accept the defaults and click Finish.

You've now created the com.acme.test plug-in, which is displayed in the Package Explorer view.

The sample plug-in will require functionality from the following plug-ins:

• com.ibm.xtools.transform.uml2.cpp (UML to C++ transformation)
• com.ibm.xtools.transform.core (Transformation engine)
• org.eclipse.uml2 (UML2 definitions)

To specify those dependencies, perform the following steps.

1. Open the plugin.xml for the com.acme.test plug-in by double-clicking it in the Package Explorer.
2. Switch to the Dependencies tab
3. Click the Add button.

Remember to add all three plug-ins.

Make sure that you save the plugin.xml so that Eclipse can pick up the changes you just made.

Creating extensibility rule

Once you have a plug-in, you can add functionality to it. Start by making a rule that adds inheritance from CObject to every C++ class that the transformation generates, as shown in the following steps.

1. In the Package Explorer view, expand the src entry under the com.acme.test plug-in
2. Right-click the package com.acme.test.
3. On the context menu, click New > Class. This starts the New Java Class wizard.

We will set several options on this wizard page:

4. Enter ACMEObjectas the Namefor the class
5. As this rule is going to operate on UML classes, it has to be a subclass of CPPExtendClassRule. Specify com.ibm.xtools.transform.uml2.cpp.CPPExtendClassRule as the Superclass
6. Select the following method subs to be created: Constructors from superclass and Inherited abstract methods.
7. Once all options are selected (as shown in Figure 2), click Finishto create the class.

You can now finish this rule by supplying code for the constructor and the createTargetExt method.

The transformation engine expects the rule to have a constructor with no arguments. However, the constructor generated by the wizard takes String as an argument. To fix this, double-click ACMEObject.java and remove the argument from the constructor. As a result, you should have ACMEObject() instead of ACMEObject(String arg0).

Because the superclass expects a unique string identifier as the argument for the constructor, you should make the following line the body of the constructor for ACMEObject:

super("com.acme.test.AcmeClassExtend");

The actual job of extending the transformation is done by the createTargetExt method. To add inheritance from CObject to all of the C++ classes supplied to this rule, add the following line to the body of the createTargetExtmethod:

addGeneralization(CPPExtendClassifierRule.InheritanceKind.PUBLIC, "CObject", arg0);

You should also add the required import statement to the ACMEObject class and save the file:

import com.ibm.xtools.transform.uml2.cpp.CPPExtendClassifierRule

Connecting your rule to the transformation

You created the rule that provides extended functionality. Now, you must connect it to the UML to C++ transformation. You make this connection through the Eclipse extension mechanism by creating extensions in the plugin.xml file.

In this tutorial, you add a rule to process UML classes. The logic behind connecting the rule to the transformation looks like this:

• Declare that you are going to extend a transformation
• Specify the transformation to extend (UML to C++)
• Declare the rule that you want to add ( ACMEObject) and give it a string Id
• Specify the transformation point that you want to work on (Class extension point)
• Add the declared rule into this transformation point using its ID

The following procedures provide step-by-step instructions for how to connect the rule to the transformation.

To implement the extensions:

1. Open the plugin.xml file.
2. Switch to the Extensionstab (shown in Figure 3) and click Add.
3. In the Extension Pointslist, click com.ibm.xtools.transform.core.transformationExtension
4. Click Finish.

To declare that you are extending the UML to C++ transformation ( com.ibm.xtools.transform.uml2.cpp.CPPTransformation):

1. Right-click com.ibm.xtools.transform.core.transformationExtension
2. Click New > TransformationExtension.
3. Specify the following properties for the transformation extension:

To declare the transformation rule implemented by the class ACMEObject:

1. Right-click com.acme.test.TransformationExtension1
2. Click New > RuleDefinition.
3. Specify the following properties for the rule definition:

To specify the transformation extension point to which you are attaching the rule:

1. Right-click com.acme.test.TransformationExtension1; then click New > ExtendTransform.
2. Specify the following properties for the transform extension:

To add the declared rule to the transformation extension point:

1. Right-click com.ibm.xtools.transform.uml2.cpp.ClassExtendTransform
2. Click New > AddRule.
3. Specify the following property for the added rule:

Don?t forget to save the plugin.xml file. At this point it should look similar to Listing 9.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin
   id="com.acme.test"
   name="Test Plug-in"
   version="1.0.0"
   provider-name="ACME"
   class="com.acme.test.TestPlugin">

   <runtime>
      <library name="test.jar">
         <export name="*"/>
      </library>
   </runtime>

   <requires>
      <import plugin="org.eclipse.ui"/>
      <import plugin="org.eclipse.core.runtime"/>
      <import plugin="com.ibm.xtools.transform.uml2.cpp"/>
      <import plugin="com.ibm.xtools.transform.core"/>
      <import plugin="org.eclipse.uml2"/>
   </requires>
   <extension
         point="com.ibm.xtools.transform.core.transformationExtensions">
      <TransformationExtension
            targetTransformation="com.ibm.xtools.transform.uml2.cpp.CPPTransformation"
            enabled="true"
            id="com.acme.test.TransformationExtension1"
            version="1.0.0">
         <RuleDefinition
               class="com.acme.test.ACMEObject"
               id="com.acme.test.ACMEObjectRule"/>
         <ExtendTransform targetTransform="com.ibm.xtools.transform.uml2.cpp.ClassExtendTransform">
            <AddRule id="com.acme.test.ACMEObjectRule"/>
         </ExtendTransform>
      </TransformationExtension>
   </extension>

</plugin>

Testing your work

The easiest way to test the plug-in is to run another instance of the workbench. Make sure that you do not have compiling errors in the plug-in, then click Run > Run As > Run-Time Workbench.

Assuming you have debug options set to the default values, the new instance of the workbench starts incorporating plug-ins from your current workspace. To test your work:

1. Switch to the Modeling perspective.
2. Click File > New > UML Model.
3. To add a class to the UML model, right-click the model, then click Add UML > Class.
4. Run the UML to C++ transformation on the model.
5. Open the resulting header file and note that the inheritance from CObject was added to the class definition.

Back to top

More extensions

With the infrastructure in place, it becomes very easy to add new functionality to the transformation.

For example, to add a copyright notice to every generated header file, add the following line to the ACMEObject's method createTargetExt:

addHeaderPrefix("// (C) Copyright Acme Corp. 2005. All Rights Reserved.", arg0);

Or, if you want to generate a skeleton of the Serialize method in C++ classes, add the following line to the same method:

addOperation("Serialize", "void", VisibilityKind.PUBLIC_LITERAL, "CArchive &ar", "CArchive &ar", null, "if (ar.IsStoring()) {/* TBD */} else {/* TBD */}", false, false, false, false, false, false, arg0);

Remember to add the following import statement:

import org.eclipse.uml2.VisibilityKind;

Of course, the previous examples are oversimplified. You can make the extensions more interesting by filtering elements to be processed based on their properties -- such as names or stereotypes being applied -- or by creating specific attributes and method bodies for the serialization functionality.

So, as a developer, the flexibility of the UML to C++ extensibility in Rational Software Architect gives you some powerful tools to customize your transformations.

Back to top

Download

Information about download methods

Resources

• Get the evaluation version of Rational Software Architect from the Trials and betas page.
  
  
• The IBM Software Developer Platform homepage provides detailed information on the overall IBM Software Development platform, of which Rational Software Architect is a part.
  
  
• For technical resources about Rational's products, visit the developerWorks Rational content area. You'll find technical documentation, how-to articles, education, downloads, product information, and more. For specific information about Rational Software Architect, visit the RSA technical resources page.
  
  
• Find more product related information by visiting the IBM Rational marketing pages.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• You can read more about UML 2.0 at the UML Resource Center.
  
  
• Ask questions about Rational Software Architect in the Rational Software Architect, Software Modeler, Application Developer and Web Developer forum.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Transformation extensibility
• Quick overview of the UML to C++ transformation extensibility
• Extension points
• Transformation rules
• Common functionality of the UML to C++ extensibility rules
• UML class and interface extensibility
• UML enumeration extensibility
• UML operation extensibility
• Tutorial: Acme Enterprise extension
• More extensions
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Software Architect
• Demo: Model Rational RequisitePro requirements in Rational Software Architect
• Webcast: Harnessing the power of enterprise architecture
• Briefing: Architecture, design, and construction using the IBM Rational Software Delivery Platform
• Buy: Rational Software Architect

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers