Configuring UML-to-EJB 3.0 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

  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, which runs as part of the UML-to-EJB 3.0 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 the corresponding Java files that the UML-to-Java transformation generates should be deleted when you rerun the transformation. On the Main page, select an option in the Delete obsolete generated files section. 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.
  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 EJB 3.0–to-UML transformation is available, you can select the Run the reverse transformation silently check box. Specifying that the EJB 3.0-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 values for the code generation properties that are unique to the UML-to-EJB 3.0 transformation. On the Properties page, specify values for the following properties:
    Option Description
    Generate a deployment descriptor By default, this property is set to false, and the transformation does not generate files named orm.xml and persistence.xml in the META-INF folder of the target project. Instead, the transformation generates JPA annotations in the generated Java code.

    Set this property to true to specify that the transformation generates these XML files and the XML elements that correspond to the UML elements in the source models. The transformation does not generate the corresponding JPA notations in the Java code, and it deletes the annotations that it generated previously in the code.

    To preserve the changes that you make to an XML element, delete its corresponding <!–@generated –> tag.

    If duplicate elements exist in the code and the XML file, the generated elements in the XML file override the generated annotations in the code.
    Generate equals and hashCode operations for all entity classes By default, this property is set to false, and the transformation does not generate these operations.
    To generate these operations, complete the following steps:
    1. Set this property to true.
    2. Apply the «Entity» stereotype to the class that contains the properties to generate the equals and hashCode operations.
    3. Apply the «Id» stereotype to the properties.
    Generate named queries for all entity classes By default, this property is set to true, and the transformation generates a named query for each entity bean; the transformation overwrites existing named queries in the code.

    To prevent the generation of named queries and to protect existing named queries in the entity bean code, set this property to false.
    Transform sequence diagrams By default, this property is set to true, and the transformation transforms all sequence diagrams in the model. All messages and relationships between EJB 3.0 artifacts and JPA entities in the diagrams are also transformed.
    Note: To refine how the UML-to-EJB 3.0 transformation generates EJB 3.0 enterprise beans, you can extend the transformation and define properties in the transformation extension. The properties that you define are displayed on the Properties page when you create a transformation extension.
  14. Optional: For each UML collection type in the source project, you can specify the Java collection type that the UML-to-Java 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.

Results

The options are applied the next time that you run the transformation.
Related concepts:
Reverse transformations: EJB 3.0 to UML
Design contract management protocols
UML-to-Java transformations
UML-to-EJB 3.0 transformations description
Transformations and transformation configurations
Related tasks:
Validating UML-to-EJB 3.0 transformation configurations
Related information:
Configuring EJB 3.0-to-UML transformations
Feedback