Working on a Remote Model
Several users access the model held by the Team for Capella Server repository through their Team for Capella Client. The Capella project on the client side only consists in one ".aird" file which is both a proxy towards the shared repository and a container for the local diagrams.
|
Fundamental principles
|
1. Locks and Update on Model Elements
Red locks indicate another user is currently modifying the element (this modification might be a deletion). The identification of the user holding the lock is added between brackets as a suffix.
Green locks indicate the current user has reserved or modified the current element.
Below is an example of the decorations in the Project Explorer.
When an element is locked by another user, its editor dialog is still accessible but cannot be modified (all fields are disabled).
Lock decorations are visible in any View of Capella, such as the Semantic Browser, the selection dialogs or the delete confirmation window.
On diagrams, the semantic locks are represented on the graphical artifacts (containers, nodes, ports, links) representing the locked model elements.
Updates of modified semantic elements are performed automatically.
2. Locks and Updates on Diagrams
Two users cannot work simultaneously on the same diagram. As soon as a user modifies a diagram, the whole diagram is locked for the other users.
When creating, cloning or moving a representation, the associated semantic target element is automatically locked. This is useful to avoid that, on a connected project, the current user saves the newly created representation with a null target in case another user had deleted the target just before the current user saves. Note that a warning is displayed in the dialog box to ask the user to save as soon as possible so that to release the lock.
This behavior can be deactivated using the preference CDOSiriusPreferenceKeys.PREF_LOCK_SEMANTIC_TARGET_AT_REPRESENTATION_LOCATION_CHANGE with a false value.
| This behavior has a particular impact when using User Profile. If the user has only a read only right on the semantic element, he cannot create/clone/move a representation on it. |
The lock diagram decorations are visible both on the tab bar of the diagram editor and in the Project Explorer.
When a diagram is locked by another user:
-
Moving or resizing elements is not possible
-
Changing the colors of elements is not possible
-
Adding or removing elements is not possible
-
Changing the label of an element is not possible
However, even though another user locks a diagram, semantic elements appearing on this diagram can still be modified by anyone. This is the case for example of the Function "Acquire Images" on the above example. The opposite is true as well: one can have a green lock on a diagram despite some semantic elements appearing on this diagram are locked by other users.
Once the user modifying a diagram saves and commits its modifications, the diagram is not locked anymore. For the other users currently displaying the diagrams, two different alternatives:
-
If the refresh strategy is "automatic", then the diagram is instantly refreshed. For performance reasons, this alternative is not recommended.
-
If the refresh strategy is set to "manual", then a specific decorator indicates the diagram needs to be updated.
After the refresh is performed, the new layout becomes visible.
Note: on the above example, one semantic element ("Acquire Images") was currently being renamed by the user. The consequence is that the refresh induces a new change (and thus a green lock) on the diagram to reflect the label update.
In Capella, the background of diagrams always represents a semantic element (which is the element under which the diagram is located in the Project Explorer). In case this semantic element is locked (hereunder the Root System Function), a specific decorator is put on the background of the diagram. This means, for example, that even though the diagram is locked for edition (green lock), adding a new element on the background of the diagram is not possible.
3. Local vs Shared Diagrams
Diagrams can be local or shared in the repository. Shared diagrams have specific decorators.
When creating a new diagram, a dialog pops up asking the user to choose whether the diagram should be shared (cdo://) or local (platform:/resource…).
It is possible to move diagrams from the repository to the local project and vice versa.
From the local project to the shared repository.
From the repository to the local project.
Note that there is a warning when the selected target is local.
|
Semantic elements created on a local diagram are instantaneously shared with other users as soon as a commit is performed. Local diagram does not mean local elements. |
4. Explicit Locks
It is possible to explicitly lock an (or a set of) element(s) by using the contextual menu.
Note that only semantic elements are locked. Diagrams can also be locked explicitly, but individually.
The behavior of the locks when they are set manually is a bit different from the one of automated locks: while automated locks are systematically released at each commit, elements locked explicitly have to be unlocked explicitly as well.
Consider the following use case
-
Element A and B are explicitly locked.
-
Element C is automatically locked because modified.
-
Element B is modified.
-
A commit action is performed:
-
Lock on A is kept.
-
Lock on B is kept, but the modification on B is committed.
-
Lock on C is released and the modification on C is committed.
-
5. Dissociated local Saves and Commits
Currently not available.
6. Commit Descriptions and History
A Preference allows specifying whether a description is required when committing or not. In case this option is enabled, the following dialog is prompted on each commit action.
Dialog buttons:
-
OK: the commit is performed with the given commit description.
-
Ignore: the commit is performed without the commit description.
-
Cancel: the commit is canceled. In this case, the user changes are kept unsaved and are still visible locally.
Another preference allows the user to pre-fill the commit description using various strategies. The default strategy exploits the previous commit description, while the Mylyn strategy relies on the content of the currently-active, non-completed Mylyn task using the template defined in the Mylyn > Team preferences. Below is an example of such a template:
${task.description}
User Information:
Key: ${task.key}
URL: ${task.url}
For more information about these templates, refer to the Mylyn documentation.
A dedicated view allows displaying the commit history. This window can be opened with the contextual menu called on the semantic model.
This view is particularly useful to monitor the current changes on the shared model. The objective of this history is also to attach as a change log when pushing back file-version of the model to Git.
This view is divided in two parts :
-
The left part list all the commits (saves) that occurred on the Capella Project. Each commit is defined by the date of the commit, the user that committed the change (only if the Server supports authentication) and the first line of the Commit description associated to this commit.
-
The right part describes the impacted elements by the selected commit(s) and the nature of their change (CREATED/DELETED/MODIFIED/UNTOUCHED).
The Commit History View contains several buttons to modify the context of the commits list, filter those commits or modify the change viewer tree layout/content.
In particular, a "Filter" button is present in the Commit History view toolbar and allows the user to filter the content of the impacted elements.
This button is represented by the following icon : 
By activating or deactivating this button, the user can apply or not the selected filter.
Selected filters can be customized into the menu icon > Filters…
A new selection dialog is opened. From this dialog, the user can select filters to activate for the Commit History view. Filters provided in this selection dialog are the same as filters available in the Capella Project Explorer.
7. Session Details Properties Pages
The properties page (contextual action) on aird files of Capella connected project has a tab named Collaborative Session Details. It presents the repository information (location, port and name) and information about connected users and locked elements for this connected project. For more details, refer to Collaborative Session Details of the Sirius Collaborative Mode user documentation.
The properties page (contextual action) on aird files of local or connected Capella projects has a tab named Sirius Session Details. It provides a lot of useful information about the project (used viewpoints, information about representations and capella models). For more details, refer to Sirius Session detailed information of the Sirius user documentation.