Collaborative API Overview

The main purpose of Viewpoint collaborative features is to allow users to collaborate in real-time around semantic models and representations. Although Viewpoint provides default behavior and UI for collaboration, you are totally free to use Viewpoint as a platform and build your own features uppon it, or customize existing behaviors.

The following documentation will give you an overview of the Collaborative API provided by Viewpoint. Feel free to consult the common collaborative use case documentation and the advanced collaborative use case documentation to see examples of Collaborative features use and customization.

Collaborative Plugins hierarchy

Viewpoint collaborative features are based on the CDO technology (please refer to CDO documentation for additional informations).

These features are defined in the following plugins:

Viewpoint also provides a Collaborative Test Framework through the fr.obeo.dsl.viewpoint.tests.collab.* plugins.

API overview

The CollaborativeSession interface: additional behavior for a ViewpointSession

The fr.obeo.dsl.viewpoint.collab.api.remotesession.CollaborativeSession interface represents any Viewpoint Session able to reference semantic resources or representations located on a remote CDO Repository.

When the collaborative mode is active (i.e. if CDOViewpointPreferenceKeys.COLLABORATIVE_MODE_ACTIVATED is true), all Viewpoint Sessions created by calling fr.obeo.dsl.viewpoint.business.api.session.factory.SessionFactory or through the fr.obeo.dsl.viewpoint.business.api.session.SessionManager will implement this interface.

This interface provides collaborative behavior for Viewpoint sessions.

Connect a Collaborative Session to a CDO Repository

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 will try 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. 

// Step 1: create the RepositoryConfig describing my repository location
RepositoryConfig repositoryConfig = CDOConfigFactory.eINSTANCE.createRepositoryConfig();
repositoryConfig.setHostLocation("localhost:2036");
repositoryConfig.setRepositoryName("myRepo");

// Step 2: connect my Session to this repository
session.connect(repositoryConfig);

Get the CDORepositoryManager associated to a Collaborative Session

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().

Customize the behavior of the Save action

When 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 impact on lock releasing.

Define where new representations should be created

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

// Step 1: get all the Remote DAnalysis associated to our current session
Iterable<CDOResource> remoteDAnalyses = Iterables.filter(collaborativeSession.getAllSessionResources(), CDOResource.class);

// Step 2: we say that all new representations should be created
// in the first Remote DAnalysis we found
if (remoteDAnalyses.iterator().hasNext()){
	collaborativeSession.setDefaultRepresentationContainer(remoteDAnalyses.iterator().next().getURI());
}

The CDORepositoryManager: handles the CDOTransactions and CDOSessions lifecycle

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:

The CDORepositoryManagerRegistry: handles CDOrepositoryManager life-cycles

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

Get the CDOTransaction associated to a Collaborative Session

You can easily get the CDOTransaction associated to a Collaborative session: 

// Step 1: get the CDORepositoryManager
// using the repository configuration
CDORepositoryManager manager = CDORepositoryManagerRegistry.getRepositoryManager(repositoryConfig);

// using directly the session: 
CDORepositoryManager manager = CDORepositoryManagerRegistry.getRepositoryManager(session);
// or
CDORepositoryManager manager = session.getRepositoryManager();

// Step 2: get the CDOTransaction associated to the session
CDOTransaction transaction = manager.getOrCreateTransaction(session);

Open and close CDOTransactions

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 on the CDO Repository.

// Step 1: creating a resource set for my transaction
ResourceSet rs = new ResourceSetImpl();

// Step 2: open a transaction on this resourceSet
CDORepositoryManager manager = CDORepositoryManagerRegistry.getRepositoryManager(config);
CDOTransaction transaction = manager.getOrCreateTransaction(rs);

// Step 3: using the transaction to modify the repository content
transaction.getOrCreateResource("myNewResource");
transaction.commit();

// Step 4: close the transaction
// this will also close the CDOSession
// and dispose the CDORepositoryManager
manager.closeTransaction(transaction);

The CDOLockManager: allows to lock and unlock elements

Get the lock status of remote elements

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.

Explicit locking

An explicit lock is a lock that is 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 CDOViewpointPreferenceKeys.PREF_ENABLE_DURABLE_LOCKING is true, then the locks will be persistent, event if the Collaborative Session is closed. They will last until the locked elements are explicitly unlocked (by the user 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...). 

// Step 1: getting a remote semantic element
EObject rootElementToLock = session.getSemanticResources().iterator().next().getContents().get(0);
Collection<EObject> elementsToLock = Lists.newArrayList(rootElementToLock);

// Step 2: locking the element and all its children
CDOLockManager.INSTANCE.acquireLock(elementsToLock, true, true);

// Element is now locked: 
// CDOLockManager.INSTANCE.isLockedByMe(rootElementToLock)     : true
// CDOLockManager.INSTANCE.isLockedByOthers(rootElementToLock) : false
// CDOLockManager.INSTANCE.isUnlocked(rootElementToLock)       : false

// Step 3: unlocking the element and all its children
CDOLockManager.INSTANCE.releaseExplicitLocks(elementsToLock, true);

// Element is now unlocked: 
// CDOLockManager.INSTANCE.isLockedByMe(rootElementToLock)     : false
// CDOLockManager.INSTANCE.isLockedByOthers(rootElementToLock) : false
// CDOLockManager.INSTANCE.isUnlocked(rootElementToLock)       : true

Implicit locks: define your own lock strategies

Viewpoint 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 on the repository. Notice that if the save action should save locally 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, Viewpoint uses a default lock strategy. The platform allows you to define your own lock strategies .

Upload and Download models

Viewpoint provide API for uploading and downloading models on/from the CDO Repository, through the fr.obeo.dsl.viewpoint.collab.api.CDOImportExportManager.

Upload a local model on the CDORepository

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

Download a remote model locally

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

Customize authentication

Viewpoint API allows you to customize your authentication policy.
If your CDOServer has an authentication mechanism, you may want to customize the way authentication is handled inside Viewpoint.

To do so, you can provide your own fr.obeo.dsl.viewpoint.collab.api.CDOAuthenticationManager and register it in the fr.obeo.dsl.viewpoint.collab.api.CDOAuthenticationManagerRegistry.

Please refer to the advanced collaborative use case documentation to get an example of authentication customization.

Collaborative preferences

You can change the Collaborative preferences to customize Viewpoint behavior: