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:-
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”:-
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):-
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:-
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:-
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:-
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:-
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:-
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):-
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!
Paul Warren 