Configuring UML-to-Java 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.


  1. 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.
  2. 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.
  3. 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 target model is the primary engineering artifact, click Mixed. The transformation converts the source artifacts to visual representations that are directly connected to the target artifact. Select this option to work in the target domain instead of with the source model, or to retain the artifacts for analysis. The transformation output becomes the primary engineering artifact.
    • 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.
  4. Click Next.
  5. 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.
  6. Click Finish. The transformation configuration editor opens, and the contents of the configuration are displayed.
  7. Optional: Specify the code generation properties that are unique to the UML-to-Java transformation. On the Main page, complete one or more of the following steps:
    • To generate getter and setter methods in the transformation output, select the Generate getter and setter methods check box. Whether the transformation generates a setter method for a UML property depends on specific values of the property in the source model.
      You can check the values of the UML property in the Properties view:
      • On the General page, if you select the property's Leaf or Read Only check box, no setter is generated. If you select the property's Derived check box, the setter implementation is empty.
      • On the Advanced page, if you set the property's Is Leaf or Is Read Only value to true, no setter is generated. If you set the property's Is Derived value to true, the setter implementation is empty.
    • To generate code that is compatible with Java™ 2 Platform, Standard Edition (J2SE) 5.0, select the Generate code that is compatible with J2SE 5.0 check box. If you clear this option, the transformation generates code that is compatible with versions of J2SE 1.4. This check box is available only when you configure a UML-to-Java transformation.
    • To save only the files that change after you run the transformations, select the Write only the updated files to disk check box.

      If you select this option and are working with large models, you might experience a decrease in performance because the transformation must determine the files that it updated, and remove the files that it did not update from its in-memory list. If you work in a team environment, you might also select this check box to eliminate unnecessary checkout operations and the reversal of checkout operations.

      If you clear this check box, the transformation does not remove the unchanged files from its in-memory list. After the transformation runs, it attempts to write the changed and unchanged files to disk. In a team environment, you might have to manually reverse the checkout operations for files that the transformation did not update.

    • To add a Java project dependency to the target project, select the Generate Java project dependencies check box.

      This option is available when you create a Java-to-UML association file on the Java-to-UML Associations page. If you select this check box, when the UML-to-Java transformation encounters a UML reference, the transformation compares the reference to the Java-to-UML association model. If the UML reference maps to a Java project that is not the current target of the transformation, the transformation adds a Java project dependency to the target project.

  8. Optional: Specify whether to delete the corresponding Java files that the transformation generates when you rerun the transformation. For example, if you delete model elements, you might want to delete the corresponding generated files. By default, the transformation does not delete obsolete files.
    • If you are editing a UML-to-Java transformation configuration, select an option in the Delete obsolete generated files section.
    • If you are editing a UML-to-Java (deprecated) transformation configuration, on the Properties page, select an option in the Delete obsolete generated files section.

    When the UML-to-Java transformation generates classes, operations, and fields, it assigns the @generated tag to these elements. The next time that you run the transformation, the transformation overwrites these elements. When you delete elements from the source model and rerun the UML-to-Java transformation, the transformation deletes previously generated fields and methods that still have the @generated tag and that no longer have a corresponding source model element. However, for files that the transformation generates, you can specify whether or not to delete files.

  9. 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.

  10. 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 Java-to-UML transformation is available, you can select the Run the reverse transformation silently check box. Specifying that the Java-to-UML, or reverse transformation runs in silent mode suppresses the merge editor. If a conflict occurs during the merge, the transformation stops and you must rerun the transformation with the silent options cleared.

  11. 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.

  12. 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.
  13. 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 Java enumerations that preserve the name and values of the enumeration literals, select the check box. The names and values of the enumeration literals are generated as strings that can be retrieved.

      To generate Java code for passive class state machines, select the check box. After the transformation runs, you can run the generated state machine code as a Java application.

  14. Optional: For each UML collection type in the source project, you can specify the Java collection type that the transformation generates. A collection represents a group of model elements. The collection type determines whether duplicate model elements in the collection can exist or whether the model elements are ordered.
    • On the Collections page, from each list of UML collection types, select a Java collection type. To specify a custom value, type the value in the appropriate collection field. For more information about UML collection types, see the related concept topic for this transformation.
  15. Optional: To create a file that defines the interdependencies of Java elements and UML elements, create a Java-to-UML association file. This feature 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, and for preventing compiler errors. 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.
    Use the Generate Java project dependencies option on the Main page to enable or disable creation of relationships between Java and UML elements. For more information about support for multiple projects and their interdependencies, see the related concept topic below.
  16. Optional: If the transformation that you configure supports mapping, you can specify alternate names for the artifacts that the transformation generates by creating a mapping model. To use a new or existing mapping model, complete the following steps:
    1. In the transformation configuration editor, on the Mapping page, select the Enable the mapping functionality for this configuration check box.
    2. In the Mapping model file name field, specify the name of a new or existing mapping model.
  17. Click File > Save.


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