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:-

image

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:-

image

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:-

image

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.

image

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!

Advertisements

10 thoughts on “Creating DFS Services using the Eclipse IDE for Java EE Developers

  1. Just wondering why it is always so difficult with Documentum products to get just a first development environment set up…?! 😦

    • Hi Ingo,

      I know it is a pain having to go all through this.

      This post was doing two things really.

      Firstly, I felt it would help the subset of our developer community who needed more control of their DFS services.

      Secondly, researching and writing it was helping me distill my thoughts on the next generation of DFS integration that leverages WTP.

      We are beta testing this internally as we speak. I have been meaning to write a post on it which I will do soon to give you guys a heads-up about whats coming shortly in this regard.

      Of course I would also love to hear about anything else specific that you need or would like.

      Many thanks
      _Paul

      • Hi Paul,

        thanks for the info. There is hope… 😉

        I have been doing this before defining the dev setup for other Webtop developers so I know it is not easy.

        If you need a beta tester… you should be able to see my email with the post.

        Cheers,
        Ingo.

  2. Hello Paul
    I tried to compile your template projects, but allways I get following error:
    BUILD FAILED
    G:\_projects\DocumentumCoreProject\dfs6.5\dfs-build.xml:179: javax/tools/JavaFileManager$Location
    at com.emc.documentum.fs.tools.GenerateModelTask.executeTask(GenerateModelTask.java:93)
    at com.emc.documentum.fs.tools.impl.ChainedExceptionReportingTask.execute(ChainedExceptionReportingTask.java:17)
    at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:288)
    at sun.reflect.GeneratedMethodAccessor5.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
    at java.lang.reflect.Method.invoke(Unknown Source)
    at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:105)
    at org.apache.tools.ant.Task.perform(Task.java:348)
    at org.apache.tools.ant.Target.execute(Target.java:357)
    at org.apache.tools.ant.Target.performTasks(Target.java:385)
    at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1329)
    at org.apache.tools.ant.Project.executeTarget(Project.java:1298)
    at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:41)
    at org.eclipse.ant.internal.ui.antsupport.EclipseDefaultExecutor.executeTargets(EclipseDefaultExecutor.java:32)
    at org.apache.tools.ant.Project.executeTargets(Project.java:1181)
    at org.eclipse.ant.internal.ui.antsupport.InternalAntRunner.run(InternalAntRunner.java:423)
    at org.eclipse.ant.internal.ui.antsupport.InternalAntRunner.main(InternalAntRunner.java:137)
    Caused by: java.lang.NoClassDefFoundError: javax/tools/JavaFileManager$Location
    at com.sun.tools.apt.main.Main.compile(Main.java:850)
    at com.sun.tools.apt.Main.processing(Main.java:95)
    at com.sun.tools.apt.Main.process(Main.java:85)
    at com.sun.tools.apt.Main.process(Main.java:67)
    at com.emc.documentum.fs.tools.impl.artifact.dfs.ServiceModelGenerator.runAPT(ServiceModelGenerator.java:157)
    at com.emc.documentum.fs.tools.impl.artifact.dfs.ServiceModelGenerator.generate(ServiceModelGenerator.java:122)
    at com.emc.documentum.fs.tools.impl.DependencyGenerateModelTask.execute(DependencyGenerateModelTask.java:65)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
    at java.lang.reflect.Method.invoke(Unknown Source)
    at com.emc.documentum.fs.tools.GenerateModelTask.executeTask(GenerateModelTask.java:89)
    … 16 more

    • Well javax.tools is a Java 6 package. And we have had problems in the past with noclassdeffounderrors when users are running Composer on a JRE instead of a JDK. So, by way of a large-ish guess, perhaps you are running JRE6 instead of JDK6?

      Actually I am not even sure if you DFS supports Java 6. As a rule Documentum is still Java 5. So actually I would recommend configuring your Composer on JDK5 and then re-trying.

      HTH
      _Paul

  3. Have you managed to run all of this inline? Meaning skip the package and deploy part but have Tomcat run the source right out of your workspace? (Could work as long as the interface stays the same and only the implementation get’s touched)

    • Theoretically this could work Ingo. I haven’t done it but you could set up tomcat with a webapp whose docbase points to the /WebContent directory of your services dynamic web project.

      It is always good practice to separate interface from implementation anyway. And I always have my dfs service classes delegate to actual implementation class as this streamlines the dfs build process and, in terms of inline development, will minimize the number of times that the service classes change.

      I have to say though Eclipse WTP has worked hard on their Server pieces and I have always found the synchronization to work reasonably well, for tomcat and BEA at least. So, setting up an inline development process would seem to run against this effort. I personally have always prefered to let WTP do it’s stuff.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s