Consuming Web services from a Lotus Domino Java agent


A Web service is a system designed to allow two or more computers to interact over a network. The main advantage of such a service is that it’s a standard solution for sending objects between multiple computers with different operating systems and application servers. For example, our company uses Web services to publish articles from a computer running the Microsoft .NET Framework to an IBM Lotus Domino-based intranet. We recently finished another project in which we exposed special reports as a Web service on a Lotus Domino 7 server. A Java-based application server read the reports server, and the only thing we had to negotiate was the Web Services Description Language (WSDL) file.

This article shows you how to create a Domino Java agent to consume a Web service. It uses Apache Axis to generate Java stubs and to read a WSDL file. We provide a sample database containing a Web service that you can use to follow along in this article. See the Downloads section for more information.

This article assumes that you are an experienced Lotus Notes and Domino application developer familiar with the new Domino Web service design element. To learn more about the new Domino Web service design element, see the developerWorks Lotus article, "Lotus Notes/Domino 7 Web Services."

Components of a Web service

A Web service consists of several components. These components include:

  • The WSDL file
  • A Service-Oriented Architecture (SOA)
  • Various protocols

The WSDL file

WSDL is the glue in a Web service setup. Each Web service publishes a WSDL file containing information about which methods and arguments it can handle as well as which objects the different methods return. Available with this article is a database (in this instance, a Lotus Domino 7 database) that contains a simple Web service.

Even if the Web service is simple, however, the WSDL file for that service is rather verbose. One reason for this verbosity is, of course, that a WSDL file uses the verbose format, XML. However, considering that the WSDL file contains a description of all objects that the Web service sends and receives, the size isn’t overwhelming. The WSDL file for the example Web service in this article has a Java class named ComplexClass, which is shown in the following code snippet:

<complexType name="MyComplexClass">
<element name="alpha" nillable="true" type="xsd:string"/>
<element name="calcA" type="xsd:int"/>
<element name="calcB" type="xsd:int"/>
<element name="result" nillable="true" type="xsd:int"/>

Service-Oriented Architecture

Service-Oriented Architecture (SOA) has been the buzz for the past decade. In brief, SOA is a software architecture that focuses more on the business than the common, technically driven solutions. It is basically a matter of designing the architecture to use Web services in a consumer-provider manner. The SOA approach is to separate the layers with consumers interacting with the business objects through the service layer rather than directly.

For more information about SOA, see the New to SOA page on developerWorks SOA and Web services.

Protocols that Web services use

A Web service message isn’t restricted to using HTTP. It can also use SMTP, Extensible Messaging and Presence Protocol (XMPP), or even FTP. The message, however, must conform to SOAP; otherwise, the receiving system has a difficult time interpreting the message. On older systems, you can find XML-Remote Procedure Call (XML-RPC), but SOAP is the correct protocol to follow these days.

The good thing about Web services is that you don’t need to go into the various protocols and standards: All that is taken care of by the application server and by the development tools. In this example, Apache Axis helps you with the WSDL interpretation and generates Java code stubs for you.

Sample databases

Before you start using the Apache Axis tools, you must have a Web service that publishes a WSDL file. In the Download section of this article, there are two sample databases: WebServiceConsumer.nsf and MyWebService.nsf. Their names suggest what they do. After you download MyWebService.nsf to your Lotus Domino 7 server, sign the Web service design element -- MyWebservice -- with an ID that can run restricted agents. WebServiceConsumer.nsf is for reference only.

Apache Axis

Apache Axis is a complete framework involving SOAP servers and many different tools for generating and deploying Web services. You use the communication part and the WSDL2Java method in this article. First, however, you must install Apache Axis.


Before you can build, test, and deploy the solution described in this article, you must have the following:

  • A Lotus Domino 7 server and IBM Lotus Domino Designer
  • The Java software development kit (JDK)
  • The Apache Axis framework

We assume that you have installed Lotus Domino 7 and that you know how to get a Java environment up and running. (The Resources section of this article provides links to all the necessary downloads.)

Table 1 shows the file structure used on our system. If you choose to replicate this structure, you can re-use the batch file and class paths mentioned later or choose to go with your own strategy. We use working names for each directory, so there is no mix-up. The batch file is variable driven, so you can easily change a line or two to make it work on your system.

Table 1. Suggested file structure
Working namePath
Server pathC:\lotus\DominoR7StandAlone
JDK version 2C:\java\j2re1.4.2_09
Apache AxisC:\java\Axis
Working directoryC:\java\consumer

Download and install Apache Axis

After you download Apache Axis, extract the package to the Axis directory. (See table 1 for suggested paths.) This article uses two features that Apache Axis provides. One is the communication classes that, in reality, you don’t really need to know anything about other than that you import them into your Domino environment. The other feature is the wsdl2java tool with which Apache Axis can read a WSDL file and generate complete Java stubs for all the required methods and objects.

You can launch a shell and start running the Apache Axis classes, but we find it inconvenient to start each command with a 100+ character class path. One solution is to set the complete class path needed for Apache Axis in the general Java class path, but we prefer a different solution: maintaining a batch file that sets the class paths. Our batch file, shown in the following code snippet, is named wsdl2java.bat, and it resides in the working directory.

@echo OFF
rem *******************************************************
rem ***     wsdl2java.bat                              ****
rem *******************************************************
set AXISPATH=c:\java\AXIS\lib
set JAVAPATH=C:\java\j2re1.4.2_09
set DOMINOJAVAPATH=C:\lotus\DominoR7StandAlone\jvm\lib\ext
set CP=%AXISPATH%\axis.jar
set CP=%CP%;%AXISPATH%\commons-logging-1.0.4.jar
set CP=%CP%;%AXISPATH%\commons-discovery-0.2.jar
set CP=%CP%;%AXISPATH%\jaxrpc.jar
set CP=%CP%;%AXISPATH%\saaj.jar
set CP=%CP%;%DOMINOJAVAPATH%\mail.jar
set CP=%CP%;%DOMINOJAVAPATH%\activation.jar
set CP=%CP%;%AXISPATH%\wsdl4j-1.5.1.jar
%JAVAPATH%\bin\java -cp %CP% org.apache.axis.wsdl.WSDL2Java %1

Creating the Web service consuming agent

Begin creating your agent by retrieving a WSDL file from a Web service. We assume that you’re using the provided Web service -- MyWebservice -- and that you have replicated it to a Lotus Domino 7 server. To view the WSDL file, point your browser to the database and open the Web service with the command ?WSDL as shown in figure 1.

Figure 1. Example of a WSDL file shown in a browser
Example of a WSDL file shown in a browser
Example of a WSDL file shown in a browser

After you verify that the WSDL file comes up, you can either save the WSDL file to your working directory or use the URL to point the Apache Axis toolkit directly to the WSDL resource on your network. Now, you can begin generating Java stubs from a WSDL file.

Generating Java files from the WSDL file

The WSDL2Java function can take either a file name as parameter as follows:

C:\java\consumer>wsd12java.bat MyWebservice.xml

or the complete Uniform Resource Indicator (URI) to the WSDL file:

C:\java\consumer>wsd12java.bat http://localhost/mywebservice.nsf/MyWebService?WSDL

To work locally, download and save the WSDL file with the name MyWebservice.xml to your working directory as shown in the first command.

NOTE: The Web service we work with is only for demonstration purposes (for example, no namespaces are used). Therefore, you now see a new directory in your working directory named DefaultNamespace.

The outcome of running wsdl2java.bat is the generation of five Java files:


Of these five files, only two are of real importance for you: and The others are there for performing the call and parsing the response. If you want to learn more about the Apache Axis framework, we recommend the Apache Axis wiki. is an interface describing which methods and arguments the Web service can handle. is a JavaBeans version of the MyComplexClass object, which the Web service is responding to when the getMyComplexClass() method is called.

Now, create a new script library in the Domino 7 database with which you can consume Web services.

Importing the Java files into Lotus Notes

Your Web service consuming agent uses the files that Apache Axis generated. The easiest method for importing the Java files is to create a Java script library (not to be confused with a JavaScriptlibrary). Import the files, and remember to set your working directory as the base path (see figure 2).

Figure 2. Script library for holding the Apache Axis-generated Java stubs
Script library for holding the Apache Axis-generated Java stubs
Script library for holding the Apache Axis-generated Java stubs

NOTE: It’s important that the base directory is your working directory, not the DefaultNamespace directory.

When the script library is in place and compiled, you can close it and create a new Java agent. This agent uses the Apache Axis client classes. These classes are part of the Axis framework and must therefore be imported.

The Apache Axis client resides in a Java archive (JAR file) in the Axis directory. You have a few options for exposing these classes to the agent, one of which is to import the classes directly in the agent. But the generic nature of these classes -- they can be used multiple times when you find out how easy Web consuming can be -- makes it more natural to store them in the .\jvm\lib\ext directory with the other JAR files that IBM Lotus Notes uses.

Copy the JAR files axis.jar, commons-discovery-0.2.jar, and commons-logging-1.0.4.jar from .\Axis\lib to .\jvm\lib\ext in your Lotus Notes client directory. (You must restart your Lotus Notes client before these additions are used.) When Lotus Domino Designer is running, only a few steps remain before you can start calling the Web service.

A Lotus Notes agent that calls a Web service

When the JAR files are in place in your .\jvm\lib\ext directory and you have restarted Lotus Domino Designer, you can code the Web consuming agent. Begin by creating an ordinary Java agent. Next, open the Edit Project window to import the script library you created earlier. Close the project Properties window, and add the required import lines shown here:

00 import lotus.domino.*;
01 import;
02 import org.apache.axis.client.Call;
03 import org.apache.axis.client.Service;
04 import DefaultNamespace.*;
05 import*;
06 public class JavaAgent extends AgentBase {
07  public void NotesMain() {
08   try {
09    Session session = getSession();
10    AgentContext agentContext = session.getAgentContext();
12    URL  endpoint = new URL("http://localhost:80/MyWebService.nsf/MyWebService");
14    Service service1 = new Service();
15    DominoSoapBindingStub service = new DominoSoapBindingStub(endpoint,service1);
16    String greeting=service.getGreeting();
17    System.out.println(greeting);
19    String greeting2=service.getGreeting("Lotus");
20    System.out.println(greeting2);
22  } catch(Exception e) {
23     e.printStackTrace();
24   }
25 }

In line 12, you create a standard Java URL that points to the Web service you want to use. In line 14, you instantiate the Service() class, which Apache Axis provides. You then instantiate the DominoSoapBindingStub service in line 15 and provide it with the newly created service1 object and the URI from line 12. In line 16, you set a new string with the value that the Web service method getGreeting() provides.

Save the agent and start the Java console. (This console is the only place you can see any action now.) When the debug window is open, select your new database, and then run the agent as shown in figure 3.

Figure 3. The Java Console when the agent has finished
The Java Console when the agent has finished

As you can see, using Apache Axis and the wsdl2java tool is a great time-saver. Once upon a time, you had to sit and decode the SOAP messages manually in a Lotus Domino 5 agent to consume a Web service!

Running the Web service consuming agent on a server

You now have a great agent that can use Web services for interactions. For example, your organization’s intranet can subscribe to the latest weather forecasts in a fancier and more accurate way than the Comma Separated Value (CSV) files you’re used to. Or why not start using the Web services that the overpriced Enterprise Resource Planning (ERP) system came with?

No extra steps are necessary for running this agent on a server. Simply make sure that your agent has the "Set runtime security level" property set to "2. Allows restricted operations" in the Agent Properties box and that the signer has the appropriate access.

Copy the necessary JAR files as described earlier into the .\jvm\lib\ext path on your Lotus Domino server, and you are done. Be aware, however, that you may experience a deadlock if you call a Domino Web service on the same server as that on which the agent is running.


This article described the steps you take to build a Domino agent to consume Web services. By taking advantage of the Apache Axis framework, you can save a lot of time and focus on the business values from day one. Apache Axis has been around for a while, and it’s stable and reliable. Using such a third-party tool makes a system more vulnerable, but that risk is small and doesn’t compare to what a good SOA can do for your organization.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Consuming Web services from a Lotus Domino Java agent