Collaborative API Overview

You will be able to connect a Collaborative Session to a CDO repository. This will create a new CDOTransaction on the described repository. Consequently, when the user tries to add a remote CDO model or representation to this session, the repository location will be pre-filled.

Notice that as soon as a Remote Semantic Resource or Representation is referenced by the Collaborative Session, the session will connect itself to the corresponding CDO Repository. So you should use the connect(RepositoryConfig) method only if you want a Collaborative Session to be connected by default (even if empty) to a certain repository.

If a Collaborative Session has been connected (explicitly or automatically) to a CDO Repository, you can easily get the RepositoryManager associated to this session: simply call session.getRepositoryManager().

When a user saves his session, if the modifications are impacting elements located on a CDO Repository, we can:

The default behavior is to check the Collaborative preferences:

Thanks to the session.setCommitOnSave(boolean) method, you can specify whether the next call to session.save() will commit the changes (if the parameter is true) or same them locally (if false).

Notice that committing changes or saving them locally has an impact on lock releasing.

The session.setDefaultRepresentationContainer(URI danalysisURI) method allows you to specify in which DAnalysis new representations should be stored. Using this method, you can force all new representations to be created on the repository.

The fr.obeo.dsl.viewpoint.collab.api.CDORepositoryManager handles the lifecycle of CDOTransactions and CDOSessions. You should not open your own CDOTransactions, but rely on the CDORepositoryManager to do so.

The fundamental rules of the CDORepositoryManager are:

Each CDORepositoryManager provides, through the getRemoteExceptionHandler() method, a ISiriusRemoteExceptionHandler used to deal with Remote Exceptions (such as Network Breakdown, invalid credentials…).

You can provide your own ISiriusRemoteExceptionHandler through the fr.obeo.dsl.viewpoint.collab.exceptionhandler extension point. It is advised to extend the UISiriusRemoteExceptionHandler and call the super implementation in all overridden methods, to benefit from the default behavior.

The fr.obeo.dsl.viewpoint.collab.api.CDORepositoryManagerRegistry is in charge of creating and deleting CDORepositoryManager when needed.

You can get the CDOTransaction associated to a Collaborative session:

Notice that the CDORepositoryManager already handles CDOTransactions lifecycle: CDOTransactions are opened when a Collaborative Session referencing a CDORepository is opened and close when this session is closed.

However, you may need to open or close CDOTransactions that are not linked to any viewpoint session, to make some modifications to the CDO Repository.

The CDOLockManager allows you to determine whether an element is:

You can use the boolean isLockedByOthers(EObject element), boolean isLockedByAny and boolean isUnlocked(EObject element) methods to determine the lock status of an element.

An explicit lock is a lock placed explicitly on remote elements (by the user through an Action or programmatically). Such locks are not released when the Transaction gets committed (contrary to Implicit locks).

If the CDOSiriusPreferenceKeys.PREF_ENABLE_DURABLE_LOCKING is true, then the locks will be persistent, event if the Collaborative Session is closed. They will last until the user explicitly unlocks the locked elements (through an Action or programmatically).

An explicit lock can be performed recursively (i.e., all the children of locked elements are also locked). Notice that you can lock both semantic or graphical elements (DDiagrams, DTree items, DLines of a DTable…).

Sirius relies on a pessimistic lock mechanism: any time a user makes a modification, all the elements impacted by this modification are automatically locked, to prevent from any conflict.

Such locks are called implicit locks, as they have been placed automatically. As their only purpose is to avoid conflicts, they are released when the user commits to the repository. Notice that if the save action should save local changes and not commit them, then implicit locks will not be released until a commit is performed.

To determine the elements to lock when a modification is made, Sirius uses a default lock strategy. The platform allows you to define your own lock strategies.

The Set<String> importLocalFilesOnRepository(Set<URI> urisOfLocalFilesToImport, CDORepositoryManager repositoryManager, boolean replaceExistingCDOResources, boolean exportWorkspaceImages, IProgressMonitor monitor) method of the CDOImporter allows you to upload a set of local models on a CDORepository.

The Set<String> exportFilesFromRepository(Set<URI> resourceURIs, CDORepositoryManager repositoryManager, boolean replaceExistingResources, boolean importWorkspaceImages, IProgressMonitor monitor) method of the CDOExporter allows you to download a set of remote models inside the Eclipse workspace.