Documentum Composer: Integrating BOF Development into your workflow

A few colleagues have recently asked me what the current best practice for integrating BOF development into your workflow is, using Composer.

If it isn’t immediately obvious why this is an interesting question then it is because the development of a BOF (Business Object Framework) Module spans the disparate worlds of java development, for the module definition and implementation, and of Composer for the artifacts, for packaging and deployment.  More often than not I observe projects where one IDE is used to develop the modules and another is used for developing the artifacts.  Or worse still some other process is used for creating the Documentum Artifacts instead of Composer, normally involving copious amounts IAPI and IDQL.

So, what I want to do here is describe how you can set up a Documentum Composer project to use an ant builder (and ant script) to package a module implementation and associate it with a jardef artifact thus seamlessly bridging the java and artifact worlds and allowing you to keep all your development under one roof, eclipse in this case.

A Documentum Composer project is obviously the natural home of your artifacts but every Composer project is in fact also a java project. So, with this in mind, let’s dive into the details.

First create (or open) the Composer project that will contain your java and artifacts. In its simplest form, a BOF Module is a module definition associated with a a jar definition. Both are Documentum Artifacts, So, let’s create those.

File->New->Other->Documentum Artifact->Jardef. Name it mymodule_jardef. After the editor opens on your new artifact select this jardef type as Interface and Implementation because our jar will contain both classes and their interfaces.

Next create the module definition. Choose File->New->Other->Documentum Artifact->Module. Name it mymodule. After the editor opens on your new module artifact, associate the jardef with the module. To do this make sure the General tab is selected click the Add button associated with the implementation jar panel. Select your mymodule_jardef artifact from the list (if this is a new project it will probably be the only jardef in the list).

Now if you look in your Problems view you’ll probably see a problem marker for you module artifact (if you don’t see any problems its probably because auto-build is off – make sure you build your project and you’ll see it appear). The marker is because we haven’t set the module’s class name but that is because we haven’t got any java yet. Ignore it for now as we’ll add the java in a minute and resolve this after.

Before we can create our java we need to slightly reconfigure the project’s build path. At the moment everything is being built into a bin folder. However, we want to separate the java from the artifacts. You won’t see the bin folder in the Documentum Navigator view but you will if you open another view like Navigator (Window->Show View->Navigator). Right-click on the project and select Properties and then Java Build Path and then select the Source tab. Make sure the “Allow output folders for source folders” checkbox is checked and then edit the output folder for the src folder to point to a classes folder as I have done here. When you click browse you’ll get a change to create the new classes folder:-

Once you’ve done that, click OK to close the dialog.

Right click on your src folder and select New->Other->Java->Interface to create an interface called IMyModule in package “my.module”, as follows:-

And then give the interface a method declaration:-

package my.module;

public interface IMyModule {
public void sayHello();
}

Next follow the same procedure to create a class this time called MyModule also in package “my.module” and make it implement IMyModule, as follows:-

And give it an implementation for the say hello method:-

package my.module;

public class MyModule implements IMyModule {

public void sayHello() {
System.out.println(“Hello World!”);
}
}

So, you should end up with something like this in your Documentum Navigator:-

The project’s java builder will take care of compiling this interface and class for us. What we need to do though is package them in a jar so we can associate that jar as the content of the Jardef artifact that we created earlier. To do that we want to add a new (ant) builder to the project that calls an ant script. This will take care of always packaging the java into a jar. Create a file in the root of the project and call it buildJar.xml then cut and paste in the following standard ant script:-

<?xml version=”1.0″ encoding=”UTF-8″?>
<project name=”Jar’s the project” default=”main”>

<target name=”main”>

<delete file=”MyModule.jar” />

<jar destfile=”MyModule.jar” basedir=”classes”/>
<eclipse.refreshLocal resource=”your project name goes here“/>
</target>

</project>

Note that the jar task will jar up all classes in classes folder which should be the one we set as our output folder just now. And also remember to put the name of your project into the resource attribute on the eclipse.refreshLocal task otherwise your jar might not show up your view after it is created.

Next, add the new ant builder to your project. Right-click the project and select Properties->Builders. Click the New… button and then select Ant Builder. Click OK. This will launch an ant invocation dialog. Give your builder the name Jar Builder. Browse the workspace and select buildJar.xml as the buildfile:-

Then select the Targets tab and add main as the target for an autobuild:-

Click OK and then select the newly added Jar Builder and move it up in between the Java Builder and the Documentum Artifact Builder:-

Click OK. Assuming auto build is on for you, you should see the project build at this point (if it isn’t invoke a build). You’ll see the Jar Builder doing its stuff in the Console window and you should see MyModule.jar appear in your navigator:-

So now we are ready to hook the jar up to the artifacts. The first thing to do is open your jardef artifact and using the Browse… button associate your jardef with some content. It doesn’t matter what that is, this action just triggers the creation of the relevant elements in your jardef artifact’s XMI. I just selected a jar file that was lying around in my Temp folder. You can choose anything.

Save and close the editor. Next re-open the artifact but this time open it with a text editor. Right-click the artifact and choose Open With->Text Editor. You should see something like this:-

<?xml version=”1.0″ encoding=”ASCII”?>
<Artifact:Artifact xmi:version=”2.0″ xmlns:xmi=”http://www.omg.org/XMI” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:Artifact=”http://documentum.emc.com/infrastructure/12012007/artifact” xmlns:dclass=”http://documentum.emc.com/artifact/12012007/dclass” xmlns:ide=”http://documentum.emc.com/artifact/12012007/jardef” urn=”urn:com.emc.ide.artifact.jardef.jardef/mymodule_jardef?artifactURI=file:/C:/Temp/Eclipse33ScratchWorkspace/DocumentumProject/Artifacts/mymodule_jardef.jardef” categoryId=”com.emc.ide.artifact.jardef.jardef”>
<dataModel xsi:type=”ide:JarDef” objectName=”mymodule_jardef” contentType=”java” jar_type=”Interface and Implementation”>
<objectType xsi:type=”dclass:DClass” href=”urn:com.emc.ide.artifact.dclass/dmc_jar?name=dmc_jar#//@dataModel”/>
<aspectName href=”urn:com.emc.ide.artifact.aspectmoduledef/com.documentum.fc.bof.bootstrap.DfModuleItemChangeMonitor?aspectname=com.documentum.fc.bof.bootstrap.DfModuleItemChangeMonitor#//@dataModel”/>
<resource xsi:type=”ide:JarResource” jarFile=”//@contentStore/@contentEntries.0/@value”/>
</dataModel>
<viewModel xsi:type=”Artifact:DefaultArtifactViewModel”/>
<contentStore>
<contentEntries key=”test.jar”>
<value filePath=”content/48/513126848/test.jar”/>
</contentEntries>
</contentStore>
</Artifact:Artifact>

I’ve bolded the entries that have just been created by importing some content.

The filePath attribute of the value element is actually just a project-relative path so modify this to point to your jar file, as follows:-

<value filePath=”MyModule.jar”/>

And the contentEntries key is arbitrary. Rename this value to MyModule.jar as well. When you view this again through the jardef editor you will see that it looks like it has the right file attached.

Save and close the file again.

That has now associated your jar file with your jardef artifact which bridges the gap between the java and artifact worlds.

Now finally we can resolve that problem marker that appeared earlier. We need to set the module’s class name. Open the module definition editor for your module artifact and choose the Select… button next to the class name field. Highlight my.module.MyModule and click OK. You should know have something resembling this:-

Save and close the editor. You should see project rebuild and the problem marker disappear as we have now resolved that issue.

And that’s it. You are now all set. Your module artifact is associated with your jardef artifact which is in turn associated with your jar which packages your java classes. Your Documentum world and your java world are joined. No more dual development or IAPI scripts. You can edit your java to your hearts content from this point forward. If you work with auto build on then this will automatically build your java, package it and have it associated with your jardef so that when you are ready to test your module you can just install the project it into a Repository. Dar (the distributable package that is produced by a Composer project) installation is a completely repeatable process so you can install time and again and the installer will work out what needs adding and what needs upgrading. So, you can modify you java, re-install, test over and over.

Obviously what I have shown here is an integration based on a plain old BOF module. But of course BOF Modules come in many flavours. You can split your implementation and interface jars for example. And then there are the other types of BOF module as well; TBOs, SBOs, behavioural aspects and aspects with attributes. The basic principles that I have explained here will work for them all and give you a seamless & automated workflow.

It is also a one-time only gig as well and once set up you can share it with all the other engineers by placing the project in your source control system.

Happy composing!

Advertisement