Example: Model ID Alignment in action
In this section, you create a model and then create successive generations of it to see what a model looks like when it gets misaligned and to see the Model ID Alignment view in action.
You'll work with a trivial-sized model so that the information is not lost in a sea of details. Figure 10 shows the initial model.
Figure 10. Initial test model
- You will create two copies: one that is already aligned and one that is not.
- To create the aligned model, simply copy and paste the actual file. This simulates "checking out" a new version of a model in a software configuration management (SCM) system, such as IBM® Rational® ClearCase® software.
- To create the unaligned model, you create a new model with the same name. Then you copy all of the contents under the root node in the original model and paste them under the root node in the new model. This operation reassigns all GUIDs and creates a model that is the same as a model created from running a Java-to-UML transformation a second time.
- Activate the Customize View menu item by clicking the downward (expand) arrow at the top-right of the Project Explorer (shown in Figure 11).
- When the list of filters is displayed, please scroll down to the bottom and remove the check mark on the filter for UML model files. This will remove the filter on model files and display the model files in the Project Explorer so that you can copy and paste the model. The paste command brings up a dialog window asking you to rename the model (for this example, use
Figure 11 shows the menu item and the two model files after the copy-paste operation is finished.
Figure 11. Copy-and-paste of model files
- Select the Compare with > Each other command (see menu selections in Figure 12) to launch the comparison editor, which shows the differences in the two models according to their model identities.
Figure 13 shows the result of the comparison.
Figure 12. Compare command for two models
Figure 13. Compare editor results
This result confirms that copying the file will simply make another version of the same model, as would checking the file out of ClearCase. Instead, you need a model that looks more like a model that has been transformed from Java and then transformed again later. This second transformation creates a model that looks identical to the output from the first transformation but has no identities in common.
- Next, remove the new Main diagram, copy the contents of the model named test, and paste them into test_3.
Figure 14 shows the model named test_3 that was created in the Step 5 to simulate this second transformation.
Figure 14. Test_3 model with copied contents
- Now, compare test_2 with test_3, and you should see significant differences (shown in Figure 15.)
Figure 15. Comparison of Test with Test_3
Oops! Creating a new model in this way results in models that are identical in structure but have completely different GUIDS, including that of the main package itself. That disallows identity comparison. Models like these (ones that represent unaligned identities) are normally compared by using Fusion.
So how do I show you here what the differences are? Simple; I cheat. To show you these differences, I copy the model at the file system level again, creating
test_4. This time, though, I edit it and remove all of its contents except for the root node, replacing them with the contents of the original file: test. Again, I copy and paste everything under their respective root nodes. This model will be a strange hybrid of the correct model identity and newly generated contents.
This example is not useful as a scenario (it is not likely to come out of any typical workflow), but it shows you the number of superfluous changes that occurred with this simple transformation (see Figure 16.)
Figure 16. Identity comparison of Test with Test_4
You can now see what happens when you generate a model by using a technique that creates new GUIDs. Even such a small model as this has 10 differences from the original. This model is similar enough in structure (identical, actually) that model alignment should remove all differences. The differences are quite sensible: five additions and five deletions. With mismatched GUIDs, that's the best that identity-based comparisons can do.
A structural comparison, as shown in Figure 17, shows no differences between test and test_4, exactly as we would expect.
Figure 17. Structure comparison of Test with Test_4
- Going back to Test_3, which was the model that has all different GUIDs, start the realignment with the Stage 1 creation of the database file.
- Store this file in a folder anywhere in the network.
Do not treat it as an artifact that can be merged though, because it spans all versions of the files. Allow it to grow in perpetuity as more and more versions of the model are created. The more versions of the model involved, the more GUIDs it incorporates.
Figure 18 shows the full Model ID Alignment view when Stage 1 is selected. It is considerably larger than it appears at first.
- The default location for the ID Mapping Database folder is the Rational Software Architect workspace in use at the time. This is not a particularly good location for an enterprise resource such as the mapping database, so change it to something that is appropriate to the workflow.
If this database is used for a specific model for alignment after regeneration by transformation, then there is no reason why the model cannot be stored in the same Eclipse project with the model root. However, if the database exists to serve migration, and if there might be more streams to align in the future (if the database participates in an ongoing workflow), then this database is a resource that should be on an enterprise file server that is backed up and kept safe for future use.
For this example, Figure 18 shows the project as the target location, because the database has no reason to exist after the project is removed. Also notice the use of the word "keep" in the file names. This is necessary so that ClearCase (if it is the SCM system in use) does not try to remove the files or put them under source control. That is not important until the alignment is finished and all models have their final names and are in their final locations.
Figure 18. Stage 1 Model ID Alignment view
A quick note about the buttons at the right of the large file list window:
Figure 19 shows the result of the Duplicate ID check when the model is not corrupted in this way.
Figure 19. Duplicate ID check result
There are three choices in the radio button group that is labeled Save Location of Models with aligned IDs:
- The first is to overwrite the input file but save a backup
- The second is to save a new file with a relevant name
- The third is to output all of the files to a new folder.
The third option would make sense for a large group of files being converted, but for this test, the second is the simplest choice. It makes what is happening very clear.
At the bottom of the view is the button labeled Generate ID Mapping Files. Clicking this button causes a progress bar to be displayed (in this case, for a very short time). Then a window shows the log file (looking back at Figure 18, notice that the box for the option to show the log after completion was checked.)
Figure 20 shows the result. There are 91 individual elements in this model, and all 91 kept their IDs. This makes sense, of course, because Stage 1 creates the database from the first model's IDs.
Figure 20. Model ID Alignment Stage 1 results
As Figure 21 shows, the output file and the database have been created.
Figure 21. Files in the project after Stage 1
At this point, the input file (the file in Stream 1) has been crawled to create the identity database. The name of that file as shown in Figure 21 is a bit funky, because it incorporates the identity (a GUID) of the file, along with the file's original name in the map file name.
- The output file is identical to the input file, because this was simply Stage 1. It can be discarded.
- To run Stage 2 against the new model, which you will remember is test_3.emx, you must set up the GUI by selecting Stage 2 in the Operation field at the top of the view.
- You must also add the file name.
This is all shown in Figure 22.
Figure 22. Files in the project after Stage 1
A new button has appeared, as highlighted in yellow in Figure 22. You can use this button to tell the tool which database file to use. Because the GUID of the main package is different from that in the earlier version of the model, the automatically generated database file name will not match that created initially.
- So, use this button to select the database that was originally created for this file.
The button brings up a simple file selection dialog, as shown in Figure 23.
- Select the database file by drilling into the appropriate project or finding the alternate location that might have been chosen in Stage 1.
Figure 23. Select the alternate database
As Figure 24 shows, the main view's ID Mapping Database Folder field and the trailing Browse button change now to signal the presence of an alternate database file and to provide the ability to remove the alternate mapping file.
Figure 24. Alternate database selected
- Now, click the Align Model Element IDs button at the bottom of the dialog shown in Figure 22 to perform Stage 2 alignment on the new model.
Figure 25. Log file after Stage 2
The log file that is displayed following Stage 2's completion (Figure 25) shows that 83 of 91 elements were updated. Comparing test with test_3.7.x.keep.emx (the output file from Stage 2) shows no differences in the data. Because of how this file was created, there is, in fact, a change to the name of the main package, which was created when the test file was created as test_3.
- Because test_4 is a hybrid file with the same package name as test but the same data as test_3, it makes sense to run alignment on that file also to see if all changes disappear. And they do, as Figure 26 shows.
Figure 26. Alternate database selected
At this point, the output file has established perfect lineage with the input file. Had there been a new element in the second stream (test_3.emx), its identity would now be in the database. And had that change been propagated further down the line (say, in the original stream set in IBM® Rational Rose® format), Stage 2 in the third stream would naturally align the new element, along with all the existing elements.
A little discipline is required to plot the specific order of alignment and to ensure that all the files are correctly managed with the appropriate databases, but that is a small price to pay for the power of realignment in a multistream environment.