Turn your Lotus applications into Web servicesYour existing apps can join the new service infrastructure
Skill Level: Introductory
George Brichacek ([email protected])Technology AdvocateIBM Software Group
Scott Souder ([email protected])Development ManagerIBM Software Group
06 Sep 2002
As more and more applications use Web services, exposing your Lotus applicationswithin this architecture will keep costs down, increase speed to market, changenothing, and integrate everything. This tutorial will show you how to turn your existingLotus applications into portable Web services. We will use IBM WebSphere StudioApplication Developer to develop and test the Web service, and then deploy the Webservice to an IBM WebSphere Application Server. The Web service we will create willaccess a Lotus Domino database through an agent written in LotusScript.
Section 1. Introduction
What is this tutorial about?
You've invested a lot of time, money, and effort in developing and maintaining yourLotus applications, or you're looking to Lotus Software to help you start leveragingyour know-how -- with messaging, collaboration, e-learning, e-meetings, and more.You're being asked to leverage these assets, keep costs down, increase speed tomarket, change nothing, and integrate everything.
This is what Web services are all about. Web services are an evolution -- not arevolution -- of the way you architect, design, implement, and deploy youre-business solutions. Web services conform to a set of open standards and
specifications. They allow you to expose those Lotus business applications you'veinvested in and integrate them across multiple platforms, programming languages,and companies.
The objective of this tutorial is to show you how to easily create Web services fromexisting Lotus Domino applications. The Web service we're going to create willaccess a Lotus Domino server using HTTP. The URL will invoke a Domino agent.The agent, written in LotusScript, will randomly select a document in a Dominodatabase and return the text from that document. We'll also show you how to deploythe Web service to a WebSphere Application Server.
This is a very simple example, but it demonstrates how to create a Web service thataccesses Lotus Domino. The idea is to take this foundation and apply it to new orexisting Lotus Domino applications. When you access Lotus Domino applications asWeb services, you are exposing them as portable units ready to be placed intoexisting business applications.
To complete the steps in this tutorial, you'll need to have the following applicationsinstalled and working properly: The Application Developer configuration ofWebSphere Studio, Lotus Domino Designer, Lotus Domino Server, and WebSphereApplication Server. Don't worry if you don't already have these products installed,links to free trial download versions of the products are provided.
What is a Web service?
Web services are self-contained, self-describing, modular applications that can bepublished, located, and invoked across the Web. The functions provided by Webservices can range from simple requests to complex business processes.
Providers of Web services register their applications with a service broker called theUniversal Description, Discovery, and Integration (UDDI) registry. They use alanguage known as Web services Description Language (WSDL) to describe theirWeb services.
The service broker (or registry) is the Web service interface. It providesimplementation access information to any potential service requestor. Requestors ofWeb services can find and invoke the registered service using the Simple ObjectAccess Protocol (SOAP).
This tutorial will benefit developers working in an environment where Lotus Dominoand Domino applications have been developed. The tutorial will provide an examplehow to create a Web service from an existing Domino application.
This tutorial may also be useful for developers looking to extend their existingapplications with Lotus collaborative services -- messaging, workflow, and onlineawareness -- where Lotus Domino is being considered, but not yet deployed.
After completing this tutorial you'll know how to create a Web service that accessesLotus Domino.
Section 2. Setting up your system
Overview
This is a step-by-step guide on how to use Application Developer to create a Webservice that accesses Lotus Domino. Though we could use Lotus Domino to host theWeb service, we'll host it on WebSphere Application Server. See Resources formore information on hosting Web services on Domino.
This section describes the software requirements for the tutorial. For moreinformation on any of the products mentioned here, see Resources.
All the products can be installed on the same machine.
Lotus Domino Designer is an application development environment used for creatingDomino and Web applications. We are not going to develop anything in this tutorial,but we are going to use Domino Designer to view the sample Domino applicationthat you'll download. We'll review the code in the sample application so you canunderstand how it all works.
This tutorial requires Lotus Domino Designer 5 or higher. The sample applicationand the steps presented in this tutorial were created with Lotus Domino Designer 6pre-release 2.
Download the free trial version of Lotus Domino Designer 6 (select Notes Client,Domino Designer & Admin 6). During the install, you can choose to install all clientsor just Domino Designer.
Lotus Domino Server
Lotus Notes/Domino is groupware software. Notes is the e-mail, calendaring, groupscheduling, Web access and information management client. Domino is theintegrated messaging and Web application server providing directory services,messaging, security, and much more. We need a Domino server for our demoapplication to run. Lotus Domino is a multi-platform application server; theapplication presented in this tutorial should work on any of its supported platforms.
This tutorial requires Lotus Domino 5.0.9 or higher. The sample application and thesteps presented in this tutorial were created with Domino Server 6. The free trialversion of Lotus Domino 6 is available for download. Follow the readmedocumentation for installation instructions.
WebSphere Studio Application Developer
Application Developer is an application development tool which we'll use to developour Web service application.
This tutorial requires WebSphere Studio Application Developer 4.0 or higher. Youcan download the latest trial version of Application Developer, listed as WebSphereStudio for Windows, at no charge.
WebSphere Application Server
WebSphere Application Server is a high-performance J2EE-compliant Webapplication server. The server provides a complete set of e-business applicationdeployment and integration services including capabilities for transactionmanagement, security, clustering, performance, availability, connectivity andscalability.
We'll be using WebSphere Application Server Version 4 for this tutorial. You candownload a free trial of the latest version of WebSphere Application Server at nocharge.
Sample code and Lotus Domino application
Download this zip file (source_code.zip) for a copy of the sample java code(GetDominoQuote.java) and the sample Domino application(Domino_Answers.nsf) that we'll use in this tutorial.
The Lotus Domino application -- Domino_Answers.nsf -- must be placed in theDomino\data directory where the Lotus Domino server is installed. It's a good ideato sign the database with a userid that has the proper access rights to executeagents on the server.
Section 3. View the Lotus Domino agent
Launch Domino Designer
In this section we're going to use Lotus Domino Designer to look at the Dominoagent code within the sample Domino application that you just downloaded. That'sall, we're not going to change anything.
in the Server field of the Open database dialog, enter the name of the Domino serverwhere you deployed the Domino demo application. The example server isGEO2001/Lotus. Select Domino Answers for Database title. Finally, select Open.
To open the agent, expand Shared Code, expand Agents, and selectDominoQuote in the left pane.
Browse the agent code
Select the Initialize to see the LotusScript code in the right pane.
Read through the LotusScript code. LotusScript is compatible with the Basicprogramming language. You'll see that this agent starts the random generator, getsthe total number of documents in the database, then selects a random numberbetween 1 and the total number of documents. The agent selects the document andreturns the text from the Answer field.
On the Create a Web Project dialog, enter WebServiceProject in the Projectname field.
Enter WebServiceEAR as the Enterprise Application project name. An EnterpriseApplication project contains resources that are required to deploy an enterprise(J2EE) application. If one doesn't already exist, a J2EE application will beautomatically created for us.
WebServiceProject should be displayed in the Context root field. The context rootis the Web application root, the top-level directory of our application when it isdeployed to the WebSphere Application Server. Select Next >.
On the Module Dependencies dialog, select Next >. For Define Java Build Settings,select Finish. If you expand all folders in Application Server, it should look like this:
Select the source folder in our project from the Application Developer Navigatorview. Next, select File => New => Other.... In the left panel, select Java and in theright panel, select Java Class. Select Next >.
You don't need to add any special Java .jar files in our project for Domino. We'regoing to invoke Domino using HTTP.
Enter a Java name
Enter GetDominoQuote for the name. We don't need to enter any otherinformation, since we'll paste in the Java code. Next, select Finish.
Copy the following code and paste it in the Java code window. Basically, theprogram invokes a Domino agent using HTTP, then parses the results. A copy ofthis code (GetDominoQuote.java) is also available in the zip file you downloadedearlier.
Note: You will need to change the server host name. In the example, changegeo2001.lotus.com to your Domino server's hostname.
import java.io.*;import java.net.*;
public class GetDominoQuote {public static void main( String args[] ) {
We'll create the Web service using the Java application we've just added to ourapplication. In Application Developer, select the WebServiceProject folder, thenselect File => New => Web service. If you don't see Web service, select Other...,
On the Web Service Type Selection page, GetDominoQuote.java should beselected. This is the Java application we'll be accessing in our Web service. SelectNext >.
On the Web Service Java Bean Identity page, change the Web service UniformResource Identifier (URI) to something more easily understood likeurn:GetDominoQuote. A URI is a name that uniquely identifies a Web service to aclient. Leave all other fields unchanged. Select Next >.
Leave all fields unchanged on the Web service Java Bean Methods page.
This page shows a summary of methods in our bean. It also allows us to select theencoding for our data. These are rules for serializing data over the SOAP protocol.SOAP encoding is based on a simple type system, and literal XML encoding isbased on an XML schema instance. We'll use the default, SOAP encoding. SelectNext >.
Leave all fields unchanged on the Web Service Binding Proxy Generation page. Thisis the name of our proxy which will encapsulate the SOAP client programming APIsand the details of writing, receiving, and parsing SOAP XML documents. Select Next>.
Do not select Launch the test client on the Web Service Test Client page. We'regoing to test our Web service using the sample Web application. Select Next >.
On the Web Service Sample Generation pane, we want to generate a sample WebClient to test our Web service. Select the check box next to Generate a sample.Also, select the check box next to Launch the sample. Select Next >.
Because we checked the option to generate and launch the sample, ApplicationDeveloper will launch a test WebSphere Application Server. You should notice thetest server starting in the lower pane. When you see the message Default Serveropen for e-business, the application server is ready.
Next, Application Developer will automatically launch a Web browser for us. In theupper pane, you should notice the sample client. In the Methods frame, selectgetRandomQuote.
Select the Invoke button. This will invoke our GetDominoQuote Java applicationwhich will call our Domino agent. The agent will select a random document, read theAnswer field, and return an answer to our client. Select Invoke a few more timesand watch the answers change.
Before we export our project, there are some changes we need to make. It's a goodidea to add a description to our Web service in Application Developer. To do so,open the J2EE Perspective. In the left navigator, select the J2EE Perspective icon.Or select Perspective => Open => J2EE.
Open the WebServiceEAR folder
Expand Enterprise Applications and double-click our enterprise application project,WebServiceEAR.
Enter a description of the Web service. (Like the good programmers we are, wedocument our applications completely.) Then press Ctrl+S to save theapplication.xml file.
Open GetDominoQuoteProxy Java File
Next, we need to open the proxy file so we can make a couple of changes. To dothis, we need to return to the Web Perspective.
Select the Workspace: Web Perspective icon in the left navigation pane or selectPerspective => Open => Web. Expand WebServiceProject\source\proxy\soapthen open GetDominoQuoteProxy.java by double-clicking it.
Change port 8080
Application Developer's built-in Web server is configured to listen on port 8080 so itdoes not interfere with a production Web server. Therefore, the proxy generated byApplication Developer sets the URL for the Web service to:http://localhost:8080/WebServiceProject/servlet/rpcrouter. Weneed to change this URL.
In this example, the WebSphere Application Server name is geo2001, change this toyour server name.
The transport port for the application on WebSphere Application Server is 9080. Youneed to check with your WebSphere Application Server administrator for the exactport number. This will be a different port number if you already have applicationsdeployed. Press Ctrl+S to save the changes.
Change WSDL file
We're not done yet. We need to change the Web services Description Language(WSDL) files. WSDL is a standard for describing networked, XML-based services.It's an XML text document that describes where a Web service is deployed and whatoperations that service provides.
Expand WebServiceProject\webApplication\wsdl. Edit both the binding andservice WSDL files by double-clicking them, and change all occurrences oflocalhost:8080 to geo2001:9080. There should be one change in the bindingWSDL file and four changes in the server WSDL file.
In this example, the WebSphere Application Server name is geo2001. Change thisto your server name.
For Where do you want to export resources to enterC:\temp\WebService.ear or any other directory. Under Options, you can selectExport source files and Overwrite existing resources without warning if the filealready exists. Select Finish.
Start the WebSphere Application Server administrator's console. For our example,we're running WebSphere Application Server on Windows. Select Start =>Programs => IBM WebSphere => Application Server 4.0 AE => Administrator'sConsole.
To create an application in WebSphere Application Server, we'll use the wizard.Select the Wizards icon along the top and select Install Enterprise Application.
Select the application
Select Install Application (*.ear). For Path, enter C:\temp\WebService.ear orthe directory where you exported the ear file. For Application name, enterWebService. Select Next >.
The next nine panels will let you specify additional information about our application-- EJB settings, resource references, virtual host, etc. For our application, selectNext > nine times to accept all the defaults. Select Finish.
You should see Command "EnterpriseApp.install" completed successfully.
Start the application
Now that we have deployed an application, we need to start it. Expand WebSphereAdministrative Domain. Expand Enterprise Applications. Right-click WebServiceand select Start.
We're done! That's it. You have turned an existing Lotus application into a Webservice.
The next logical step would be to create a friendlier user interface for this Webservice application. Remove the frames, and update the page with the Invokebutton. The last step would be to create or enhance an end-user Web businessapplication that would use this Web service, but that is another tutorial for anothertime.
• Build your next development project with IBM trial software, available fordownload directly from developerWorks.
Discuss
• Participate in the discussion forum for this content.
About the authors
George BrichacekGeorge Brichacek is a technology advocate with IBM Lotus Software, IBM SoftwareGroup, focused on application development and enterprise integration. He haspresented and developed several memorable demos for the Lotus MastersBroadcast, as well as for customers, and for internal field enablement. He works withLotus product management to bring the latest and greatest technologies on Lotusapplication development and enterprise integration to you. During his spare time, hedeveloped and supported a Lotus Notes utility called CalPrint. George resides in theChicago area. You can reach him at [email protected].
Scott SouderScott Souder is a development manager for the Product Introduction team within theIBM Software Group. As part of the development organization, Scott leads a teamwhose mission is to ensure that the offerings in the Lotus Software portfolio meet orexceed design and release goals through early, real-world use by both internal andexternal customers. Scott resides in the Dallas area. You can reach him [email protected].
