This page discusses how you can get started using 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.
Unfortunately, you'll probably have problems at some point. This seems to be the nature of web services, which are governed by a wide range of loosely interpreted standards, not to mention that there are often several versions of the standards (1.0, 1.1, etc.) that are sometimes not compatible with each other. The version of the Axis library that is used by Notes/Domino 7 is also a little old, and it doesn't always support all the "latest" web service tricks.
One thing to remember in debugging problems: the Notes Java Debug Console is your friend. Just use the menu option File - Tools - Show Java Debug Console to open it up. It has the output of any text printed to System.out or System.err. It also accumulates the data even when it's not open, so when you open it up it will show all the old errors that happened too.
That being said, here are some common problems you'll run into:
You see a "java.lang.SecurityException: Exit with code 0" error in the Java Debug Console when you generate the stub files
This is actually not a problem, as long as the stub files are generated properly. It's due to the fact that the Axis stub generation program tries to make a System.exit call when it's done, and Notes doesn't allow that (which is a good thing, because we're not done at that point!). You can ignore this error.
Stub files are not generated after you click the "Generate Stub Files" button
This is almost always due to the fact that the WSDL file cannot be accessed for some reason. If this is true, you'll see a "WSDL file not found" message in the Stub File Errors box.
Can you access the WSDL file with your browser? Is there a firewall or proxy server that might be blocking your Notes client (sometimes you can get to the file with a browser, but when the Notes client tries to access it via Java it fails)? Do you have to log in somehow to see it?
Often times, if you actually can get to the WSDL file with a browser, you can just save it as a file to your local hard drive and point to the local file instead of the URL when you're generating the stubs. However, you may still have the same problems when you're actually trying to call the web service methods, so it's good to work out what's going on with the WSDL file first. If it's a firewall/proxy server problem, you'll need to talk to your network administrators...
Another cause can be that you're trying to point to a WSDL version 1.2 file. In this case, you'll see the following error in the Java Debug Console:
java.lang.Exception: WSDL/SOAP versions 1.2 are not currently supported
Not much you can do about that one. If Axis doesn't support it, it doesn't support it...
You get a java.lang.SecurityException error when you run your web service agent
If you get this sort of error when you run the web service agent with the Stubby code on your server:
java.lang.SecurityException: not allowed to make a socket connection to www.foo.com
it most likely means that you need to adjust the "security access" on the agent. Agents that access web services (by their very nature) make network connections, which is a restricted operation in Lotus Notes. To allow this sort of thing, you must:
Your web service agent runs but it gets errors
Check the Java debug console. Sometimes it's a connection problem. Sometimes you're pointing to the wrong server URL (localhost instead of the actual server?). Sometimes the method simply returned a Fault and you didn't catch it. Sometimes it's just Axis acting up and there's nothing you can do about it.
A common problem in testing is when you are running against a local web service in a Notes database and you forgot to start the HTTP task in the background. When this happens, you'll get the exception:
java.net.ConnectException: Connection refused: connect
The easiest way to start the local HTTP task is to go to the Forms list in Domino Designer, select a Form in the database, and choose the menu option:
Design - Preview in web browser - Default browser
This will start the HTTP task in the background and allow the local web service to be used properly.
This can also happen if a firewall or proxy server is preventing access to the service (even if you have the proxy server settings set properly in the Notes client, the Axis stubs will still try to access the web services directly, not through the proxy server).
Errors with services that return complex data types
If you access a service that returns a complex data type (normally only a problem with nested complex types), you may get an error like this:
org.xml.sax.SAXException: SimpleDeserializer encountered a child element, which is NOT expected, in something it was trying to deserialize.
Not sure what to do about that one I'm afraid. I've read in some places that upgrading to the latest version of Axis will fix it, but that's not necessarily an option here. I'm still looking for a good workaround...
How to detect Faults that are returned from calling a web service
All of the method calls to a web service will throw java.rmi.RemoteException exceptions if there is an error or a Fault is returned. You can catch faults by writing code like this:
try {
String result = service.SomeMethodThatThrowsAFault();
} catch (java.rmi.RemoteException fault) {
System.out.println("Oops, we got a fault:\n" + fault.getMessage());
}