Stubby - How It Works
This page discusses the inner workings of Stubby, a Lotus Notes database that helps you create Apache Axis "stub" files that can be used to call web services from a Lotus Notes 7.x environment. If you need more information, please see the main page.
Lotus Notes 7 introduced the ability to write native web services to run on the Domino server. While the web service design element is coded much like an agent, Domino actually uses a version of the Apache Axis libraries to provide web service capabilities.
Officially only the web service provider functionality has been exposed, but the client libraries are also packaged up in the distribution. This means that we can actually call Apache Axis client code natively from Notes 7, as long as we reference the correct libraries.
The normal distribution of Axis uses a package naming scheme of "org.apache.*". In the Notes client, these packages are found under "lotus.domino.*". If you modify your package references accordingly, most of the Axis client functionality can be used natively within an agent.
Hacks and Oddities
In the process of getting all this working, I had to work through a few hacks. For example:
- Axis uses a file called client-config.wsdd to configure itself when you try to run the stub client code. It looks for this file on the classpath. Because you don't always have access to the classpath on the client/server that's running this code, I had to override a protected method in the Locator class to manually feed a client-config.wsdd class into the Axis engine when it tries to start up. If you have no idea what that means, don't worry about it. Just be glad I did it for you.
- For some reason the Axis stub files that Notes generates try to throw lotus.domino.types.Fault objects in certain places, even though there is no such class! After the stubs are created, I have code that goes through each of them and fixes the references.
For web services that use SOAPAction headers, you will sometimes have problems because Axis will send the SOAP action URI in an HTTP header element called "HTTP_SOAPAction", but the service may be expecting the header element to be called "SOAPAction" instead. I write a little code in the appropriate areas of the stub files to also create a "SOAPAction" header to deal with those cases.
- In case you're ever trying to figure out how to make a Java agent write proper linefeeds to a text field, here's how you do it: write to the field using normal (\n) linefeeds in Java, write an Input Translation formula in the text field of "@ReplaceSubstring(@ThisValue; @Char(10); @NewLine)", and refresh the UIDoc to run the Translation formula.
last edited March 8, 2007