My client wanted me to develop a webservice consumer that sends it requests to a Documentum webservice.Â I had some previous experiences with LotusScript webservice classes generated by Domino automatically, but this turned out to be a non-solution, because I had to access the SOAP header.Â I had to enter the Scary Java World for a proper alternative… It became quite a queeste!
Java solutions I tried and what went wrong (in a nutshell)
- Apache Axis implementation in Domino: too restricted. I needed to add authentication to the header, but the Axis implementation doesn’t implement the setHeader method.
REMARK: I must admit some posts on the web suggest it might be possible, but the Java new(bizzy)bee here suggests it isn’t ;-):
- Stubby: couldn’t get this one to work in Domino 8.5, the classes aren’t generated.Â A pitty, because they explain how to add headers…
- Apache Axis full implementation: too complicated/outdated (last version: 2006!) compared to:
- Apache CXF: Stephan Wissel made me believe this could be a neat solution.
Why use CXF?
The short answer: once you get it to work, it’s easier (even for Java virgins), has more possibilities and is up-to-date.Â The long answer can be found in Stephan’s interesting post.
Although Stephan’s article was of very great help, for the absolute beginner (me) it lacks some building steps. That’s why I decided to write out my own struggling.
Domino CXF step-by-step
What you need
- The latest binary distribution of CXF
- Eclipse IDE for Java EE Developers
- Java JDK or JRE 6 or higher
Create the CXF Java classes from a WSDL with wsdl2java
- Save the wsdl you want to use locally.Â For ease of use, copy it to your CXF install directory in the subdirectory bin.
- From the command prompt, “cd” yourself to subdirectory bin in your CXF install directory.
- -client creates an example class that can be a good starting point for your java (agent) code.
- -exsh true is only needed if you want access to the SOAP headers (f.e. to provide a username/password to the service).
- If you omit -d targetdirectory the classes are generated directly in the same (bin) folder.
- If the program throws errors: maybe your %JAVA_HOME% needs to be set:
- You can test this with echo %JAVA_HOME% at the command prompt.Â It should return the directory where you installed the Java JDK/JRE.
- If it doesn’t, enter SET JAVA_HOME=path-to-SDK at the command prompt.
Create the code in Eclipse (if I can make it there, I’ll make it anywhere)
- Create a new Java project (File – New Project – Java Project) and give the child a name.
- In Windows – Preferences – Java – Installed JREs add the dominodir\lib\etc directory as standard VM and make it the default. It means you’ll use the Domino Java VM, so you can be sure you don’t use stuff different from the Notes Java distribution.
- Choose Project – Properties – Libraries – Add External JARs and add all jar’s from the CXF lib subdirectory.Â That way we can use the CXF classes in our project.
- We can easily add the CXF classes generated from our wsdl by drag the root folder from the generated classes in the previous chapter, to our Eclipse project:
- You should find the example client class in your Eclipse project folder in the subdirectory you just dragged to the project in 4. The classname looks like xxx_Client.java.
- Open the class.
- In the generated example client the wsdl location is handled differently.Â For now, do it like this:
There are probably better ways to point to the wsdl, but this one is easy enough for now :-).
- Scroll down and look for the functions(s) you need.Â The function arguments are already there, only they are all set to “” or null.Â Adjust the parameters to your needs (
is your friend if you want to see the declarations).
- Remove or remark the other functions, we don’t need them now.
Do not proceed to the next step if you can’t run it in Eclipse yet.Â Importing in Domino won’t fix the errors ;-).
Generate the webservice jar
Â Â Â permission java.lang.RuntimePermission "setContextClassLoader";
Â Â Â permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
Finally, a webservice consuming agent
- Â Create a new agent, type Java.
- Import the CXF jar you generated with Import – Archive.
- Open JavaAgent.java for editing: copy paste parts of your Eclipse client example code to the agent (this screenshot might help you).
Notice you don’t have to add all imports you needed in Eclipse.Â And you still have to add the WSDL_URL.
- Also add the function(s) you need.Â Start by hardcoding the function arguments.
- Important: agent security settings! The runtime security level of the agent should be 3Â -Allow restricted operations with full administration rights.
- For an easy start, print the results to the console (System.out.println(“
“)), or debug.Â Open Tools – Show Java Debug Console.
The beauty? We didn’t have to import any external jar files (apart from the CXF generated one) and we don’t have to mess with the lib\ext directory of the Domino server!
I hope I covered most aspects of the process, so that even Java dummies are able to create a client ;-).