Customizing and Automating Rational XDE Developer - Java Platform Edition

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Introductory

Steven Franklin, Software Design and Process Specialist, Software Design and Process Specialist

11 Feb 2004

Part 1: The Rational XDE Extensibility (RXE) API

Editor's note

On June 5, 2006 IBM announced the withdrawal of the Rational Rose XDE product family listed below. The Rational XDE components are being withdrawn from the market; however, the Rational Rose components will continue to be supported and will be re-packaged into a new set of offerings.

For more comprehensive information on the product migrations with the IBM Rational June 2006 product release plans, please visit: http://www.ibm.com/software/rational/support/migrations/

In earlier article series, I covered IBM^® Rational^® XDE™ Developer -- Java™ Platform Edition to a reasonable level of detail; however, the customization and automation capabilities of Rational XDE Developer v2003 (known in earlier versions as Rational XDE Professional, or simply Rational XDE) require more attention. This article is the first of a three-part series covering the basics of Rational XDE Developer customization and automation, including the Rational XDE Extensibility (RXE) API, code templates, and pattern templates. By clarifying the issues and techniques associated with these capabilities, this series should give you some ideas about how Rational XDE Developer can help increase your productivity. In this article I'll begin with an overview and then focus on RXE, which enables templates as well as stand-alone applications to query and modify models. I'll illustrate the customization capabilities with some simple examples.

I'm assuming Java developers will want to customize Rational XDE Developer using either the Java language or the integrated JavaScript™ support. Although JavaScript is completely different from the Java language, it's sometimes handy to embed a quick JavaScript snippet into Rational XDE Developer.

Here's an outline of the entire series:

• Part 1: introduction to extending Rational XDE Developer using RXE, code templates, and pattern templates, with a focus on RXE
• Part 2: applying RXE to a sample project
• Part 3: using code templates and patterns templates on a project

Note that none of the sample code included with the articles in this series is in any way production-ready; it's only intended to show you the basics and has not been tested to any extent. Consider the sample code to be just one developer's perspective and not a replacement for IBM's Help and reference material. The capabilities being demonstrated continue to evolve, so it's important to stay abreast of fixes, improvements, and changes.

Because this article series is targeted at developers using the Java platform edition of Rational XDE Developer, I spend very little time on the Windows environments: Visual Basic, Visual Basic for Applications (VBA), Visual C++, .NET, and so on. I plan to address these more specifically in future articles.

Extending Rational XDE Developer

Rational XDE Developer v2003 -- Java Platform Edition puts more power in the hands of the user by providing greater accessibility through multiple interfaces. This enables you to tailor and automate your use of Rational XDE Developer to speed up production and better meet your project's needs. It also gives you more control over how Rational XDE Developer fits into your projects and processes. You can build in additional features (for example, tools to enforce specific coding standards), making them easily accessible to all team members.

Keep in mind that customization and automation can be overdone. It's tempting (and often fun) to spend 10 hours customizing Rational XDE Developer to save 10 seconds on a task that you do a few times a week. However, when done properly, tailoring Rational XDE Developer can offer significant time savings.

The three main ways to extend Rational XDE Developer are to:

• Develop dynamic code templates that use model information (accessed via the RXE API) as part of their logic. This is useful for replacing repetitive coding tasks.
• Develop pattern templates to extend the standard pattern capabilities with pattern callouts that can be executed at key trigger points in the pattern application process. Design and coding tasks can be automated in this way. As with code templates, model information can be accessed via RXE.
• Develop programs to run externally that similarly access model information.

As shown in Figure 1, these three customization mechanisms are accessible via JavaScript, Java, and (because Rational XDE Developer's functionality is exposed through a Microsoft^® COM model) any COM-aware language, including Visual Basic, Visual C++, and .NET languages.

Figure 1: Customization mechanisms in Rational XDE Developer

Figure 1 oversimplifies the tiers involved in customizing Rational XDE Developer; the architecture is actually much more open and complicated. For one thing, the underlying API in the bottom tier separates into three APIs that are all shown at the same level in the top tier, but (as noted earlier) code and pattern templates can call the RXE API to access model information. Because RXE is the heart of Rational XDE Developer's customization and automation capabilities, I'll focus on it in this introductory article.

RXE

To understand the roots of RXE, it's useful to look at some of the history of IBM Rational Rose^®. For years, starting long before the existence of Rational XDE Developer, Rational Rose has provided strong extensibility features through its Rose Extensibility Interface (REI). REI provides developers with a means of automating Rational Rose, navigating models, generating results based on models, exporting diagrams, and more. Users can tie Rational Rose in with other COM-aware applications via BasicScript code. BasicScript provides an integrated VBA engine that can talk to other COM servers or access the Rational Rose COM interface directly; in this way, Rational Rose model information can be exported to other types of files, including Excel, Word, Outlook, and XML. Data can also be pulled from external sources in a similar fashion.

The RXE API in Rational XDE Developer is conceptually similar to REI, but the RXE architecture offers more languages, more ways to plug in functionality, and, in my opinion, a superior object model for the API. Figure 1 compares REI to RXE, with the key feature being the support for multiple languages in Rational XDE Developer, including JavaScript, Java, and any COM-aware language.

Figure 2: Rational Rose's REI compared to Rational XDE Developer's RXE

If you migrate from REI in Rational Rose to RXE in Rational XDE Developer, you may get to reuse some ideas, but your scripts will largely have to be rewritten because of differences in the RXE design. I'll discuss migration from REI to RXE later in this article.

The RXE API enables you to write applications, as well as code templates and pattern templates, that access Rational XDE Developer models, packages, modeling elements, descriptions, attributes, and more. In Rational XDE Developer v2003, the RXE API is read-only and not write-enabled, so if you need to manipulate the model as part of the logic, your only option (at present) is to use the Rational XDE Developer SDK (XDK). XDK is an undocumented and unsupported API that provides writeable access, but it could leave you vulnerable to changes in future builds or bugs in untested code not intended to be used by general users. I'll discuss this issue in more detail in Part 3.

Code Templates

Standard code templates in Rational XDE Developer (and in Eclipse, the open source IDE framework on which Rational XDE Developer for the Java platform is built) only allow insertion of static snippets of code; however, the Rational XDE Developer code templates discussed in this article allow for dynamic generation of code. For example, with a standard template like the following, you can insert a static for loop into your code:

for (int i=0; i < 10; i++) {
...
}

But with a dynamic Rational XDE Developer code template, you can create a for loop based on a variable name and upper limit supplied as arguments, like this:

for (int myVar=0; myVar < upperBound; myVar++) {
...
}

Code templates can be applied to methods within Java classes, whereas pattern templates apply at the class or framework level, for when you need more capability.

Pattern Templates

Pattern templates let you do more than inject dynamic snippets of code; they let you define dynamic, reusable patterns that can either be applied to existing classes or generate new classes.

Rational XDE Developer includes the existing Gang of Four (GoF) patterns and also lets you create your own patterns. You can do more than create static UML patterns; you can define intelligent behavior that determines how patterns are applied.

Interestingly, pattern templates and code templates can be used together. You can generate or modify classes in your model and bind code templates to various methods to generate some of the content. For example, you might have an in-house debugging approach that requires applying patterns to all core business logic classes. You could also use code templates to automatically generate some of the class state information, exception handling, and debugging output. Patterns can have code templates embedded within them, which avoids the need to separately bind code templates to various methods that have been created from pattern templates.

Back to top

More About RXE

In this section I'll expand on the earlier introduction to RXE, looking at its object model representation and language support, its place in Rational XDE Developer's basic architecture, and some issues related to migrating from REI to RXE. After this background we'll be ready to explore actually using RXE.

The Object Model in RXE

RXE doesn't support all UML objects, but it makes up for that by having both generic and specific objects. IRXEElement is a generic representation of all accessible Rational XDE Developer model elements, to be used if you're better off working with a generic representation of a model element or if the element type isn't supported by RXE. Although working with IRXEElement objects is adequate, you'll often have access to more functionality if you deal with a specific element type, such as IRXEClass. Later (in Part 3), I'll discuss the mechanism for moving between generic and specific element representations.

There are six types of RXE object: administrative, code templates, collections, elements, patterns, and relationships. These terms reflect the relationship of the objects to one another or to pattern or code templates. Figure 3 shows the basic Rational XDE Developer object model representation as presented by RXE, and Table 1 briefly describes the classes in the figure. There's actually much more interaction between the classes than what's shown; for example, almost all classes in the RXE design have access to the IRXEApplication owner.

Figure 3: High-level summary of the RXE object model

Although the object model in RXE may seem complex at first, notice that many of the objects are similar in that they own one or more containers of other objects -- for example, classes contained in a package, or methods or attributes contained in a class. Expanding on what's summarized above, suppose you want to find out the attributes within a class; if you look at IRXEClass, you will (unsurprisingly) find that the appropriate class is IRXEAttributes, which contains zero or more IRXEAttribute objects. Given this consistency within the object model, it becomes very efficient to navigate your Rational XDE Developer model.

In addition to the RXE classes shown in Figure 3, RXE provides administrative functionality in classes such as IRXEUtil. It also has a set of classes that capture relationships; classes like IRXERelationships or IRXEDependencies represent relationships between model elements, letting you navigate both ends of a relationship, determine the type of relationship, and obtain other information.

Incidentally, the RXE object model in the .NET edition of Rational XDE Developer looks similar to the one in the Java platform edition, but the two models sometimes diverge. For example, .NET will expose a container as a parameter, whereas the Java API will expose the container through a get method.

RXE Language Support

As mentioned earlier, RXE can be accessed by COM-aware languages, including Visual Basic 6.0, VBA, Visual C++ 6.0, and .NET assemblies. Rational XDE Developer extensions written in the Java language can access RXE if they include the appropriate *.jar files (as we'll see later). This is possible because the RXE JAR files provide a wrapper around the COM interface. (Normally, Java applications need to take extra steps to make COM calls.) RXE classes and methods can also be accessed via JavaScript scripts used in patterns and code templates.

RXE in Rational XDE Developer's Architecture

Figure 4 shows where the RXE API fits into the basic architecture of Rational XDE Developer for the Java platform. Above the underlying OS and JRE (Java Runtime Environment) lies the open-source IDE framework Eclipse; Rational XDE Developer and many of its enhancements are built on top of Eclipse. RXE exposes the Rational XDE Developer functionality, making it available to external RXE-aware applications as well as to code and pattern templates within Rational XDE Developer. In addition, there's a large community of developers who create Eclipse add-ins, a separate level of customization enabling further tailoring of the environment; however, there is the potential danger that these could break the Rational XDE Developer environment (by changing Eclipse features that it depends on).

Figure 4: The Rational XDE Developer extensibility architecture

Migrating from REI to RXE

If you have existing REI scripts that you want to migrate to RXE, I believe your best approach is simply to redesign and rewrite them (especially for short scripts, in which case the effort will be minimal). If your team is primarily used to writing Java code, that's the preferred way to access RXE; you'll have a better and more maintainable system in the end. Although REI's BasicScript interface is adequate, I prefer to write Java classes that call RXE because it enables me to take advantage of Rational XDE Developer's full Java environment.

Differences in functionality between the REI and RXE APIs are inevitable. For example, I find that REI integrates more smoothly with the Rational Rose GUI than RXE integrates with the Rational XDE Developer GUI. REI provides significant ways for you to manipulate and query the state of the user interface. In the RXE object model, IRXEUtil provides some access to the Rational XDE Developer GUI, and you may find all the capability you need within that class. Furthermore, many things that require REI development in Rational Rose can now be accomplished directly within Rational XDE Developer (using pattern templates, for example).

Back to top

Using RXE

We'll now look at how to go about using the RXE API, with simple sample code illustrating both an internal and an external JavaScript code template, a Java code template, and a stand-alone Java application. (Sample pattern templates aren't trivial and so will be addressed separately in this series, in Part 3.) I'll walk through the straightforward way the RXE API is called from each of these contexts, as summarized in Table 2.

Object Model Documentation

To help you get started using the RXE API in the Java platform edition of Rational XDE Developer, the RXE object model is documented in the Help with an API reference shown as Javadoc™ output (Figure 5).

Figure 5: Javadoc reference for Java RXE API

(click here to enlarge)

A Sample Internal JavaScript Code Template

For the first example, I'll create a very simple JavaScript code template.

An internal JavaScript code template is probably the simplest type of code template. You write the JavaScript code within Rational XDE Developer and then bind the template to a method, essentially assigning dynamic code generation to the method. You start by right-clicking the method and clicking Code Templates > Bind in the context menu. A blank Bind Code Template dialog box is displayed, in which you click the New button to start up the New Code Template wizard. Figure 6 shows the first page displayed by the wizard, where you enter a name and description for the new code template.

Figure 6: Naming and describing a new code template

Entering the JavaScript Code

The next page (Figure 7) lets you enter the code template's functionality. You can supply parameters such as variable names, dates, and counters to the template. Because this is a very simple example, no parameters need to be defined. For an internal JavaScript code template, the Body Kind value is Scripted Template and the only language supported is JavaScript.

Figure 7: Creating a scripted code template

The JavaScript code resides within the <%...%> tags, unless you want to write out some data, in which case the output data goes within <%=...%> tags. The JavaScript code in Figure 7 (also shown in Listing 1) generates a Java statement that provides the current date in the following format:

String buildDate = 2003-07-23 16:30;

The idea here is to run this whenever the code and model are synchronized, as a way of indicating the last time synchronization took place.

<%
var currentDate = new Date();
var minute  = currentDate.getMinutes();
var hour    = currentDate.getHours();
var day     = currentDate.getDate();
var month   = currentDate.getMonth(); 
var year    = currentDate.getFullYear(); 
var dateString = year + "-" + month + "-" + day + " " + hour + ":" + minute;
ctData.appendExpandedString("String buildDate = \"" + dateString + "\";");
%>

There are a few key issues to note about JavaScript code for templates:

• Standard JavaScript syntax is used. If the syntax is not valid (for example, if it doesn't follow proper semicolon usage), the code will not be valid.
• Code templates generally write code. In our example, the ctData.appendExpandedString method accomplishes this.
• The code template must generate valid Java code, or your affected classes will not compile.

You may be wondering about the ctData.appendExpandedString call. The ctData object, which is of type IRXECTCallOutData, manages the exchange of data to and from the customization code. If you find the ctData approach cumbersome, Listing 2 shows another approach you can take: the code that generates the Java statement is within <%=...%> tags, meaning that the results will be written to the target Java code. A string is built up within these tags.

<%
var currentDate = new Date();
var minute  = currentDate.getMinutes();
var hour    = currentDate.getHours();
var day     = currentDate.getDate();
var month   = currentDate.getMonth(); 
var year    = currentDate.getFullYear(); 
var dateString = year + "-" + month + "-" + day + " " + hour + ":" + minute;
%>
<%= "String buildDate = \"" + dateString + "\";" %>

Since any text outside <%...%> or <%=...%> tags will be generated, another possible approach is to enclose only the JavaScript variables or operations within the <%=...%> tags, which would change the last line in Listing 2 to this:

In my opinion, the approach shown in Listing 1 is the easiest. It avoids messy use of brackets, simplifies formatting, and is generally cleaner. For instance, it avoids formatting like that in Listing 3 in favor of what's shown in Listing 4; I prefer the latter because I find it easier to read and maintain and less likely to have mismatched brackets.

<%
for (int i=0; i<10; i++) {
%>
   int var<%=i%>=<%=i%>;
<%
}
%>

<%
for (int i=0; i<10; i++) {
   ctData.appendExpandedString("int var" + i + "=" + i + ";");
}
%>

Binding the Code Template

Once you enter the code and click Finish, you're back at the Bind Code Template dialog box (Figure 8) and ready to bind the template to the method you originally selected. Note the two check boxes:

• If you select Replace Existing Code Body, no code will remain in the method except for what's written by the code template.
• If you select One Time Expansion, the code template will be executed (that is, its body "expanded") only the first time the code is generated or when the method body is empty. This is useful if you just want to generate code as a starting point but you expect to modify it beyond what the code template provided.

When you click the Bind button, the code template is bound to the method you selected.

Figure 8: Binding the scripted code template

Editing the Binding

If you later want to update or just review the code template binding for a method, you can right-click the method and click Code Templates > Edit Binding (Figure 9). Originally only the Bind option was available in the Code Templates submenu, but now that we've bound a code template to the method, we can update the binding using the context menu. (We can also remove it, using Unbind.)

Figure 9: The Edit Binding command

When editing the JavaScript code template binding (as shown in Figure 10), you can update its name, description, or code. Another useful feature is the Expand button (which wasn't available when we originally created the template in Figure 7); this button lets you see the results of the JavaScript code.

Figure 10: Editing a code template binding

A Sample External JavaScript Code Template

There may be times when you would prefer to write your JavaScript code in an external *.js file rather than in a Rational XDE Developer text box as in the preceding example. For complex scripts, an external editor may provide better display and formatting of the JavaScript code.

Figure 11 shows the creation of a code template that refers to an external JavaScript file. The Body Kind is set to External JavaScript and the path to the JavaScript file is specified.

Figure 11: Creating an external JavaScript code template

So far, I've encountered two differences between external and internal JavaScript code:

• External JavaScript files do not require <%...%> tags.
• External JavaScript files must use the ctData object to receive parameters and user data and to return text.

Listing 5 shows the JavaScript code stored in the file referred to in Figure 11, GetCurrentDate.js.

var currentDate = new Date();
var minute  = currentDate.getMinutes();
var hour    = currentDate.getHours();
var day     = currentDate.getDate();
var month   = currentDate.getMonth(); 
var year    = currentDate.getFullYear(); 
var dateString = year + "-" + month + "-" + day + " " + hour + ":" + minute;
ctData.appendExpandedString("String buildDate = \"" + dateString + "\";\n");

A Sample Java Code Template

When writing a Java code template, you must set the body kind to Java (Figure 12). Furthermore, the classpath must be valid, and the class name must point to the class that contains the code template.

Figure 12: Creating a Java code template

To set the classpath, I browse to the root of my Java package hierarchy. Although hidden by the drop-down list in Figure 12, there is a browse button (labeled "?") that lets you navigate to your project root or wherever your *.class or *.jar file containing your code template resides (Figure 13).

Figure 13: Updating the classpath

Here are some general guidelines for creating a Java code template:

• Start by doing a basic design if you plan to build anything more than a trivial code template.
• For very simple code templates, an internal JavaScript template may be the quickest route.
• Implement the IRXECodeTemplatesExpansion interface. Import the com.rational.xde.pcc.rxe.interfaces.* hierarchy to obtain this interface.
• Consider breaking out complex logic into private methods so that the Exec method doesn't become too lengthy. (I don't practice this good coding habit in the following example, to keep it simple and short.)

Listing 6 is a Java code sample that implements the date generation functionality shown in the previous JavaScript samples.

package com.rational.codedemo; import com.rational.rxe.*; import com.rational.xde.pcc.rxe.interfaces.*; import java.util.Date; import java.text.DateFormat; import java.text.SimpleDateFormat; public class DateGenerator implements IRXECodeTemplatesExpansion { public DateGenerator() { } public void Exec (IRXECodeTemplatesExpansionData data) throws java.io.IOException { DateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm"); String dateString = formatter.format(new Date()) + " "; Date currentDate = new Date(); String result = "String buildDate = \"" + formatter.format(currentDate) + "\";"; data.appendExpandedString(result); } }

Listing 6: Sample Java code template for date generation

In Listing 6, data output is accomplished with the data.appendExpandedString(result) call. The data variable is an object of type IRXECodeTemplatesExpansionData. You can integrate standard Java functionality into this code as you see fit, as long as you adhere to the requirements of the IRXECodeTemplatesExpansion interface.

You bind the Java code template using the Bind button as shown earlier in Figure 12, and you can later edit the binding (again, by right-clicking the method and clicking Code Templates > Edit Binding). I usually use the Edit Code Template Binding dialog box (Figure 14) as a way of debugging the Java code template, and then click the Expand button.

Figure 14: Editing a Java code template binding

A Sample Java Application

To write a stand-alone Java application, click Run > External Tools. You can run the application from the command line or a batch script or launch it as an external tool.

The code shown in Listing 7 is for a basic Java application; it creates an instance of Rational XDE Developer that loads just the minimum functionality required to manage the model. The new instance only has access to the model as saved to disk. If an existing Rational XDE Developer session makes changes to the model without saving them, the external Java application will not be aware of the changes.

package com.rational.codedemo;
import com.rational.rxe.*;
import java.io.IOException;

public class JavaRXEDemo {
   public JavaRXEDemo() {   }

   public static void main(java.lang.String\[\] args) {
      JavaRXEDemo walker = new JavaRXEDemo();
      String modelName = 
         "D:\\Documents\\XDE Workspace\\RXE Demo\\Java 1.4 Code Model.mdx";
      walker.run(modelName);
   }

   public void run(String modelName) {
      try {
         IRXEApplication app = new RXEApplication();
         app.startReadAction("");
         IRXEModel model = app.openModel(modelName);
         System.out.println("Model name: " + model.getName());
         System.out.println("Model path: " + model.getPath());
         app.completeAction();
      } catch (Exception e) {
         System.err.println("Error: Unable to attach to XDE process.");
         System.err.println("Message: " + e.getMessage()); 
      }
   }
}

To access the RXE classes, a Java application has to import the com.rational.rxe.* hierarchy. Note that all model querying must take place between these statements:

app.startReadAction("");
...
app.completeAction();

Actions must be in either the read state or the write state before you can query or manipulate the model. You can query the application to see if a read or write action is already underway, but actions cannot be nested.

To run the application from the command line, you need to point to rational\xde\xdepkg\rxe.jar and rational\common\rjcb.jar in your classpath. (I assume rjcb.jar is the Java/COM bridge, which enables Java code to call RXE's COM interface.) The command line for the sample code in Listing 7 is as follows:

set CLASSPATH=
.;d:\progra~1\rational\xde\xdepkg\rxe.jar;d:\progra~1\rational\common\rjcb.jar java
com.rational.codedemo.JavaRXEDemo

The resulting output for the sample code is

Model name: RXE Demonstration
Model path: D:\Documents\XDE Workspace\RXE Demo\Java 1.4 Code Model.mdx

To run the application from within Rational XDE Developer, you must add the two JAR files to your project. Right-click the project in the Navigator and click Properties; in the Properties dialog box (Figure 15), select Java Build Path on the left and update the Libraries page on the right.

Figure 15: Setting the Java build path

(click here to enlarge)

The application can then be configured and run by the application launcher (Figures 16 and 17).

Figure 16: Running an application

Figure 17: Updating an application launch configuration

(click here to enlarge)

After the application is run within Rational XDE Developer, the console window displays the same output as shown earlier, when the application was run from the command line.

Back to top

Summary

In this article, I've briefly introduced RXE, code templates, and pattern templates, with a focus on using RXE for querying and manipulating models. I hope this introduction and the simple examples I've provided have given you some insight into the customization and automation capabilities within Rational XDE Developer.

In Part 2, I'll walk through a more detailed example that uses RXE so that you can even better see its usefulness. I'll create an XML/HTML export facility that generates a summary of portions of a Rational XDE Developer model. Although by no means competitive with the reporting features built into Rational XDE Developer v2003, this facility might be a useful starting point for your own reporting, interfacing, or export requirements.

About the author

		Steven Franklin has an extensive background in software design, architecture, and engineering process, which he usually applies to large, distributed information management and command and control systems. He's been using Rational tools since 1997, and his primary areas of interest include XML, J2EE, wireless, and software engineering methodologies. Steven can be reached via e-mail.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top