What is a Web service?

Web services give organizations the ability to extend existing business processes as published services. These services allow developers to loosely couple software components while easing the integration effort to exchange information between applications. Unlike traditional Domino Web-based applications, Web services contain no user interface for end-user interaction, but provide a unified way to execute processes and exchange data.

Web services are based on three technology standards:

• The eXtensible Markup Language (XML), the enabling force behind Web services, is not a programming language or API but rather a platform-independent way to structure data. The syntax of XML makes it easy to programmatically manipulate textual data while still allowing it to be easily understood by humans. Web services use XML as the standard to provide communication between networked devices.
• The Simple Object Access Protocol (SOAP) provides developers with a platform-independent mechanism to remotely invoke methods on distributed objects. The communication glue of a SOAP message uses XML for describing the object, method, and arguments to execute. Both clients and servers can implement and use SOAP. In this case, the SOAPConnect for LotusScript package provides an easy to use implementation that shields the developer from handling low-level XML.
• The Web Service Description Language (WSDL) defines the available ports and operations for a particular Web service. You can think of a port as an interface and an operation as a method to be called on a particular object.

Back to top

Book Catalog Scenario

Before I review the code and implementation details of how to use SOAPConnect for LotusScript, let's review the purpose and structure of the included sample database. The sample database is a short book catalog highlighting various gardening books. The goal of this database is to provide users with a way to receive up-to-date pricing on any book within the catalog. The database contains one form called Book that highlights the details about each book in the catalog. The Book form consists of five fields that describe each book: the book's title, the book's cover image, the book's author, the ISBN number, and the publisher. Users can browse the list of available books via a Web browser using the All Book view as shown in Figure 1 below.

As you'd expect, once a book has been selected in the view, the user is presented with that particular book's details.

As with most online retailers, the price of books fluctuates given demand and availability. The Get Price button allows users to receive an up-to-date price using the power of a Web Service from Barnes & Noble and the SOAPConnect for LotusScript package.

Back to top

Installing SOAPConnect for LotusScript

The SOAPConnect for LotusScript package is available for download at the end of this article. In order to test the sample database or use the SOAPConnect for LotusScript, your environment must meet the following minimum requirements:

• Lotus Notes Client, release 5.0.7a or later
• Lotus Domino Designer, release 5.0.7a or later
• Lotus Domino Server, release 5.0.7a or later

Although the SOAPConnect for LotusScript package doesn't require the developer to write any Java code, the package uses a Java agent underneath the covers to invoke the external Web service. Unfortunately, the Java agent uses an implementation of Apache's SOAP that requires a different version of the Java XML parser than the one installed as part of Notes and Domino. Following the steps below could affect other databases, so it's highly recommended that you perform these steps in a test or development environment.

To install on the Domino Designer, complete the following steps:

1. Unzip the SOAPConnect for LotusScript package in the directory C:\SOAPConnect.
2. Rename file XML4j.jar that is installed in the Notes program directory (by default C:\Lotus\Notes\XML4j.jar ) to XML4j.jar-hidden.
3. Copy all files in directory C:\SOAPConnect\ProgramDir to your Notes program directory (by default C:\Lotus\Notes ).
4. Copy all files in directory C:\SOAPConnect\DataDir to your Notes data directory (by default C:\Lotus\Notes\data ).
5. Rename file XML4J.jar that is installed in Designer's Java directory (by default C:\Lotus\Notes\data\domino\java ) to XML4j.jar-hidden. Then copy all files in directory C:\SOAPConnect\ProgramDir to your Designer Java directory (by default C:\Lotus\Notes\data\domino\java ).

To install on a Windows Domino Server, complete the following steps:

1. Unzip the SOAPConnect for LotusScript package in the directory C:\SOAPConnect.
2. Rename file XML4j.jar to XML4j.jar-hidden in both the Domino program directory (by default C:\Lotus\Domino ) and the Domino Java directory (by default C:\Lotus\Domino\Data\domino\java ).
3. Copy all files in directory C:\SOAPConnect\ProgramDir to your Domino program directory (by default C:\Lotus\Domino ) and also copy them to the Domino Java directory (by default C:\Lotus\Domino\Data\domino\java ).
4. Copy all files in directory C:\SOAPConnect\DataDir to your Domino data directory (by default C:\Lotus\Domino\data ).

Back to top

Understanding SOAPConnect for LotusScript

As you saw during the installation process, SOAPConnect for LotusScript consist of several Java libraries and Domino databases. Although Java technology is used underneath the covers, SOAPConnect allows developers to use LotusScript to create, send, and manipulate SOAP messages. To gain a high-level view of how SOAPConnect for LotusScript operates, the diagram below demonstrates the data flow and the transport protocol being used.

As illustrated in Figure 3, whenever a user wants to view the price for specific book, a document is created in the SOAPCall Runner database. The SOAPCall agent in the SOAPCall Runner database uses Apache's SOAP library to create a SOAP message and send it across to XMethod's servers. XMethods is a virtual laboratory for developers to test various Web services from many different authors and organizations. In the sample database, XMethod's server acts a router between the request from SOAPConnect and Barnes & Noble's servers. After the request has been forwarded to Barnes & Noble's server and the book is located within their catalog, the book's price is sent back to the SOAPCall agent through XMethod's server. In turn, the SOAPCall agent returns the price back to the calling LotusScript agent within the book catalog database.

Back to top

Invoking the Web service

Now that I've covered the basics of Web services and the behavior for your sample application, let's get started with reviewing how to invoke a Web service using the SOAPConnect for LotusScript package. In the sample database, the GetPrice LotusScript agent is called when the user clicks the Get Price button on the Book form. Amazingly enough, it only takes nine lines of code to invoke the Web service and return the data back to the agent. The code below illustrates the objects and methods necessary to get back a book's price.

		
1       %INCLUDE "SoapConnect"
2       Dim session As New NotesSession
3       Dim doc As NotesDocument
4       Dim myArgs(0) As Variant
5       Dim price As String
6       Set doc = session.DocumentContext
7       Dim bn As New SOAPClient("http://services.xmethods.com:80/soap/servlet/rpcrouter" )
8       myArgs( 0 ) = doc.BookNumber( 0 )
9       price = bn.invoke("urn:xmethods-BNPriceCheck", "getPrice", myArgs)

Let's step through this code snippet:

1. Before you can use the SOAPClient class, you need to signal to Domino the location of this resource. The Include directive on line 1 inserts the contents of SoapConnect.lss into the agent at compile time. The SoapConnect.lss was copied into your program directory during the installation of SOAPConnect.
2. Lines 2 through 6 set up variables you'll use during the execution of the agent.
3. Here's where it gets interesting. On line 7 you create a new SOAPClient with the location of the service endpoint. This example uses a service endpoint of XMethods. More information about XMethods is available at the end of the article. (See Resources.
4. Before you can invoke the Web service, you need to get the ISBN number of the book in question.
5. Line 9 invokes the Web service passing the namespace, method, and argument. The namespace variable corresponds to the service that will be loaded, in this case the xmethods-BNPriceCheck service. The myArgs variable contains the ISBN number for the book.

The Figure 4 below illustrates the GetPrice agent within Domino Designer 6.

Back to top

Summary

Lotus has made a commitment to embrace Web services as a way to utilize and extend Notes and Domino's collaborative features. With packages like SOAPConnect for LotusScript, it's exciting to explore how Domino can consume Web services using native tools and procedures. The sample database provides a framework that can be used to create your own databases to invoke Web services. Throughout this article the following topics were presented:

• Introduction to the core technologies that make up Web services.
• Coverage of the steps involved in installing SOAPConnect for LotusScript.
• Exploration of how to use SOAPConnect for LotusScript within the context of a sample application.

Resources

• Download Lotus Domino Designer 6 and Lotus Domino Server 6 trial versions.
  
  
• Download the SOAPConnect for LotusScript package.
  
  
• Download the companion Domino database that was demonstrated throughout this article.
  
  

• The Apache SOAP project provides a Java SOAP implementation that is used within SOAPConnect for LotusScript.
  
  
• Find out more about XMethods virtual laboratory for developers to list and test out available Web services.
  
  
• Find out more about Building Web services with Domino 6.
  
  
• Learn how to Turn your Lotus applications into Web services.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• What is a Web service?
• Book Catalog Scenario
• Installing SOAPConnect for LotusScript
• Understanding SOAPConnect for LotusScript
• Invoking the Web service
• Summary
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Domino Designer
• Webcast: Modernization approaches to reduce the total cost for multi-platform enterprise applications
• Briefing: Smarter collaboration with IBM Lotus solutions

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers