<commit_before>---

Copyright 2014 Mentor Graphics Corp.  All Rights Reserved.

---

# Address compare/merge issues from 4.1.10
### xtUML Project Design Note

1. Abstract
-----------
This note describes the changes required to address a few issues found in the
4.1.10 release.  These issues are all related to new support added in 4.1.10.

2. Document References
----------------------
[1] Issues 1, https://github.com/xtuml/internal/issues/227     
[2] CQ Issue: dts0101054289 - Graphics are not automatically merged unless a
                              manual merge has been completed      
[3] CQ Issue: dts0101056206 - Changes made to instance state machine of the
                              subtype class cause dangling references in
                              BP 4.1.10   
[4] CQ Issue: dts0101056209 - Switching to a branch which doesn't have updated
                              ISM polymorphic event identifiers causes false
                              dangling references errors   
[5] CQ Issue: dts0101009925 - Merging addition of state machine from two
                              branches   
[6] CQ Issue: dts0101040652 - Graphical elements should not be used in the merge
                              process   

3. Background
-------------
BridgePoint release, 4.1.10, added support to address issues [5] and [6].  A few
issues were found by the customer relating to this work.

4. Requirements
---------------
- The compare merge editor shall be marked dirty if only graphical data changes   
  are present
- A new element shall be able to get added to a newly switched to branch
- The tool shall not update SM Ids except for during compare/merge

5. Analysis
-----------
5.1 Graphical merge

Since 4.1.10 graphical data is automatically merged.  When this support was
added the case where no semantical data was present in the changeset was not
considered.  The tool shall detect this case and mark the editor as dirty.  This
allows the user to either save or skip adding the graphical changes by closing
without saving.

5.2 Adding an element to a newly checked out branch

Investigation shows that when Selection.setSelection is called we are checking
if the elements in the new selection already exist, if they do the selection is
not updated.  In the case of a file replace the element is equal according to
the equals method, but they are not the same java instance.  The element in the
selection is the one torn down due to the file replace.  Since it is left over
the creation of new elements does not work.  The tool shall simply clear the
previous selection when setSelection is called.  There is no benefit to checking
the current selection before updating it.

5.3 Dangling references

With the changes from [5] the tool was modified to upgrade models to use an id
based off of the class' id and a character (either 'i' or 'c').  This allowed
two state machines added in two different branches to get merged together as the
class id was always the same.  This approach affected the in memory model only
which allowed for a hole when dealing with polymorphic events.  If the user
modified and committed only one of the supertype or subtype the ids on disk
would be out of sync.  This caused for corruption on the next load.  In addition
the upgrade code was interfering with model reloads when both versions of the
data file were not corrupt.  This resulted in temporary dangling reference
errors.  The tool shall change the SM ID upgrade policy to only upgrade them
when dealing with compare/merge.  This allows for the data on the disk to always
remain in sync.  Doing this will still address [5] and will prevent [3] and [4]
from ever occurring.
   
6. Design
---------
6.1 Graphical merge

In ModelContentMergeViewer.updateContent() code is added that looks for incoming
graphical changes.  If any exist the viewer is marked dirty.  This code will not
return graphical changes for those thay do not have a matching semantic change.
The editor will only ever be marked dirty if only graphical data changes are
present.

6.2 Adding an element to a newly checked out branch

Selection.setSelection() is modified to remove comparisons against the current
selection and instead just set the selection to what is passed in.

6.3 Dangling references

The new approach to support [5] is to only update the SM ids in compare/merge.
To do so ModelCacheManager is modified to cache the original SM id if the file
contents contain an ISM or CSM.  Then on load the class will update the ids to
an id generated from the OBJ_ID plus the 'i' or 'c' character.  To handle this
the upgrade code that was added in [5] is moved to this class.

On save the tool must restore the original id.  The same update code from the
ModelCacheManager class is called to update the ids, only the cached id is used.

All references to the upgrade code from [5] is removed.  Additionally, the two
attributes added in [5] to Model Class are removed.  The schemas and test code
are modified to remove support for these two attributes.

Nothing is required to remove the attributes from persisted models.  The
importer simply ignores any attributes that are not modeled.  If we were
removing an attribute not at the end, then we would require upgrade code.

7. Design Comments
------------------
7.1 Various exceptions found during testing<commit_msg>Job: #227 Update for pre-review comments<commit_after>---

Copyright 2014 Mentor Graphics Corp.  All Rights Reserved.

---

# Address compare/merge issues from 4.1.10
### xtUML Project Design Note

1. Abstract
-----------
This note describes the changes required to address a few issues found in the
4.1.10 release.  These issues are all related to new support added in 4.1.10.

2. Document References
----------------------
[1] Issues 1, https://github.com/xtuml/internal/issues/227     
[2] CQ Issue: dts0101054289 - Graphics are not automatically merged unless a
                              manual merge has been completed      
[3] CQ Issue: dts0101056206 - Changes made to instance state machine of the
                              subtype class cause dangling references in
                              BP 4.1.10   
[4] CQ Issue: dts0101056209 - Switching to a branch which doesn't have updated
                              ISM polymorphic event identifiers causes false
                              dangling references errors   
[5] CQ Issue: dts0101009925 - Merging addition of state machine from two
                              branches   
[6] CQ Issue: dts0101040652 - Graphical elements should not be used in the merge
                              process   

3. Background
-------------
BridgePoint release, 4.1.10, added support to address issues [5] and [6].  A few
issues were found by the customer relating to this work.

4. Requirements
---------------
- The compare merge editor shall be marked dirty if only graphical data changes   
  are present
- A new element shall be able to get added to a newly switched to branch
- The tool shall not update SM Ids except for during compare/merge

5. Analysis
-----------
5.1 Graphical merge

Since 4.1.10 graphical data is automatically merged.  When this support was
added the case where no semantical data was present in the changeset was not
considered.  The tool shall detect this case and mark the editor as dirty.  This
allows the user to either save or skip adding the graphical changes by closing
without saving.

5.2 Adding an element to a newly checked out branch

Investigation shows that when Selection.setSelection is called we are checking
if the elements in the new selection already exist, if they do the selection is
not updated.  In the case of a file replace the element is equal according to
the equals method, but they are not the same java instance.  The element in the
selection is the one torn down due to the file replace.  Since it is left over
the creation of new elements does not work.  The tool shall simply clear the
previous selection when setSelection is called.  There is no benefit to checking
the current selection before updating it.

5.3 Dangling references

With the changes from [5] the tool was modified to upgrade models to use an id
based off of the class' id and a character (either 'i' or 'c').  This allowed
two state machines added in two different branches to get merged together as the
class id was always the same.  This approach affected the in memory model only
which allowed for a hole when dealing with polymorphic events.  If the user
modified and committed only one of the supertype or subtype the ids on disk
would be out of sync.  This caused for corruption on the next load.  In addition
the upgrade code was interfering with model reloads when both versions of the
data file were not corrupt.  This resulted in temporary dangling reference
errors.  The tool shall change the SM ID upgrade policy to only upgrade them
when dealing with compare/merge.  This allows for the data on the disk to always
remain in sync.  Doing this will still address [5] and will prevent [3] and [4]
from ever occurring.
   
6. Design
---------
6.1 Graphical merge

In ModelContentMergeViewer.updateContent() code is added that looks for incoming
graphical changes.  If any exist the viewer is marked dirty, unless they are
accompanied by a semantic change.  In other words the editor will only ever be
marked dirty if only graphical data changes are present.

6.2 Adding an element to a newly checked out branch

Selection.setSelection() is modified to remove comparisons against the current
selection and instead just set the selection to what is passed in.

6.3 Dangling references

The new approach to support [5] is to only update the SM ids in compare/merge.
To do so ModelCacheManager is modified to cache the original SM id if the file
contents contain an ISM or CSM.  Then on load the class will update the ids to
an id generated from the OBJ_ID plus the 'i' or 'c' character.  To handle this
the upgrade code that was added in [5] is moved to this class.

On save the tool must restore the original id.  The same update code from the
ModelCacheManager class is called to update the ids, only the cached id is used.

All references to the upgrade code from [5] is removed.  Additionally, the two
attributes added in [5] to Model Class are removed.  The schemas and test code
are modified to remove support for these two attributes.

Nothing is required to remove the attributes from persisted models.  The
importer simply ignores any attributes that are not modeled.  If we were
removing an attribute not at the end, then we would require upgrade code.

7. Design Comments
------------------
7.1 Various exceptions found during testing
{'fraction_non_alphanumeric': 0.04976192699094389, 'fraction_numerical': 0.02250023340491084, 'mean_word_length': 3.021021021021021, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4990517', 'n_tokens_mistral': 2733, 'n_tokens_neox': 2539, 'n_words': 1650}