Configuring Java-to-UML transformations

To specify the information that the transformation uses to generate the output that you expect, you use the New Transformation Configuration wizard and the transformation configuration editor, which guide you through the configuration.

About this task

A transformation configuration has .tc as a file name extension, and contains the information that the transformation uses to generate the output that you expect. A transformation configuration also contains information that is specific to a particular type of transformation. To edit an existing transformation configuration, in a view that shows the workspace resources, double-click a transformation configuration file, which opens the transformation configuration editor.

To simplify working with the transformation configuration file, save the configuration file in the project that contains the elements to transform.

Procedure

Depending on the view that you are working in, complete one of the following steps:
- In the Pattern Explorer view, right-click a transformation; then click New Configuration.
- In other views, click File > New > Transformation Configuration. If Transformation Configuration is not a menu item, click File > New > Other > Transformations > Transformation Configuration.
Specify the details of the configuration. In the New Transformation Configuration wizard, on the Specify a Configuration Name and Transformation page, complete the following steps:
1. In the Name field, specify a name for the configuration.
2. In the Configuration file destination field, specify the destination for the transformation configuration file. The destination is a relative path in your current workspace. You can specify a fully qualified project name or folder name. If you specify a folder in a project, you must prefix the folder name with a forward slash (/).
3. From the Transformation list, select a transformation.
  Note: To display the transformations that are installed, but not enabled, click Show all transformations. A transformation must be bound to a capability to be displayed in this list.
In the Protocol section, specify the modeling protocol, which is also called the design contract management protocol (DCMP). The value that you select determines whether to synchronize the source and target of the transformation.
- If the source model is the primary engineering artifact, select Conceptual. Any changes to the source model are propagated to the target model.
- If the architecture that the source artifacts represent evolves independently from the target, select Reconciled. Selecting this option enables the reverse transformation, which you can use to compare the source and target, and to reconcile changes. You might also select this option if different teams implement, develop, or maintain the architecture.
  Note: When you select this option, additional properties become available in the "Reverse transformation" section of the Main page. For some transformations, additional options or pages become available in the transformation configuration editor. For information about configuring the reverse transformation, see the related link below.
Click Next.
Specify the source and target elements for the transformation. For a list of valid source and target elements, see the related concept topic for this transformation. On the Source and Target page, complete the following steps:
1. In the Selected source pane, select the source element for the transformation to transform.
2. In the Selected target pane, select the destination of the transformation output. To create a new destination for the output, click Create Target Container.
Click Finish. The transformation configuration editor opens, and the contents of the configuration are displayed.
Optional: Specify values for the code generation properties that are unique to this transformation. On the Main page, complete one or more of the following steps:
- To transform Java™ getter and setter methods into UML operations, select the Generate UML operations for each Java getter and setter method. If you do not want to display the UML operations for Java getters and setters in the target UML model when you run the transformation, do not select this check box.
  This option modifies the same transformation property as the Generate getter and setter methods option in the reverse transformation. If you select one of the check boxes, it is equivalent to clearing the other. Clear this check box if you want to generate Java getters and setters when you run the reverse transformation, but you do not want to display the UML operations for Java getters and setters in the target UML model when you run the forward transformation.
- To generate a flat UML package structure in the target UML model for each Java package in the source Java project, select the Generate a flat UML package for each Java package check box. If you do not select this check box, the transformation generates a hierarchical packages structure.
  If the transformation target is an existing UML model, you should specify the same package structure as the target model; this reduces the number of differences that you must resolve between the target model and the temporary model that the transformation generates.
  
  For example, assume that a source Java project contains the classes a.b.Y and a.b.c.Z. If you select the check box, the transformation generates UML packages a.b and a.b.c. These packages are not hierarchical. UML class Y is created in UML package a.b, and UML class Z is created in UML package a.b.c. If you clear the check box, UML package a is created; UML package b is created in package a; UML package c is created in package b; UML class Z is created in package c; and UML class Y is created in package b.
- To generate UML associations for UML attributes for Java fields, select the Generate a UML association for each Java field check box. The transformation examines the target UML model and creates association relationships for Java fields that are part of an association relationship. If a Java field is not part of a UML association, the transformation creates a UML attribute. To also show visualized types and primitive type as directed associations, select the corresponding check boxes.
Optional: To generate debugging information, on the Main page, select the Generate a debug log check box. The next time that you run the transformation, the log file is generated as an XML file in the folder that you specify in the transformation preferences. If you do not specify a location for the log files, the transformation generates the log file in the .metadata folder in your workspace.
Tip: To set preferences for transformations, click Window > Preferences; then expand Modeling and click Transformations.

The log file provides information about the source elements, the target elements, and the rules that the transformation applies to transform the source elements. If the transformation transforms many elements, you might experience decreased performance while the transformation generates the log file; therefore, you should only generate a log file for debugging purposes.
Optional: To prevent new dialog boxes from opening while a transformation runs, on the Main page, select the Run the forward transformation silently check box.
Running a transformation in silent mode suppresses all dialog boxes that the transformation generates. The transformation applies default rules and behavior, which might generate unexpected or incorrect transformation output. You should only run a transformation in silent mode to validate that the transformation runs, instead of validating the transformation output. For example, you might run a transformation in silent mode as part of an automated task or automated test suite.

Setting the transformation to run in silent mode overrides the file-overwrite options that you specify, and overwrites files if necessary.

If the UML-to-Java transformation is available, you can select the Run the reverse transformation silently check box. Specifying that the UML-to-Java, or reverse transformation runs in silent mode overrides the file overwrite options that you specify in the transformation configuration. The UML-to-Java transformation overwrites files if necessary.
Optional: To create a traceable relationship between the transformation source and target, on the Main page, select the Create trace relationships check box. This check box is enabled only if you select the Mixed Modeling or Reconciled Modeling protocols.
You can use trace relationships and the visual development tools to understand the relationships between source model elements and transformation output. This function is useful in large projects that might contain multiple models and transformation configurations. The transformation does not alter the source model.
Optional: Specify documentation about the transformation configuration. This field is useful for communicating information about a configuration that multiple users share. On the Main page, in the Documentation field, specify additional information about the transformation configuration.
Optional: Specify the transformation extensions to enable or disable.
- On the Extensions page, select or clear the check boxes for the transformation extensions to enable or disable.
  To generate UML enumerations that preserve the name and values of the enumeration literals, select the com.ibm.xtools.transform.java.enumext.j2u.transform check box. The properties of the custom Java enumeration are preserved when it transforms into UML.
Optional: Specify how the transformation transforms the selected Java collection types from the source Java project into UML collection types.
- On the Collections page, from each UML collection type list, select a Java collection type. To specify a custom value, type the value in the collection field.
  For each Java collection type in the source project, you can specify the UML collection type that the transformation generates. You can map one Java collection type to one UML collection type. The default selections map the Java Collection, SortedSet, List, and Set classes to the UML Bag, OrderedSet, Sequence, and Set collection types. When you run the transformation, if it can identify Java collections or arrays in the code, and identify the type of the collections or arrays, the transformation applies the «JavaCollection» or the «JavaArray» stereotype to the generated UML element and populates the values of the stereotype properties. Otherwise, the transformation generates an adaptable reference and does not apply a stereotype to the generated UML element.
  
  For example, to transform Java vector classes into UML sequences, select java.util.Vector from the Sequence list instead of the Java List classes. For each Java List class in the source Java project, the transformation generates an adaptable reference in the target UML model and sets the Is Ordered and Is Unique properties of the generated UML element to false. In this example, the transformation sets these properties to false because it does not transform the Java List collection type into a UML collection type.
  
  See the related reference topic below for more information about how the transformation populates UML collection properties when it transforms Java collections.
Optional: To create a file that defines the interdependencies of Java elements and target UML elements, create a Java-to-UML association file. This functionality is useful for defining relationships between Java and UML elements whose scope is outside the transformation that you configure, and that might be located in different projects. To create an association file, on the Java-to-UML Associations page, complete the following steps:
1. In the Java-to-UML association file name field, specify a file name.
2. In the Java-to-UML Associations section, beside the table, click the buttons to add or remove an association from the file.
For more information about support for multiple projects and their interdependencies, see the related Java-to-UML transformation concept topic below.
Optional: If you enable the Reconciled Modeling DCMP, on the Mapping page, you can select and configure mapping models that you created for other reverse transformations. By using mapping models, you can specify alternate files names for output that the UML-to-Java transformation generates. The mapping model that you specify must exist in the current workspace.
The Java-to-UML transformation uses the mapping models to determine the appropriate name for the UML elements that it generates. For example, a UML model contains PackageA, and PackageA contains Class1. When you create a mapping model for the UML-to-Java transformation, you can specify that Class1 has an alternate file name of MappedClass1. When you run the UML-to-Java transformation, it generates Java files named PackageA.MappedClass1.java. When you run the Java-to-UML transformation, the transformation determines that the original UML path for the Java element is PackageA.Class1, and generates a UML class named Class1 in a UML package named PackageA.

If the artifact file name that you specify in the mapping model is not a valid Java file name, then the transformation modifies the name of the file when it creates the Java code element. For example, if the mapping model specifies an alternate file name of "Mapped Class1", instead of MappedClass1, the transformation generates a Java file named Mapped_Class1.java. The transformation does not keep a record of these modifications; therefore, the Java-to-UML transformation cannot map the Mapped_Class1 file to the original UML element. In this example, the Java-to-UML transformation transforms the Mapped_Class1 Java source object into a UML class named Mapped_Class1, instead of Class1.
Click File > Save.

Results

The options are applied the next time that you run the transformation.

Feedback