Documentum Composer and Eclipse Team

Now that we have Composer installed on Eclipse JEE we have an open tooling platform that we can extend.  One such extension is Eclipse Team that provides a source control API that most source control vendors; cvs (comes with eclipse anyway), svn, perforce, starteam, etc, have integrated with.  Right out of the box you can share your projects with other team members via most standard source control systems.  For demonstration I’m going to use the Subversive SVN provider here but the others all work in a similar way.

As part of the scenario we will be playing out the role of two developers by switching between two workspaces.

Installing the SVN Provider

First thing first though we need to install the Subversive SVN team provider.  Goto Help->Install New Software…  Select Helios in the “Work with” drop down and type “svn” into the filter box.  Select the Subversive SVN Team Provider (Incubation) and install it.

You will be prompted for the usual restart so go ahead and do that. 

Configuring the Team Provider for Documentum

Next we need to tell the team provider what to checkin.  You need to do this in the other workspace too and I will remind you to do so.  Goto Window->Preferences…->Team->Ignored Resources. 

Click Add Pattern… and add the following three patterns:-
*.artifact

Now repeat that adding the next two patterns:-
*.dar
/Web Services/bin/*

This tells all the team providers to ignore built artifact files (*.artifact), Documentum ARchives (*.dar) and all web service build artifacts.  There is no point in checking these in.

Sharing a Project

We now assume the role of the first developer.  He wants to share a project.  With the Documentum Artifacts perspective open create a new Documentum project to share.  As this is the first Documentum project in your workspace Composer will also create the core and the TCM reference project for you.  As these two upstream projects are both referenced by your project you need to check these in too.  This ensures your projects references will be satisfied when others check them out.  This principal stands for any referenced projects that you may add too. 

The core and tcm reference projects are hidden in the Documentum Artifacts perspective so open the Navigator view to show all three projects; Window->Show View->Navigator.  Now you can see all three projects, select the core project first, right-click and select Team->Share Projects…

This will bring up the SVN Share Projects Wizard.

Enter the URL for your SVN repo and the login details.  We can default everything else so just click Finish. 

SVN will then pop up the Commit dialog allowing you can enter a comment for the commit and to review the set of files that will be commited.  It is worth checking these to make sure there are no resources that should be ignored.

Click OK and the files will be added to the repository.  Once that’s done, repeat this process for the TCM reference project and lastly for you project.

Once all three projects have been shared your workspace should look something like this:-

Note the little orange repository icon in the bottom left hand corner of all your folders and files.  This is a visual indicator that these files are being managed with source control.

Import a Project

So now other developers are free to work on these projects too.  Let’s have a look at how they might do that. 

Switch to a new, empty workspace and show the Documentum Artifacts perspective.  Now set up the ignored resources as we did earlier.

Now import the projects that were shared by developer one.  Right-click in the Project Explorer and select Import->Import… to bring up the Import dialog.  Find and expand the SVN category and select Project from SVN.

Click Next to launch the SVN Import dialog.  On the first page enter the repository info as you did before.  Click Next to bring up the Select Resource dialog.

Select the Browse button.  Navigate to the DocumentumCoreProject and select it. 

Click OK to confirm the selection and return to the previous dialog.  Then click Finish to bring up the Check Out As dialog. 

Accept the defaults on this dialog and Click Finish to start the import.

Once the core project has been imported repeat the same process for the tcm reference project next and finally for your project.  Don’t forget the core and tcm reference projects won’t be visible in the Documentum Navigator so you can open one of the other navigator views to see them.

Once all three projects have been imported you should see something like this:-

Again, note the little orange repository icons indicating these projects are under source control.

Updating a Project

Naturally your developers are now going to update the project by adding new artifacts, editing others and possibly deleting some others still.  This is all part of the natural life-cycle of the project.

So switch workspace back to the first developer and let’s make a couple of changes.  Let’s add a new format artifact and edit the description of the dar folder install parameter.  Your workspace should now look something like this.

Note the arrow (>) next to items that have been modified.  And note also that these track all the way back up the tree to the project itself.  And the little question mark on the format artifact indicating it is new.  If you want to learn more about the SVN icons goto Window->Preferences->Team->SVN->Label Decorations for this dialog:-

Now submit these changes.  The first thing we do is merge out; i.e. grab all the changes made by others whilst we have been working on our change.  This ensures we are compatible and not blindly forcing a breaking change into the repository.  Right-click on the project and select Team->Update.  Obviously in this case no one else has made any changes yet.  But typically at this stage we would resolve any conflicts and re-test
our changes to ensure they are still good.  Then we know we are fit to check in.  Right-click the project and select Team->Submit… 

Add a submission comment and click OK.  Note that the SVN modified indicators all disappear and your changes have been submitted into the
repository.

In the meantime the developer that imported the project is now making changes too.  Let’s switch to his workspace and also make an edit to the description of the dar install folder parameter.

Resolving a Conflicting Change

You’ll notice that both developers have now changed the dar folder install parameter artifact.  The second developer is going to be made aware of this when he attempts to check his changes in. 

So still as the second developer do your merge out.  Right-click on the project and select Team->Update.  SVN will attempt to update your workspace.  It will grab any new, non-conflicting changes and attempt to resolve any conflicts.  It will update your project with the new format artifact.  However, it will be unable to resolve the conflict that has arisen with the dar folder install parameter.  You’ll be notified with the following dialog:-

Click OK to close the dialogs.  Now right-click on the project and select Team->Synchronize with Repository.  A dialog will pop-up asking if you want to open the Synchronize Perspective which is a collection of views for helping with synchronization tasks.  Choose Yes and the perspective will open:-

Right-click on the dar folder install parameter, the artifact that has the conflict, and select Edit Conflict.  This will open the XMI versions of the local and repository file highlighting the conflicts. 

The developer uses this editor to resolve the conflict in the normal way.  Once he is done he marks the file as merged by right-clicking on the artifact in the tree again and selecting Mark as Merged.  The artifact will be removed the file from the Synchronize view:-

Lastly, he right-clicks on the project and selects Commit and his changes, merged with others, are committed to the source control system.

Conclusion

In today’s post we’ve taken a look at the Subversive SVN Team Provider for eclipse and demonstrated how it can be used with Composer, unmodified, to share Documentum projects amongst a team of developers through an SVN source control system.

The same basic theory holds true except for the subtle differences between providers feature sets.  Over time I will try and demonstrate the same scenarios using CVS and Perforce.

In the meantime – Happy Composing!

Advertisements

Composer on Helios

I know that many of my readership do like to run Composer on Eclipse, opposed to running Composer the RCP product which is still based on Eclipse 3.4.  Composer the RCP product is a closed-box.  Composer on eclipse on the other hand is an open platform that you can extend through the software updates in order to leverage any of the multiple complimentary tool-sets that are out there.

So, to that end, a quick set of instructions on how to get Composer running on the latest version of Eclipse, 3.6, codenamed Helios.

Download and install the JEE version of eclipse from here.  The JEE version already contains most of the dependencies that Composer requires to run including EMF, GEF, etc.  Start it up and choose a workspace.  Once it has started the only additional package you need is the emf validation framework.  Goto Help->Install New Software…  Choose the “All Available Sites” or “Helios” in the “Work with” drop down and in the filter box type “emf validation framework” and you should see something like this:-

Select the SDK.  Click Next to review the installation.  Click Next again and accept the licence agreement.  Then click Finish to install.  Once it has been downloaded and installed into your Eclipse run-time you will be asked to restart – go ahead and do this.  Once it has restarted the install is complete.  Now close Eclipse again as you now need to add the Composer plugins.

Copy all folders and jars beginning “com.emc.ide%” from the features and plugins folders of your existing Composer 6.5 install into the dropins folder under a /composer/eclipse path.  It should look like this:-

Now restart Eclipse one more time and navigate to Help->About Eclipse to confirm the Documentum logo is there as shown in the following image:-

And your done.  As always the obligatory support statement. Composer isn’t officially supported in this configuration- although technically there is no difference.  Any issues you did find would need to be reproduced on Composer RCP before Tech Support would accept them.

Lastly, a small request from me.  Before I left on my LOA and now that I am back I am always actively encouraging EMC to host and support Composer as a set of plugins from an update site, like the rest if the Eclipse community, as well as Composer as a product.  But I am just one of a few voices saying this within EMC who obviously weigh our opinion up against the cost of hosting the update site.  So if you would like to consume Composer from an update site, if you would like Composer to be an open -platform it is important that you let EMC know this by telling them directly or by commenting here.

Ok that’s it.  In future posts I show you how you can leverage some of the complimentary tool-sets I mentioned earlier and that you now have available to you.  And obviously feel free to experiment and let us know what works for you.

Happy Composing

Hello Again!

Hi Folks,

After 14 months I’m back.  I didn’t leave EMC and return.  I took leave of absence in order to fulfill a commitment elsewhere.  

I’ve been back for a little under a month now.  A lot of things have changed, as you can imagine.  Sadly, a few colleagues have moved on.  You know who you are and I would like to take this opportunity to publicly thank them and to wish them all the best in their new positions.  I also have a few new colleagues and I would like to say hello to them.  I look forward to working with you.

I feel like I am getting my feet back under the table so my normal blogging service can now be resumed.  I have a couple of Composer posts lined up and I will hopefully be able to start blogging about all things XCP in the near future, stay tuned.

Cheers,
_Paul