Introduction to IBM Rational XDE Java Code Model Importer
How to migrate Rational XDE Java Code Model projects from Rational XDE for Java to Rational Software Architect or Rational Systems Developer
The IBM® Rational® XDE Java Code Model Importer (model importer) is a utility provided as part the products IBM® Rational® Software Architect and IBM® Rational® Systems Developer (hereafter referred to collectively as Rational software). This utility lets you migrate Java™ code and the corresponding Java code model from Rational XDE for Java so that you can use the Rational UML and code modeling and transformation capabilities.
The Rational XDE Java Code Model Importer is installed automatically if you select installation of the IBM® Rational®XDE Base Model Importer (XMI) in the IBM Installation Manager. It migrates Rational XDE models, including any custom Unified Modeling Language (UML) profiles that you may have applied to those models. Before running the importer, you will use XMI to import the Java code models and their referenced models to your Rational Software Architect workspace.
About the importer
The following products should be installed on your computer, and you need to be familiar with them:
- Rational Software Architect or Rational Systems Developer with the optional Rational XDE Java Code Model Importer feature installed. Note: Trial versions are available and listed under Related topics.
- Rational XDE for Java
After installing Rational Software Architect or Rational Systems Developer, you must specify this VM (virtual machine) argument:
You can specify this argument in either of two ways:
- By modifying the eclipse.ini file (in the Rational installation directory, the same directory as the eclipse.exe file) and adding the two arguments shown previously under the
-vmargsargument. This modification will apply these VM arguments whenever you run either of these Rational software products.
- By giving the options to the command line when you run this Rational software. For example:
"install directory\eclipse.exe -product com.ibm.rational.rsd.product.ide -vmargs -DXDE_JAVA_PRIMITIVETYPES"
You also need to be familiar with these functions and features:
- How each product reflects Java in UML terms. This knowledge is required to be able to evaluate the outcome of the migration and to verify that it has produced an acceptable outcome.
- How each product works with combinations of UMl models and Java, including understanding the working of "round-trip engineering" (RTE) in Rational XDE and understanding the "model-code theories of operations." This knowledge is required to decide during import whether you want to replace the UML schematic elements in the imported Rational XDE Java code model with visual references to Java source code elements and, thereafter, to practice mixed modeling.
The next section explains the migration process in detail.
The migration path
Take a look at Figure 1, which illustrates the entire migration path, before you read the details of each step:
Figure 1. The migration process
A Java code model project in Rational XDE software can contains two types of artifacts: Java source files and Rational XDE models. The Rational XDE models can be of various types. There can be either zero or one Java code models in the project. Normally, all of the models in the Rational XDE workspace (presumably representing a closure) should be imported to the Rational workspace by using the XMI. Then you can use the model importer to migrate the Java code and the code models during a second step.
The overall migration process can be divided into five major phases. Depending on the size and the complexity of the migration, one or more iterations of this five-step process might be required:
- Preparing the Rational XDE projects (UML models and Java code)
- Importing the UML models
- Importing the Java project (which re-binds the Java code to the imported UML models)
- Running a UML-to-Java transformation in Rational software to finish updating the code in preparation for using the code
Step 1. Planning
There are two primary concerns when planning your Rational XDE to Rational Software Architect or Rational Systems Developer migration:
- Your overall migration strategy. This, along with other considerations, will guide your decision whether to
follow the approach of having your entire team start using Rational software all at once, or the approach of using both Rational XDE and Rational software in parallel during the migration process so that subsets of the team can adopt Rational software incrementally. The latter approach is considerably more challenging. because it involves maintaining parallel development streams, using tricks using model fusing techniques, and performing the actual model migration steps more than once. You need to consider factors such as model sizes and the number of modeling users. These factors will determine how long it will take to complete these tasks:
- Get Rational software installed on all the desktops
- Train all the users on Rational software
- Perform the actual model migration processing
- Whether you will use mixed modeling, architecture reconciliation, or conceptual model-driven development approach as your chosen alternative to Rational XDE round-trip engineering.
Step 2. Preparing the Rational XDE projects (base models and Java code)
Perform the following steps to prepare the Rational XDE base models and the Java project code for the Code Model Import:
- In Rational XDE for Java, synchronize the Java code models so that the UML models (.mdx file) and the Java project are in sync. This is a prerequisite, which you must do before the migration. Important: Do this with the Rational XDE Java preferences set so that the code marker tags are enabled (marker tags are the comments that are created by the Rational XDE code generator that begin with
<@modelguid>and contain the unique identifier of the Rational XDE UML model element that correspond to the Java class).
- Make a backup copy of the Java projects, including the Rational XDE base models corresponding to Java code model.
- Double-check that, on the machines that will process the model imports, the JVM settings are as specified in the Prerequisites section of this article.
Step 3. Importing the UML models
Using Rational XDE Model Importer (XMI), import the Rational XDE UML models. This should include all Rational XDE Java code models, all Rational XDE content models that reference or are referenced by the code models, and the Rational XDE reference models (for example, jdk_min.mdx) referenced by the code models.
Step 4. Importing the Java projects
There are two paths that you can follow when importing the Java projects from Rational XDE:
- By following the first path, you can elect to import the Rational XDE Java projects into the Rational software workspace before invoking the model importer by using the "generic" Eclipse project import wizard: File > General > Existing projects info Workspace. This will import the Rational XDE Java projects (which are Eclipse 1 projects) into Rational software and update them to Eclipse 3 projects. When they are imported in this manner, the projects can be used as the input for the Rational XDE model importer.
- By following the second path, you can import the Rational XDE Java projects into the Rational software workspace as an
onlinepart of the processing performed by the importer. Figure 2 shows the Rational XDE Java project import wizard (the Rational XDE Java Code Model Importer wizard). This is the control that you interact with to specify what you want the model importer to do with your Java code and the Rational software UMl models that were imported from Rational XDE previously, in Step 3. To launch this wizard, select File > Import > Other > Rational XDE Java Projects.
Figure 2. Rational XDE Java Code Model Importer wizard
- Specify the following in the model importer wizard:
- Add the list of Java projects to the Selected projects table and, for each project, add the corresponding Rational UML model that was derived from the project's Rational XDE Java code model. Normally, you will put all of the Java projects in the Rational XDE workspace in this list. You will not include Rational XDE Web projects or Enterprise Java™Beans (EJB) projects, because the model importer does not migrate Rational XDE Web, EJB, or EJB deployment models. In Rational software, though, you work with Web and EJB artifacts directly and do not manipulate them through UML models.
- For each Java project and model pair, specify these options:
- The encoding scheme to be set for the Rational XDE Java project. This can be specified by selecting or typing in the encoding scheme in the Project Encoding box. If the selected Java project is an existing project in the workspace, this combo box is disabled.
- Whether or not the Rational XDE Java project needs to be copied into the Rational workspace. This can be specified by checking the option that says Copy Rational XDE Java projects into workspace. If the selected Java project was previously imported, then this check box is disabled (see the previous discussion about complex projects).
- Whether of not you want to replace the UML semantic elements in the Rational software models that was derived from the Rational XDE Java code model with direct references to the Java elements. By checking this options, you are declaring your intent that for this project you plan to use the "mixed modeling" approach in Rational software, as opposed to using architecture reconciliation or conceptual model driven development.
If you plan to use the second option, import only one project at a time instead of multiple projects. Just follow these steps:
- Check whether you want model importer to automatically delete the imported copies of Rational XDE Java reference models from the Rational workspace after the model importer's processing has concluded.
- Click Finish to start the migration.
Step 5. Running a UML-to-Java transformation on each imported code model
This is an optional step in the process. Perform this step only if you did not tell the model importer to Replace UML elements in the previous step. In other words, during Step 4, you effectively declared your intention not to use mixed modeling and, instead, to use an architecture reconciliation or conceptual model-driven development approach, thereby preserving the code model in Rational software as intact UML semantic models that are used with Rational UML-to-Java (and perhaps Java-to-UML) transformations.
Operations performed during migration
Now that you know the steps for performing the migration, this section will describe the conversion processing that is performed by the Rational XDE Java Code Model Importer to make the code model and Java code compatible with Rational software modeling and transformation components. Some of these operations are performed or bypassed according to the project, depending on whether you selected the option to Replace UML elements with Java elements for the project.
Creation of the mapping model
Performed according to the project: Performed only if the Replace UML Elements with Java Elements option was notselected. The importer also creates a mapping model that captures the existing mapping of UML model elements to Java source files after the migration processing. This mapping model is specified by default in UML-to-Java transformation configuration (the .tc file created as described in the Java transformation configuration subsection, which follows)) to ensure that this mapping is respected and preserved by the transformation.
Replacement of Java framework references to Java visualized types
Performed according to the project: Performed without regard to whether the Replace UML elements with Java elements option was selected. As imported from Rational XDE, the UML model elements that correspond to Java code
elements may contain references to types from JDK (Java™ Developer Kit) libraries. For example, a UML class may have an attribute of type
java.lang.String;. In Rational XDE, most type specifications (parameters, for instance) are plain text, but type specifications defined by UML associations could resolve against the Rational XDE Java reference models, such as jdk_min.mdx. When the Rational XDE code model is migrated to Rational software (using Rational XDE Base Model Importer), the references to the Rational XDE reference model become references to the imported versions of the Rational XDE Java reference models.
However, Rational software maintains its own direct representations of JDK types, and Rational software expects references to Java types to resolve against these. Therefore, the model importer looks at the references to the imported Rational XDE Java reference models and resolves them again, directly against the JDK. Wherever possible, it also re-resolves type specifications that were plain text in Rational XDE. This provides stronger typing rigor (at the UML level) than Rational XDE. It is a step that is necessary to make the imported Rational XDE code models compatible with the Rational Java modeling and with UML-to-Java and Java-to-UML transformations.
Migration of profiles
Performed according to the project: Performed without regard to whether the Replace UML Elements with Java Elements option was selected. The Rational software Java transformation defines and uses its own UML profile, which contains stereotypes that are applied to UML elements to represent various Java constructs. As part of the code model migration process, the importer applies this new profile to the Rational software UML model that resulted when the Rational XDE Java code model was imported with XMI. This makes the model compatible with the Rational software Java transformation components and thereby enables the model to participate in UML-to-Java (forward) and Java-to-UML (reverse) transformations. The stereotypes that are applied in this step supersede stereotypes that were migrated from the original Rational XDE Java code model.
The table that follows lists the stereotype property values that are migrated by the Rational XDE Java Code Model Importer.
Stereotype property values
|This Rational XDE Java RTE profile stereotype property||Is superseded by this Rational software Java 5 transformation stereotype property|
Replacement of UML elements (morph option)
Performed according to the project: This is performed only when Replace UML Elementrs with Java Elements was selected. All of the UML schematic elements in the Rational software UML model are replaced by shortcuts to the corresponding code elements in the Java source files. This leaves the diagrams in the UML model depicting UML-like class shapes that directly represent the Java classes. Double-clicking on these shapes opens the Java class code in the Java code editor. This is consistent with the Rational software mixed-modeling approach. The effect is the same as if you had composed a new model and then applied the UML-to-Java transformation to that model by using the Replace UMl Elements option.
You can subsequently add new UML semantic elements to the model and again apply the UML-to-Java transformation with the Replace UML Elements option to also convert the new elements into direct Java references. This means that you can practice mixed modeling in an iterative development process.
Performed according to the project: Performed only when Replace UML Elements with Java Elements was not selected. The code elements in the Java source files are tagged by model importer as
<@generated> if an equivalent UML element in the model exists. Model precisely, model importer will search
<@modelguid> tags in the imported code. Such tags will be present by virtue of having been generated by Rational XDE. This is why one of the preparation steps before running the model importer is to make sure that the Rational XDE preferences are set to generate these tags and then to synchronize the Rational XDE code model
- Any code elements that, for any reason, are not tagged with
<@generated>markers during this step will not be modified (deleted or overwritten) by subsequent application of the UML-to-Java (forward) transformation. For instance, if you delete or rename the model element in Rational software (the UML class) that corresponds to a Java class that does not have the tag, and you then run the Rational UML-to-Java transformation, the class will not be modified. To change this behavior, you can manually add the
<@generated>tag to the comments of the Java class in the source file. Thereafter, changes made to the UML class in the model will be applied to the Java class in the source code. See the documentation of the UML-to-Java (forward) transformation component for more details.
- To tag the Java files, the Rational XDE Java Code Model Importer searches for
<@modelguid>tags that are present as part of the Javadoc comments. Make sure that the
<@modelguid>tag is present as Javadoc comments in the source files. You can verify this by synchronizing the Java code model in Rational XDE before starting the migration.
Creation of the Java transformation configuration file
Performed according to the project: This is performed only when Replace UML elements with Java elements was not selected. At the end of the migration, the Rational XDE importer will create a Java 5 transformation configuration (TC) file with a specific set of parameter values (such as the source model, target Java project, and so on). Use this TC file without modifications to run the UML-to-Java transformation one time on the migrated model, immediately after model importer has completed the import. This will clean up residual differences in the way that Rational XDE represented Java elements compared to how Rational Software Architect or Rational Systems Developer represent them.
- The new IBM Rational design and construction products for Rose and Rational XDE users, an IBM developerWorks article by Bill Smith (Dec 2005)
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products. In particular, visit the Rational Software Architect area.
- Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
- In the Pattern Solutions area on developerWorks, get the resources you need to advance your skills in patterns-based development.
- Evaluate IBM Rational Software Architect V7.0 online by taking this three-hour test drive without installing or configuring it on your own system. This advanced model-driven development and static analysis tool is ideal for software architects and developers who are creating service-oriented architecture (SOA), Java™ Platform, Enterprise Edition (J2EE), and portal applications.
- Try IBM Rational Systems Developer V7.0. The evaluation period for this trial is 30 days. All of the product's features are enabled.
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.