Common Collaborative use cases

The following documentation will give some basic examples of manipulation of the Sirius Collaborative API. You can also refer to the advanced collaborative use case documentation to get additional information about customization of default collaborative behavior.

1. Manipulate Collaborative Sessions

1.1. Open a Collaborative Session

Opening a collaborative session with Sirius API is exactly the same as opening a local session: you can use the org.eclipse.sirius.business.api.session.factory.SessionFactory or the org.eclipse.sirius.business.api.session.SessionManager.

// Step 1 : define the session URI
URI sessionResourceURI = URI.createPlatformResourceURI("myProject/session.aird");

// Step 2 : get the corresponding session
Session session = SessionFactory.createSession(sessionResourceURI);
// or
Session session = SessionManager.INSTANCE.getSession(sessionResourceURI);

// Step 3 : open the session
session.open();

// Step 4 : cast the session to CollaborativeSession
// to get additional API
if (session instanceof CollaborativeSession){
	((CollaborativeSession)session).setCommitOnSave(false);
}

The opened session will implement the CollaborativeSession interface.

1.2. Close a Collaborative Session

Collaborative Sessions are closed exactly like local sessions: when calling session.close(), the CDOSession and CDOTransaction associated to the collaborative session will automatically be closed. Implicit locks are automatically released.

1.3. Connect a Collaborative Session to a CDO Repository

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. However, if you want a Collaborative Session to be connected by default (even if empty) to a certain repository, you can refer to the documentation of the connect (RepositoryConfig) method.

2. Add a semantic resource located on a CDO Repository

The following example adds a CDOResource as a semantic model of the Collaborative Session created in the previous section:

// Step 1 : get the repository manager of the CDORepository containing the resource to add
CDORepositoryManager manager = CDORepositoryManagerRegistry.getRepositoryManager("localhost", "2036", "repo1");

// Step 2 : get the cdo resource to add

// Version 2.A : if you want to modify the CDO Resource before adding it
CDOResource semanticResource = manager.getOrCreateTransaction(session).getOrCreateResource("myResourceToAdd.xmi");
// You can modify the CDO Resource here : add children...
URI semanticResourceURI = semanticResource.getURI();

// Version 2.B : if you do not want to modify the CDOResource
URI semanticResourceURI = URI.createURI("cdo://repo1/myResourceToAdd.xmi");

// Step 3 : add the resource using the AddRemoteResourceCommand
Command addSemanticResourceCommand = new AddRemoteResourceCommand((CollaborativeSession) selectedCollaborativeSession, manager, semanticResourceURI);
session.getTransactionalEditingDomain().getCommandStack().execute(addSemanticResourceCommand);

Now the Collaborative Session references a remote semantic resource, from which local and remote representations can be created.

3. Allow the end-user to create remote representations

In the previous section, we added a semantic model located on a CDO Repository to a Collaborative Session. Now we want our user to be able to create remote representations that he will share in real-time with other users. These remote representations will be stored inside a remote representations set (nothing more than a standard org.eclipse.sirius.DAnalysis located on a CDO Repository).

3.1. Create a new remote representations set

// Step 1 : get the resource that will contain remote representations
CDOResource remoteRepresentationsResource = manager.getOrCreateTransaction(session).getOrCreateResource("myRemoteDAnalysis.aird");
// notice that you can also write
CDOResource remoteRepresentationsResource =((CollaborativeSession)session).getRemoteResource("myRemoteDAnalysis.aird");

// Step 2 : create the root of the resource
DAnalysis representationContainer = SiriusFactory.eINSTANCE.createDAnalysis();
remoteRepresentationsResource.getContents().add(representationContainer);

// Step 3 : add the representation container to the session
session.addRemoteRepresentationsSet("myRemoteDAnalysis.aird");

3.2. Connect to an existing remote representations set

// As the resource already exists (created by an other user for example)
// we just have to add it to our session
session.addRemoteRepresentationsSet("myRemoteDAnalysis.aird");

3.3. 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 forbid the creation of local representations (to make sure that all created representations are located on a CDO Repository).

// Step 1 : get the Remote Representations Set URI
URI remoteRepresentationsSetURI = manager.getOrCreateTransaction(session).getOrCreateResource("myRemoteDAnalysis.aird").getURI();
// or
URI remoteRepresentationsSetURI = CDOURIUtil.createResourceURI(manager.getOrCreateTransaction(session), "myRemoteDAnalysis.aird");

// Step 2 : define the default container of all new representations
collaborativeSession.setDefaultRepresentationContainer(remoteRepresentationsSetURI);

If you want to define complex rules to determine in which representation container should new representations be created, you can use the collaborativeSession.setAnalysisSelector() method.

3.4. Create a remote representations from a Remote Resource

Once you defined where new representations should be created, you have to create the remote representation using the DialectManager.

// Step 1 : get the semantic resource on which the representation should be created
CDOResource semanticRemoteResource = session.getRemoteResource("myRemoteResource.xmi");
EObject representationRoot = semanticRemoteResource.getContents().get(0);

// Step 2 : create the representation
DialectManager.INSTANCE.createRepresentation("myNewRemoteRepresentationName", representationRoot, representationDescription, session, new NullProgressMonitor());

// Step 3 : commit changes
session.save(new NullProgressMonitor());

4. Upload and download models

Sirius provides API for uploading and downloading models on/from the CDO Repository.