Using Documentum Composer to streamline the BOF2 Development Process

In a previous post I introduced one alternative for performing integrated BOF development within Composer. 

For the uninitiated, in BOF2 class loading is performed by DFC using a special class loader.   This allows module (type, aspect, service, …) implementations to be stored in the Repository and served up to clients upon-demand.  This allows you to leverage the power of the Content Server (version control, etc) on your Java modules.  Overall this is a nice feature and it ensures you get the right behaviour for the aspects, types and services that your application uses. 

However, it does complicate the development lifecycle as you have to package and deploy your modules to a development repository before you can test them.  For IDE debugging this can be a nuisance.

To assist during development there is a feature built in to DFC that allows you to skip the Repository class loading step for specific modules.   Let’s take a closer look.

Create the Module

As per my previous article create a project and within it your module. 

A quick overview follows;

1. the module’s interface should extend the marker interface com.documentum.fc.client.IDfModule,
2. the module’s implementation should extend com.documentum.fc.client.DfSingleDocbaseModule (or equivalent) and implement your interface,
3. the project should include an additional ant builder that executes a simple ant script that builds your module jar(s) into your jardef artifact’s content directory
4. finally your jardef artifact XMI should be modified to link to the jar(s) (as opposed to the dummy one(s) you had to import)

Create the Module Test

Now create another Documentum project to host your module’s test code.  The reason we create a Documentum project as opposed to, let’s say, a regular Java project is that a Documentum project will be set up with a DFS library already on its classpath.  This library contains DFC and as result is a very convenient leg-up as we are just about to create some DFC-based test code.

But first create a plain text file and call it something like bof.registry_file.properties.  In the file add the following line:-

mymodule=module,my.module.MyModule

where “mymodule” is the name of your module as specified in the Module Artifact:

“module” specifies the module’s type.  Other values could be “aspect”,”type” or “service”.

And “my.module.MyModule” is the fully qualified class name to your module’s implementation class.  The same class name is specified in the class name field of your Module Artifact. 

This file is a local module registry.  You can add additional lines to suit for each module that you wish to debug in your IDE.

Next create a JUnit test case (File->New->Other->Java->JUnit-> JUnit Test Case) and add some simple test code:-

And as you will no doubt be aware for DFC to really work we need a dfc.properties file.  Create a folder in the root of the project and call it something like “rsc” or “resources”.  Import (or create) a dfc.properties file into this folder and make sure that it is configured with the docbroker that is hosting your test Repository.  Add this folder to the project’s Java Build Path.  Right-click on the project, choose Properties->Java Build Path.  Select the Libraries tab and then hit the Add Class Folder… button and select the folder you just create and click OK, as follows:

Next we need to define a launch configuration.  To do this, from the Menu choose Run->Debug Configurations…  Select the JUnit category and then hit the New button.  Give the new JUnit launch configuration a name, “BOF Test – local invocation” for example.  Select the Arguments tab.  In the VM Arguments field enter “-Ddfc.development.bof.registry_file=${project_loc}/bof.registry_file.properties” which sets a system property upon launch.  This particular property, dfc.development.bof.registry_file, will be checked by DFC and, if set, instructs it to fulfil any request for a module that is also specified in the local registry file using a local class loader instead of its special Repository class loader.  The net result is that it will load the class from your project:-

Now select the Common tab.  In the Save As panel select the Shared file radio button and browse to a suitable location within this project.  This will save the launch configuration in the project which means you can place it under source control in order to share it with others in your team:-

Click Apply to save the launch configuration.

I would also recommend that you create a second launch configuration, call it something like “BOF Test – Remote Invocation” and on this configuration remove the system property.  Make sure you save it to the same location as the local invocation configuration.  This will allow you to test in local mode or remote mode.  There is good reason for doing this as I will explain shortly.

Finally, as a one-time only operation we need to install the module so that it is registered properly with the Repository.  Right-click on your module project and select Install Documentum Project.

That’s it.  You are now all set.  To test your module.  Right-click your test project and choose Debug As… (or Run As…)->Debug Configurations…  Make sure the local invocation launch configuration that you created earlier is selected and hit Debug.  Or simply use the toolbar short cuts buttons.  Once its run.  Make a change to your module’s implementation.  Be sure not to install the project again and re-invoke the launch configuration.  By setting breakpoints in your module implementation you will be able to see you modified implementation being executed.

In Conclusion

This article demonstrates how to streamline the BOF development process.  It also demonstrates how to create launch configurations and how to share them with your team by saving their definitions in the workspace and using source control.

One very important note.  Be aware that this local invocation is really a bit of a cheat and that its usage can mask packaging problems.  The fact that the class is visible in your project does not necessarily mean it will be visible with proper BOF class loading.  To a large extent DFC and Composer try to negate this through the insistence of the one-time only install and through the build process respectively which catches errors.  And also why I recommended creating a remote invocation launch configuration as well as a local one.  But this might not stop packaging problems creeping if, let’s say, you subsequently modify your module’s packaging structure.  The long and short of it is that whilst the workflow outlined here can be a real productivity boon for your developers your Documentum applications should also always go through a proper QA cycle.

As always happy Composing…

Advertisement