Introduction

One of the typical workflows in using the IBM® Rational® Software Architect design and development tool for model-driven development is to create a Unified Modeling Language (UML) model to represent a particular system. This tool also provides several predefined transformations that will convert the UML model into any of the supported programming languages. However, rather than using the ones provided, you can create your own transformation that will convert the model according to rules that you define.

The extensibility features in Rational Software Architect provide tools to create Java™ Emitter Template (JET) transformations and specify your own rules for the generation of output from the transformations. JET is a template language developed by IBM. By using JET transformations, you can quickly and easily generate a template-based model-to-text transformation. With the JET toolkit, you can generate text files from a model by using templates that contain text and JET commands (tags). JET transformations automate the repetitive process of text generation.

This article guides you through the steps of authoring a new JET transformation to create a Java project that represents a book library.

Back to top

Create and configure the JET transformation project

To use the JET technology to create transformations, the target domain expert must provide an Exemplar project to the transformation author. The Exemplar project represents the desired format of the output of the transformation. The best practice is to create an Exemplar project that represents as many details as possible of the format for the required output. The project must be imported into the Rational Software Architect workspace.

For the purposes of this article, a simple Java™ project (MyLibrary) that contains a Java class (BookTitle) within a package (books) is the example. When the JET transformation is created and executed, the expected output of the transformation will be a Java project that contains one or more Java classes within a package.

Figure 1 shows the exemplar Java project used in this article.

In order to develop the JET transformation that will accept a UML model as a source and generate a Java project as a target, you must create a new JET Project with Exemplar Authoring in Rational Software Architect:

1. Select File > New > Project from the main menu.
2. From the JET Transformations category, specify JET Project with Exemplar Authoring.
3. Name the project com.test.my.transform.
4. Accept the defaults on the next page, and then click the Next button.
5. From the Transformation Scope page, select the MyLibrary project, and then click Finish.

The created project contains the transform.tma file that you will use in this exercise mainly to develop the desired transformation. It opens in the editor view automatically, with two tabs: Schema and Overview. The Overview tab (Figure2) displays general information about the transformation.

You will work in the Schema tab (Figure 3) to develop the transformation output actions.

As the first step, the Exemplar project has to be analyzed. It might contain artifacts that you do not plan to generate in your output. In our example we do not want the transformation to generate .class files. The generation of these classes will be performed in the target Java project automatically based on the .java files.

To delete BookTitle.class from the Exemplar schema:

6. Right-click BookTitle.class in the Transform Authoring window.
7. Select Delete from the menu.

In Figure 4, the Exemplar project in its final version is shown in the transformation Schema editor.

Develop the input and output schema actions

Now you are ready to develop the input schema and output actions so that you can generate the transformation output automatically.

To specify the target Java project generation:

1. Right-click the root entry in the "Define the transformation input schema and output actions" pane, and select New >Type from the context menu.
2. Give the new type the name projectInfo.
3. Add a new project named my.project to the projectInfo type.
4. To create output actions, drag the .classpath and .project files from the Exemplar pane onto the my.project node in the Transform Input and output actions pane.
5. In the Transformation input schema and output actions pane, rename the created files as .project and .classpath.

The files are now added to the "Transformation input schema and output actions" pane. In the Exemplar pane, icons near the .project and .classpath file nodes appear. This indicates that actions have been created for these elements (see Figure 5).

Larger view of Figure 5.

6. If you do not see the Properties view in your workspace, right-click any added element in "Transformation input schema and output actions" pane, and select Show Properties View from the context menu.
7. Add an attribute called name to the projectInfo type.

The created transformation should be flexible so that it can generate projects with various names for different libraries. To enable this flexibility:

8. Right-click the projectInfo type in the "Define the transformation input schema and output actions" pane, and select New > Attribute from the context menu.
9. Call the new attribute name.
10. (Optional) Right-click the name attribute, and select Edit Exemplar Text from the context menu.
11. In the Edit Exemplar Text window, add the project name MyLibrary to the name attribute (Figure 6).
12. Click Add and then OK.

The exemplar's project name is displayed in the Properties view under the Exemplar Text field (see Figure 7).

Replace the Exemplar Text string

This Exemplar Text string can be automatically replaced with the name that you want to use for the project when you are ready to run the transformation. The output project will be generated with the user-defined name specified in the source model.

Follow these steps to specify that the Exemplar Text should be replaced according to user input when the transformation is executed:

1. Select the my.project project.
2. In the Properties view, under the Action Parameters section, right-click the value for the Name property.
3. Select Replace with model reference (see Figure 8).

Larger view of Figure 8.

4. In the "Replace with Model References" dialog window, select the name attribute of the projectInfo type, and then click OK (Figure 9).
   

As a result, the value of the Action Parameter name of the project called my.project is replaced with the {$projectInfo/@name} tag (Figure 10).

Specify transformation actions for generating artifacts

Now you are going to specify the transformation actions for generating project artifacts.

To generate a Java file for each library item, an output action needs to be created and linked with the exemplar Java file. To do this, you add a new type called "item" to the "projectInfo" type, and specify Java class generation:

1. In the "Transformation input schema and output actions" pane, right-click the projectInfo type.
2. From the context menu, select New > Type.
3. Name the new type item.
4. Drag the BookTitle.java file from the Exemplar pane onto the item type.
5. Name the file myBookTitle.java.
   

The new myBookTitle.java file is now added to the "Transformation input schema and output actions" pane. An icon is displayed next to BookTitle.java in the Exemplar pane, indicating that this file is linked to the new myBookTitle.java file in the other pane. Notice that, in the Properties view under the Action section, you can add conditions for generation, as well as a description of any of the generated artifacts (see Figure10).

Save the created schema and update the project:

6. From the main menu, select File > Save All.
7. In the editor view in the "Transformation input schema and output actions" pane, right-click the root type and select Update Project (Figure11).

The folders for each type will be generated, containing JET templates that specify the generation of each required file (Figure 12).

The main.jet template file contains tags that specify the generation of the .project, .classpath, and myBookTitle.java files (Figure 13).

Larger view of Figure 13.

Replace hard-coded strings with xPath expressions

To add flexibility in generating a variety of output results, various hard-coded strings in JET templates can be updated with xPath expressions. Here, we will describe a few of the possible options as examples, as well as the recommended workflow.

1. In the "Transformation input schema and output actions" pane, select the myBookTiltle.java file (Figure14).
2. In the Properties view under "Action parameters," select the MyLibrary/books value of the path property, right-click it, and select the "Replace with Model Reference" menu item.

Larger view of Figure 14.

Figure 15 shows the resulting dialog window: Replace with Model References.

In this dialog window, you can select an existing attribute or create a new one. Here, we will demonstrate the creation of a new attribute that will describe the generation of the package name.

3. Select the projectInfo type.
4. Click New.

When you click the New button, the "Create New Derived Attribute" dialog window will appear (Figure 16). In this window, you can define the attribute with the value derived from the calculation. The attribute's name field should be populated by you, the user. the exemplar text field is populated with the string that you selected when the dialog was invoked, and the same string is written, by default, for the Calculation value. Leave the default value for this exercise, but, in a real-world transformation you can replace it with an XPath expression.

5. Add the pkgDir string to the "Attribute name" text field.
6. Click OK to close the "Create New Derived Attribute" window.
7. Click OK to close the "Replace with Model References" window.

The new derived attribute, pkgDir, is created and displayed in the "Transformation input schema and output actions" editor pane (Figure 17).

The value of the path property for myBookTitle.java is updated with the generated derived attribute parameter (Figure 18).

Larger view of Figure 18.

The transformation author should also provide the ability to generate multiple Java classes.

To enable this, create a new name attribute for the item type the same way that we described before for the projectInfo type. Replace the hard-coded file name with a created attribute for the path parameter of the myBookTitle.java file.

8. Select myBookTitle.java in the "Transformation input schema and output actions" editor pane,
9. Select the BookTitle file name in the path value in the Property view.
10. Right-click the BookTitle file name in the path value in the Properties view.
11. Select the "Replace with Model Reference" context menu item.
12. In the "Replace with Model References" dialog window, select the name attribute that belongs to the item type.
    

As a result, the hard coded path is replaced with a string that contains an XPath expression (Figure 19). This gives flexibility for the transformation user to generate multiple Java classes with different names.

Larger view of Figure 19.

13. Save the created schema.
14. In the editor view in the "Transformation input schema and output actions" pane, right-click the root type and select Update Project.

The JET templates will be updated. The following XPath expression will be added to the main.jet template:

<ws:file path="{$projectInfo/@pkgDir}/{$item/@name}.java" replace="true"
template="templates/item/myBookTitle.java.jet"/>

Edit the templates to customize the transformation output

Up to this point, you were developing the transformation using the JET authoring editor. Now, when the template skeletons are generated, you should fine-tune them to enable generating the content of the transformation output according to your project's requirements.

Here, we will demonstrate how you can use the editing tools provided in the Rational Software Architect tool set.

To assist you with template editing, the tool indicates detected strings within the template that can be replaced with transformation artifacts. The information signs are displayed in the Project Explorer view (Figure 20). When you open the indicated template, the text to be replaced is underscored. When you hover the mouse over the underscored text, a help string with a suggested action is displayed.

Larger view of Figure 20.

1. Select the underscored text.
2. Right-click and select Find/Replace with Model References (Figure 21).
3. In the "Find/Replace with Model References" dialog window, you can select the suggested attribute or any other existing attribute, or you can create a new attribute.
   For this demonstration, we select the suggested highlighted attribute, name, under the item type.
4. Click Replace, and then click Close.

The selected text in the template will be replaced with this JET tag:

<c:get select="$item/@name" />

You can replace any text with the JET tag at this point. In the attached example project's project.jet and main.jet templates (see the Download section), we replaced the hard-coded project name with this XPath expression:

<c:get select="$projectInfo/@name" />

Note:
Information signs in the Project Explorer disappear when all suggested updates are performed and any updated templates are saved.

Back to top

Run the transformation

You created a basic JET transformation, and you are ready to execute it now.

To test the transformation, create a file containing the transformation input. The IBM® Rational® Software Architect for WebSphere® edition provides tools to generate a test input file based on the XSD schema that was generated in the transformation authoring project. Follow these steps to generate the input file:

1. Select File > New > Other > XML > XML File, and then Next.
   Note:
   You may need to select the Show All Wizards check box in the New dialog window to make this option available.
   
2. Confirm enabling the capabilities if a dialog box up requesting that you do so.
3. Select the com.test.my.transform project as a container, enter MyTest.xml as the name, and click Next.
4. Select the Create XML file from an XML schema file radio button, and click Next.
5. Click the Select file from Workspace radio button.
6. From the com.test.my.transform project, select the schema.xsd file, and then click Next.
7. Check all check boxes, and then click Finish.
8. Enter the required data in the generated MyTest.xml file, and then save and close that file.

Figure 22 shows the suggested input file.

The transformation is ready to be executed.

9. In the Project Explorer, right-click the MyTest.xml file, and select Run As from the menu.
10. Select Run Configuration.
11. In the Run Configurations window, double-click JET Transformation.
12. Make sure that the MyTest.xml file is listed as Transformation Input (Figure 23).
13. Click Run.
    

Larger view of Figure 23.

When the transformation runs, the new project called BookLibrary is created. It contains Java files named as specified in the MyTest.xml file (Figure 24).

The Rational Software Architect tool set can be used in a similar way to further elaborate the transformation input schema and output actions.

Back to top

What's next

This article provided step-by-step instructions on how to define a basic transformation based on JET templates. Such a powerful user-defined transformation can simplify the process of asset-based development and can assist in code reuse.

In the next article in this two-part series, we will demonstrate how to use Rational Software Architect tools to generate profiles specific to the target domain of the transformation and how to deploy the transformation into your workspace.

Be sure to check the Resources section for where you can learn more.

Back to top

Download

Information about download methods

Resources

Learn

• Read more about the JET template-based transformation and for an XPath primer, see Strategic Reuse with Asset-Based Development (IBM® Redbooks®, May 2008).
  
  
• Check these relevant developerWorks articles:
  • Create more — better — code in Eclipse with JET (IBM® developerWorks®, August 2006)
  • Create powerful custom tools quickly with Rational Software Architect Version 7.0: Introduction to the Transformation Authoring feature (developerWorks, January 2007)
  
  
• Get more information on JET technology from the Model-to-Text project page on the Eclipse website.
  
  
• Find out more about Rational Software Architect versions:
  • Rational Software Architect Standard Edition:
    • Information Center
    • developerWorks page
    • Version 7.5 release notes
  • Rational Software Architect for WebSphere Software:
    • Information Center
    • developerWorks page
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  • Attend a free developerWorks Live! briefing to get up to speed quickly on IBM products and tools, as well as IT industry trends.
  • Follow developerWorks on Twitter.
  • Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  
  
• Try one of our web-based training courses, which you can take anywhere, any time.
  
  

Get products and technologies

• Download either or both version for a trial:
  • Rational Software Architect Standard Edition
  • Rational Software Architect for WebSphere Software
  
  
• Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
  
  

Discuss

• Join the discussion in the Rational Development Tools forum.
  
  
• Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups such as the Rational Café, and wikis.
  
  

About the authors

Marya Berfeld has been working in software verification on modeling tools with IBM Rational since 2000. She has worked on testing multiple modeling features, and she published an article on UML-to-Java transformations in Rational Software Architect in developerWorks in 2008

Darren Coffin has been working in software verification on modeling tools with IBM Rational since 1999. He has worked extensively on testing a broad number of modeling features and diagrams. He is a graduate of Trent University, with a B.Sc. in Computer Studies and Environmental Resource Studies.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Create and configure the JET transformation project
• Run the transformation
• What's next
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Rational Software Architect
• Buy: Rational Software Architect

Dig deeper into Rational on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers