Archive for the ‘Documentum Foundation Services’ category

Creating a DFS Services Client using Documentum Composer

July 3, 2009

One of my readers left a comment saying that my previous post left him high and dry when it came to creating the client project for testing his service.

So I put this very quick post together to describe it for him and hopefully for others too.

First this to note here is that there are lots of ways to create a DFS Client spanning both Java or .Net.  This is just one way using Documentum Composer.

So where did the previous post end up.  Well we had created a Documentum Project and within that created a DFS service, exported it as a service archive and deployed it onto a suitable application server. 

So what next?

Create yourself another Documentum Project (File->New->Other->Documentum Project).

Next create yourself a lib folder and in it import (Import->File System) your services remote jar.  This will have been exported at the same time as your service archive.  If you called your service archive samples for example then you would look for samples-remote.jar.

Once imported add it to your java build path (<project>->Properties->Java Build Path->Libraries->Add JARs…  Navigate to your remote jar within your client project and select it.  You should end up with the equivalent of this:-

image

You also want to make sure you have the right DFS client class path configured.  So whilst you are on this dialog.  Select the “DFS Services Library” build path entry and click Edit…  Select an appropriate library type for your scenario.  I’ve chosen “DFS Remote Client Library with UCF”:-

image

Click Finish.

Finally you need to write some code to call your service.  There are lots of contexts that your code could execute within; a Main class, a java application, an eclipse application, lots of others too.  I’m a big fan of test-driven development so I like to create Junit tests as these can be automated later and become part of the applications test suite.   Let’s create one of these (File->New->Other->Java->Junit->Junit Test Case):-

image

Give your Junit test a Package and a Name and make sure you’ve chosen to create a constructor stub.  Don’t worry about the super class warning – just click Finish and you should see this dialog:-

image

Obviously we do want to add Junit 3 library to the project’s class path so choose to perform that action.  Click Ok. 

Composer should do that for you and open your newly created Junit test case in the java editor.  We now need to add our service orchestration code.   Add a method called test with the following signature shown:-

image

And then add your orchestration code to that method.  If your not sure how to get started with this then a great place to start here is the client code that ships with the DFS SDK.  Cut and paste in a sample remote client and re-purpose it for your needs by changing the service related calls to use your service.  I’m actually using the DFS Hello World sample for this article.  As you are adding code, especially if you cut and paste a sample, you’ll end up with a bunch of problem markers:-

image

Because we already configured the project with a DFS class path you can hover over the problem marker in the sidebar and use the quick fix to add the necessary DFS imports.

A good tip here is to note that the moduleName and contextRoot (in the code sample above) must match the equivalent settings that you configured for your services project and that are also specified in the Export Service Archive dialog:-

image

That is pretty much it.  Make sure your services are deployed and that the server is running and the wsdl for each service is available.

To run the Junit test right-click on it in the project explorer and select Run As->Junit Test.  This will execute your test case using the Junit test framework and display the results.

If you want to debug the code then set a break point in the code and select Debug As->Junit Test instead.

Alternative

Now it is important to note that DFS supports two modes of invocation; remote – as we outlined above.  But it also supports local invocation too. 

This provides us with an alternative way to test our service code with less fixture than the remote alternative; i.e. without having to deploy it to a server.  

First we also need to add some of the services’ resources to the services project’s class path so that the DFS runtime can find them.  The Ear is configured in such a way that these same resources are available on the class path when the Ear is deployed on an app server.  We are just mimicking this configuration. 

So right-click on your services project and select Properties ->Java Build Path->Libraries.  Click Add Class Folder.  Navigate down your services project.  Expand the Web Services folder and the bin folder.  And check the gen-rsc folder.  Click Ok.   You should see this folder added t0 the build path:-

image

That’s the services project configured.

Now create another Documentum client project.

This time round make sure you add your service project to the Java Build Path (<client project>/Properties->Java Build Path->Projects):-

image

As before edit the type of DFS Library Path but select “DFS Local Library”.

There is no need to add the remote jar as we will pick up the service classes directly from the project.

As before add the Junit Test Case.  If you get any compilation errors then quick fix them.  Note, that when you add your services code you must call getLocalService instead of getRemoteService AND you don’t need to register the service context with the ContextFactory ahead of time.  So your service invocation code simply becomes:-

ContextFactory contextFactory = ContextFactory.getInstance();
IServiceContext context = contextFactory.newContext();

ServiceFactory serviceFactory = new ServiceFactory();  
IHelloWorldService service = serviceFactory.getLocalService(
               IHelloWorldService.class, context);

And that’s it.  You are ready to go.  Right-click on the Junit class in the project explorer and select Run As (or Debug As)->Junit Test.

Conclusions

So we’ve walked through creating a remote DFS Consumer and looked at an alternative for creating a local DFS consumers that leverages DFS’s local invocation facility.

As always I await your feedback.  In the meantime…

Happy Composing!

EMC Documentum Developer Edition

May 14, 2009

Today’s a first for EMC.

For the first time ever you can download a completely free version of the EMC Documentum for development, the EMC Documentum Developer Edition.  The one-click install includes the Content Server, DFS, Composer, DA and Webtop.  All the tools you need to develop enterprise content-centric applications.

To compliment this we’ve also launched a new developer-oriented community.

Enjoy and as always happy composing!

Documentum Composer: Smart Containers

January 16, 2009

My colleague David Louie, the Composer product manager, posted a nice demo on the EDN site demonstrating how to build and use a smart container.

One way toconsider a smart container is as a composite application object model.   These can be defined in Composer.  WDK Webtop includes some generic runtime support and together these can be used for rapid prototyping.

From this demo you can hopefully extrapolate either WDK Webtop customizations adding specific runtime support for the Police Case Folders (i.e. File->New-> Police Case Folder, etc) or even a purpose built rich client bound to DFS web services, generated from the smart container model!

Anyway, here is the EDN page.  I recommend you take a look.  The demo is the .exe link at the bottom of the page.

Hat tip to Dave for producing this.

Happy Composing!

Creating DFS Services using the Eclipse IDE for Java EE Developers

August 29, 2008

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!

Creating DFS Services using Documentum Composer

August 11, 2008

I’m not sure how many people realize it but when you create a Documentum “artifact” project within composer, it is also a “dfs services” project.  If you right click one of your Documentum projects and bring up its properties, then select the Java Build Path, then the Libraries tab you should see something similar to this:-

image

An if you select Properties->Builders, you should see something like this:-

image

When an “artifact” project is created it also adds all the necessary DFS resources to allow you to develop Documentum services.  It will deploy a copy of the DFS SDK to your core project (incidentally this is why creating the first project in a workspace takes a little longer than you might expect) and add the DFS Services Library to your project’s java build path.  And add a DFS Builder for building your services.

Creating a Service Consumer

Just as a quick aside if you do need to create a consumer, select the “DFS Services Library” entry and then select Edit, you should see something like this:-

image

As you can see there are in fact 4 flavours of DFS services library.  The first, and the default, is concerned with developing services (today’s topic).  The remaining three are actually concerned with developing service consumers.  They are pretty self-explanatory.  The only one that perhaps requires a little explanation is the last; “DFS Local Client”.  You add this type of library to projects that are acting as “functional tests” for your services projects.  Typically, you create one or more of these “functional test” projects in the same workspace as your services projects and configure them with this type of library.  This then allows you to debug from the client into the service and back again without having to deploy to a server.  A useful feature.  I will talk more about developing service consumers in a future articles.

Building a Service

OK, so back to developing the services themselves.  As you can see your project is all set up for service development.  Now you need to develop a service.  As you will probably all be aware there are a couple of flavours of DFS service; one based on a POJO and another based on a BOF SBO (service-based object).  They are, in fact, very similar and are just annotated java classes.  You can read more about DFS and its annotations from the DFS developer’s guide.  I won’t go into these here.  We’ll use the POJO variant here.  And for convenience we’re going to use one of the samples provided in the DFS SDK; <DFS SDK install dir>/samples/HelloWorldService.  All we need to do is navigate to <DFS SDK install dir/samples/HelloWorldService/src/service folder and copy the top level folder of the source tree, “com” in this case.  Then paste it into the the /Web Services/src folder of your Documentum project.

Once you drop these sources packages and class files into the Web Services folder, and assuming that you have “automatic build” turned on, then you should see the DFS Builder leap into life and attempt to build the service.  In your Console view you’ll get a build report:-

image

And if you open the standard Navigator view (Window->Open View->Navigator) and navigate to the Web Services/bin/gen-src folder you should also see a set of generated source.  This is actually a jax-ws web service that has been generated from your POJO service.  And under the classes folder you should see a set of classes and wsdl.  These classes are an aggregate compilation of your POJO (and associated classes) and the generated jax-ws web service.  The wsdl is obviously just standard wsdl also generated from your POJO:-

image

If for some reason your service fails to compile then you will of course get all the same familiar productivity tools for dealing with these issues that you have for plain old java development.  For example you’ll get errors and warnings reported in your Problem view:-

image

And just so you know the DFS Builder does support incremental builds and will only rebuild services that have changed since the last build so it should be reasonably efficient.

Testing the service

So now we’ve reached the point where we have a service that needs testing.  There are two approaches to this.  The first is to create a parallel test project with Junit tests that exercise your service.  To facilitate this your test project would be configured with the local client library, as described above, so that it can make local invocations to your service.  This project should of course be placed under the same version control as your services project.

The second approach is to export your services as an ear, deploy it to an application server and exercise your service again via another project capable of making remote service invocations.  Before you do this though you must remember to set the archive’s context root and module name as both of these affect the eventual URL of your service.  This is a one time deal though so just right-click on the project and select Properties->Documentum Project->DFS Module:-

image

Just so you are aware.  Typically all EMC DFS services share a context root of “services” and a module name that describes their general function.  Core for core services, bpm for business process, etc.  These will then be available via URLs such as http://localhost:8080/services/core… and http://localhost:8080/services/bpm…

Once these settings are made you can export the service.  Right-click on the project and select Export->Documentum->Export Service Archive:-

image

The archive name and context root should be defaulted for you from your DFS Module settings page.  Choose an output folder.  Uncheck the Generate Publish Manifest.  This is only required is you want to publish your services to a UDDI registry using the DFS tools.  And click finish.  This will produce your ear file.  Once you are in possession of the ear you can deploy it onto your app server using the appropriate app manager console or by dropping it into the hot deploy folder.  Whichever works for you.  Once you have it deployed you can perform a quick sanity check by requesting the service’s WSDL document by requesting something like http://localhost:8080/services/helloworld/HelloWorldService?wsdl.  Assuming you get back the WSDL document (that matches the one that was generated by the builder earlier) then you are good to go.

Next you will need to create yourself another test project.  But this time configure it with one of the two available Remote Client library options, depending on your content transfer requirements.  Again, creating Junit test cases I find is the quickest and easiest.  These can be rolled up into test suites and all can be invoked easily enough through the Composer (eclipse) UI.  And once again, if you can standardize this process across your development team then you can check this test project into source control right along side your services project.

In Summary

In summary we have walked through the out-of-the-box capabilities of a Documentum project with respect to creating DFS services.  Every Documentum project has the capability to host the development and testing of DFS services.  There are four libraries that are at your disposal for development and testing.  Each project has an incremental builder that is capable of automatically building your services.  And finally there is an exporter that can produce an ear file containing your services that is ready for deployment onto any app server.

Looking forward, in future articles I will talk more about another development option which leverages both Composer’s and WTP’s capabilities.  This option gives you far greater control over the contents of your ear and brings remote debugging of your services to your IDE.

In the meantime, happy Composing.


Follow

Get every new post delivered to your Inbox.