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!

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

Troubleshooting BOF Development Mode

One of my readers had some trouble getting his local BOF development working. 

No matter what he did he always got NoClassDefFoundError when DFC attempted to load his service class locally.

Turns out that his issue was an eclipse issue.  He had specified something like this as a vm-arg in his junit launch config:-

“-Ddfc.development.bof.registry_file=${project_loc}/bof.registry_file.properties”

And for some reason eclipse was not resolving the variable “${project_loc}” properly.

After he re-specified this setting with a fully-qualified path, everything worked as expected.

A good tip is that DFC will report, during start-up, some basic status about BOF development mode, as far as it is concerned. 

Look out for:-

“Error during initialization of BOF Development mode”

if something catastrophic happens, Or:-

“BOF Development Mode: can not find registry file {0}”

if DFC cant find the local registry file that it thinks it is looking for.  This was my readers issue.  Or (hopefully):-

“******* BOF Development Mode is enabled *******”

if DFC is able to load the registry file.

I thought I would put this out in case anyone else ran into same the problem.  And of course if anyone knows why eclipse is failing to resolve the variable then we’d all love to know that too.

Happy Composing.

Creating DFS Services using the Eclipse IDE for Java EE Developers

Composer’s out-of-the box DFS integration is currently aimed at the Developer with simple, as opposed to advanced, requirements for DFS.  Specifically, we’re talking about developers that only care about the services themselves (the basic developer) and don’t care about the package that the services come in (the advanced developer).  And for a lot of use cases this out-of-the-box capability is just fine.

However, there are some other use cases where you do care about the package that the services come in.  Perhaps you want to package everything in a war rather than an ear (because you use Tomcat for example).  Or perhaps you want to run some additional servlets or servlet filters alongside your services (or even JSPs!).  Or perhaps you have custom authentication and authorization requirements and you want to replace DFS’s authorization SOAP handler with you own.

Any of these types of requirement will mean that you care about the packaging your services come in as well as the services themselves.

Fortunately, the Java EE edition of Eclipse can help us out.  It adds new projects types such as the Enterprise Application project (ear project) and the Dynamic Web project (war project).  These projects will give us complete control over the contents of the ear, war & jars’s.

To compliment this it is possible to install the Composer plug-ins right into this edition of Eclipse as I talked you through here.  This is a pre-requisite for this article.

With the union of these two products we can now do some cool things like create Web projects with DFS services in them.  We can also significantly boost our productivity by leveraging Eclipse’s capability to deploy and test our ear and war projects on an associated application  server, without having to ever leave the IDE.  Eclipse supports most, if not all application servers either out of the box or via download.

To get you started I’ve created an attached a few blank templates projects which should give you the idea.

TemplateProjects1.zip contains a set of projects that will re-produce DFS’s existing packaging.  It comprises an Ear project with an associated Utility project (jar project) and a War project.  The utility project hosts the DFS builder and is where you would develop your services.  This is also visually denoted with the Documentum logo decorator on the project icon.  When exported this will produce a ear, with your service jar and an embedded war.  It should look something like this:-

You’ll notice that I’ve ringed the Ear associations in red.  The source file for a sample service in blue.  The generated web resources for the service (the wsdl, reference web.xml, app server specific config files, etc) in green.  Note these files in particular.  My recommendation is that you add a custom ant-based builder that copies (or merges) these files to the relevant locations in your War file.  Lastly, I’ve ringed, in pink, the DFS builder so you can see that it exists on the utility (jar) project.

TemplateProjects2.zip contains a Web project and a utility project.  No ear this time.  The utility project again hosts the DFS builder and is where you would do you service development.  When exported this would produce a War containing a services Jar.  It should look something like this:-

TemplateProjects3.zip contains a single Web project which hosts the DFS builder.  This time you do everything in the Web project including develop your services.  When exported this will obviously produce a single War and would contain everything DFS needs to run; the DFS runtime, JAX-WS runtime, your services, UCF, etc.  It should look something like this:-

With all of these project templates you’ll notice that they are suspiciously devoid of anything DFS related at the moment; runtime, JAX-WS runtime, UCF, etc.  I didn’t want to infringe any copyright’s with my employer.  I like getting paid .  So regrettably I will have to leave you this as a reader exercise.  Another approach of course would be to import an existing DFS ear that could act as a bootstrap.  It’s up to you.  But obviously these files need to be applied one way or another before you can think about deploying this to a Server.

I have also left out the Documentum Core Project.  Again, I didn’t want to infringe any copyright’s so before you import any of these templates make sure you have a 6.5 Documentum Core Project in your workspace.  The easiest thing to do is create yourself a dummy Documentum project which will force the creation of the core project if it doesn’t exist.

Debugging a Project

OK.  Assuming you have overlayed the remaining DFS files to complete your project structure.  You will now want to run or debug it.  First-time only you need to configure an appropriate server.  In the Server’s view right-click in free space and select New->Server.  Follow the wizard through to completion.  Typically you will configure a new Server entry based on an existing app server installation but some of the runtimes also support installation of a new app server instance as well, Tomcat being one.

With the new Server entry created in the Servers view you now need to associate the projects you want to run with your Server.  To do this you can drag them onto the Server from Package Explorer or you can right-click the project and select Run As (or Debug As)->Run On Server… or you can right-click the Server entry in the Servers view and choose Add and Remove Projects…

Once you have associated your project with your Server all that remains is to Start it or Debug it.  Right-click on your server and select either Start or Debug.

Obviously if you start your Server in Debug mode (as the above screenshot shows) any breakpoints you have set in your code will cause eclipse to break into the debugger when hit.

More Details (for the Curious only!)

Eclipse is very declarative in nature and most all settings are stored in special files in the project (.project, .classpath, etc) and we have tried to carry that practice on within Composer (.dmproject, .dfsproject, template, etc).  So, if you want to create one of these projects yourself then it is fairly simple process, as follows:-

1. Create your web services source tree.  If you want to use the DFS Builder’s defaults you must create folders /Web Services, /Web Services/src, /Web Services/bin/gen-src & /Web Services/bin/classes/.

However it is entirely feasible, and in fact probable within the context of a War or Jar project, that you will want to modify these settings so that Eclipse builds your service in the right place for your Jar or War (as I demonstrated in the with template #3).  You just have to tell DFS where you want to put your files.  To do this you need to edit .dfsproject file (see #2) and add the following attributes to the root element; sourcePath=”<project-relative path to dfs service java files>” (equivalent of /Web Services/src default), generateSourcePath=”<project-relative path indicating where to store generated source>” (equivalent of /Web Services/bin/gen-src default) and outputPath=”<project-relative path to compiled output” (equivalent of /Web Services/bin/classes/).  The settings used for template #3 therefore looked like this:-

<?xml version=”1.0″ encoding=”ASCII”?>
<dfsproject:Project xmi:version=”2.0″ xmlns:xmi=”http://www.omg.org/XMI” xmlns:dfsproject=”http://documentum.emc.com/infrastructure/04012008/dfsproject” version=”6.5″ sourcePath=”src” generateSourcePath=”src-dfs-gen” outputPath=”build/classes” dfsSdkVersion=”6.5″>
<module/>
</dfsproject:Project>

2. Copy in the following files from a dummy Documentum project; .dmproject, .dfsproject & template.  Modify .dfsproject, if required, as outlined in step #1.

3. Next, edit .classpath adding the following lines to match your DFS settings:-

<classpathentry kind=”con” path=”com.emc.ide.external.dfs.DFS_CONTAINER”/>
<classpathentry kind=”src” output=”<outputPath>” path=”<sourcePath>”/>
<classpathentry kind=”src” output=”<outputPath>” path=”<generateSourcePath>”/>

If you are outputting your source to the project’s default output folder then you can just omit the output attribute altogether.

This file determines your Java Build Path so you should be able to see these changes if you inspect the Java Build Path tab on your project’s properties dialog.

4. Lastly, edit the .project file and add the following bolded entries:-

<?xml version=”1.0″ encoding=”UTF-8″?>
<projectDescription>
<name>TemplatesProjects2Jar</name>
<comment></comment>
<projects>
<project>DocumentumCoreProject</project>
</projects>
<buildSpec>
<buildCommand>
<name>com.emc.ide.external.dfs.dfsbuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.wst.common.project.facet.core.builder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.wst.validation.validationbuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.wst.common.project.facet.core.nature</nature>
<nature>org.eclipse.jdt.core.javanature</nature>
<nature>org.eclipse.wst.common.modulecore.ModuleCoreNature</nature>
<nature>org.eclipse.jem.workbench.JavaEMFNature</nature>
<nature>com.emc.ide.builder.documentumNature</nature>
<nature>com.emc.ide.project.dmProjectNatureId</nature>
<nature>com.emc.ide.external.dfs.DfsNature</nature>
</natures>
</projectDescription>

Some of the other entries may be a little different, especially the natures, depending on the type of project that you are merging into.

When you save this file you should see the Documentum logo decorator added to your project and if you inspect the Builder properties tab you should also see the DFS Builder has been added.

In Conclusion

What we have looked at today is a technique for leveraging both Eclipse IDE for Java EE Developers, specifically its WTP features, and Composer in order to develop services within the context of enterprise & web applications.  This gives you as the developer complete control over the contents of your DFS package.  It also allows you to leverage the full power of WTP’s server runtimes & debugging capabilities.

Happy Composing!