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 . If Transformation Configuration is not a menu item, click .
- 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:
- In the Name field, specify a name for the configuration.
- 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 (/).
- 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:
- In the Selected source pane, select the source element for the transformation
to transform.
- 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 Next.
- Optional: Specify which C++ elements the transformation
transforms into UML operations, and whether the transformation generates
UML associations or UML properties for member variables in a class.
These options provide you with greater control over the UML elements
that the transformation generates in the target UML model. By default,
for each class that you specify in the transformation source, the
transformation generates UML operations for C++ getter and setter
methods, default constructors and destructors, copy constructors,
and assignment operators, and creates UML associations for member
variables. On the C++ to UML Options page, complete one or more of
the following steps:
- To create UML operations, select the check boxes beside the
C++ elements to transform.
- To create UML associations for member variables, select the Generate
UML associations for C++ member variables by peeking into the model check
box. The transformation examines the target model and creates association
relationships for member variables that are part of an association
relationship. If a member variable is not part of a UML association,
the transformation creates a UML property.
- Optional: To resolve references
to UML elements that are outside the scope of the transformation target,
create an association file that defines links between C++ and UML
elements. This functionality is useful when the elements to transform
are in multiple C++ projects and their interdependencies are outside
the transformation that you configure. To create an association file,
on the C++-to-UML Associations page, complete the following steps:
- Select the Enable C++-to-UML associations check
box.
- In the C++-to-UML association file name field,
specify a file name.
- In the C++-to-UML associations section, beside the table,
click the buttons to add or remove an association from the file.
The order of the associations determines how C++ elements map
to UML elements. For more information about support for multiple projects
and their interdependencies, see the related C++-to-UML transformation
concept topic below.
- Click Finish. The transformation configuration
editor opens, and the contents of the configuration are displayed.
- 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 ; 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-C++, or reverse, transformation is available, you can select
the Run the reverse transformation silently check
box. Specifying that the reverse transformation runs in silent mode
overrides the file overwrite options that you specify in the transformation
configuration. The transformation overwrites files if necessary.
- To create traceable relationships between the elements
in the transformation source and target, on the Main page,
select the Create trace relationships check
box. You typically select this check box the first time that you run
the C++-to-UML transformation in a Reconciled
Modeling environment,
so that you can synchronize the C++ source code with the target UML
model. After the transformation runs, in the merge window, for each
corresponding proposed change that you accept, the transformation
adds @generated tags and unique identifiers to the
code elements that have a corresponding representation in the target
UML model. Generating traceable relationships
prevents the transformation from generating duplicate elements in
the transformation target.
To
view the list of elements for which traceable relationships can be
created, see the related transformation concept topic link at the
end of this topic.
For each proposed change
that you do not accept in the merge window, the transformation does
not add these annotations to the code element. The next time that
you run the UML-to-C++ transformation, it generates a duplicate code
element because no relationship exists between the model element and
code element.
- Optional: To
display the errors that occurred when the transformation ran, on the Main page, select the Open the Report dialog box when the transformation
is complete check box. Selecting this check box displays
only the generated errors. The same information is also written to
the error log, which you can view by clicking .
To display the warnings
that occurred when the transformation ran, select the Show warnings in the Report dialog
box check box.
- 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.
- Click .
Results
The options are applied the next time that
you run the transformation.