Tutorial - How to Use Lotus Domino Web Services in Java Development This tutorial contains detailed information about how can we use Lotus Domino Web Services (using Web Services Provider) in Java Development. Using this sample application, we ll able to do full-text search in the Domino Directory using Web Services (Provider) technology. Just we ll need to enter search keyword and click to Search button. That s all. Let's start our sample application. Part 1 (Domino WebService) In this part of tutorial will use following Development IDE & Tools. Lotus Domino Server 8.5 Lotus Notes & Designer 8.5.1 Now we will create Lotus Notes Application to begin our tutorial. In the application (a.k.a. notes database) we ll create new Web Services Provider design element. BlackBerry application invoke this web services and gets the results. Create new Lotus Notes Application using following information : Title : Search People Application File Name : searchpeople.nsf Add anonymous entry to ACL with Author & Create Document property. Also you can create your application any where in your server data directory. Web Services URL seems like that : http://<hostname>/<nsf db file path>/<web service name>?wsdl Picture 1 - Create Database
Create Web Services Provider design element using following information : Open your application in Domino Designer Expand Code \ Web Service Providers Click to New Web Service Provider button. Name : SearchPeople Type : LotusScript Click to OK Picture 2 - Domino Designer IDE - Web Service Providers Picture 3 - New Web Service Provider (SearchPeople) Picture 4 - Web Service Properties
Create Web Services Provider design element using following information : Tab : Basics o Name : SearchPeople o PortType Class : SearchPeople Tab : Advance o Options \ Programming model : RPC o SOAP Message Format : Doc/literal o Include operation name in SOAP action : Checked o Port type name : SearchPeople o Service element name : SearchPeopleService o Service port name : Domino Add following codes to the Declarations event of Web Service. %REM ############################################################ WEB SERVICES : SearchPeople DEVELOPER : Ferhat BULUT WEB SITE : www.bestcoder.net E-MAIL : ferhat@bestcoder.net CREATED DATE : JANUARY 13, 2010 MODIFIED DATE : DECEMBER 28, 2010 COMMENTS Bu WebService BestCoder.NET sitesinde yayınlanmak üzere blackberry mobil uygulama geliştirme örneği için hazırlanmıştır. ############################################################ %END REM REM Declaration of global variables accessible from all parts of the Web service. Class Person Public NameSurname As String Public NoteID As String End Class Class PersonList End Class Public Persons () As Person Class SearchPeople Public Function Search ( Key As String ) As PersonList On Error Goto ErrorHandler Dim osession As New NotesSession Dim odatabase As NotesDatabase Dim i As Integer
Dim strsearchstring As String Set Search = New PersonList REM Debug Print "WebService : SearchPeople - Function : Search - Start" REM Get Current Database Set odatabase = osession.currentdatabase Dim onamesdb As NotesDatabase Dim opersoncollection As NotesDocumentCollection Dim opersondoc As NotesDocument Dim onnperson As NotesName REM Get Domino Directory Database Set onamesdb = osession.getdatabase ( odatabase.server, "names.nsf", False ) REM Create FT Search String strsearchstring = {[FORM] CONTAINS "Person" AND [FULLNAME] CONTAINS "} + Key + {"} Set opersoncollection = onamesdb.ftsearch( strsearchstring, 10, FT_SCORES, FT_FUZZY ) REM If collection is empty go to exit If opersoncollection.count = 0 Then Redim Search.Persons ( 0 ) Set Search.Persons ( 0 ) = New Person Search.Persons ( 0 ).NameSurname = "NOT_FOUND" Search.Persons ( 0 ).NoteID = "" Gosub Finish End If REM resize person array with the size of collection Redim Search.Persons ( opersoncollection.count - 1 ) i = 0 Set opersondoc = opersoncollection.getfirstdocument Do While Not ( opersondoc Is Nothing ) REM Create person class in person array Set Search.Persons ( i ) = New Person Set onnperson = New NotesName ( opersondoc.fullname ( 0 ) ) Search.Persons ( i ).NameSurname = onnperson.abbreviated Search.Persons ( i ).NoteID = Cstr ( opersondoc.noteid ) Set opersondoc = opersoncollection.getnextdocument ( opersondoc ) i = i + 1 Loop Finish: ErrorHandler: REM Debug Print "WebService : SearchPeople - Function : Search - End" Exit Function REM Debug Print "WebService : SearchPeople - Function : Search - Error Description : " + Error$ + " - Error Line Number : " + Cstr (Erl) End End Function
End Class Save and close. Our webservice is ready. But don t forget to check the values of some field on your Lotus Domino server configuration document as following : Check Http task is running. HTTP Task have to be running to browse web service on the browser. Just type tell http status keywords on the server console and press the ENTER. You will see "HTTP Server Listen for connect requests on TCP Port:80" in the list if HTTP Task is running. If not, type load httpkeywords and press the ENTER. Or ask your domino administrator. Add Signer of Web Service to TAB : Security >>> PARTS : Programmability Restrictions \ Sign or run unrestricted methods and operations field. TAB : Internet Protocols \ SUB-TAB : Domino Web Engine \ Web Agents and Web Services \ Run web agents and web services concurrently? : Enabled Give an integer value to Internet Protocols \ Domino Web Engine \ Web Agents and Web Services \ Web agent and web services timeout field. Maybe 60 seconds Lets check our Web Service is running? Open your Internet Explorer or any Browser. Write to Address field. o http://<local computer ip or host name>/<db file path>/peoplesearch?wsdl and press to Enter. You will see following picture in your browser. Picture 5 - Web Service Provider Browser Preview
Part 2 (Stub Generator & Introduction to Eclipse) In this part of tutorial will use following Development IDE & Tools. Lotus Domino 8.5.1 Lotus Domino Designer 8.5.1 BlackBerry Java Plug-in for Eclipse v1.1.2 (With this version, you have to download OS plugins (4.5.0 or etc) from Available Software Sites screen using http://www.blackberry.com/go/eclipseupdate/3.5/java) (Download) BlackBerry Email and MDS Services Simulator Package v4.1.4 (Download) Sun Java (TM) Wireless Toolkit 2.5.2_01 for CLDC (formerly known as J2ME Wireless Toolkit) (Download) Note : Sun Java (TM) Wireless Toolkit 2.5.2_01 for CLDC is 32-bit application. So Java (JDK) on your computer have to be 32-bit. I had a problem during stub generation process with Sun Java (TM) Wireless Toolkit (32-bit)and JDK (64-bit). Check your webservice is running. Type the Web Service url to address field. Webservice url seems like that :http://<local computer ip or host name>/<db file path>/peoplesearch?wsdl and press to Enter. Open the Sun Java Wireless Toolkit application using Utilities link. Picture 6 - Utilities > Stub Generator Select Stub Generator and click to Launch button.
Picture 7 - Run Stub Generator Enter necessary information in Stub Generator Dialog screen. WSDL Filename or URL : Your WSDL URL > http://<hostname>/<nsf db file path>/<web service name>?wsdl Output Path : Location for generated files. Select a directory. For example : C:\SearchPeople Output Package : Type the package name for your java files. For example : com.blackberry.lotus CLDC Version : Select CLDC 1.1 option. Select OK button to finish process. If you got an error, please check this list to solve problem : Check the Lotus Domino server is running Check HTTP Task is running o Type on console show tasks. On the list HTTP Server Listen for connect requests on TCP Port : 80 o Check server configuration (I mentioned about in Part I) o Check Web Service Provider codes o Check Java configurations (JDK have to be installed etc.) If everything is fine, Stub Generator shows a dialogbox like this. Stub Generation Complete After that close Stub Generator application. Goto C:\SearchPeople directory. Look at files. You will see 8 files. You need these *.java files to begin BlackBerry Java Application Development part of the tutorial.
Picture 8 - Stubs - Output Files of Web Service Open your BlackBerry Java Plug-in for Eclipse v1.1.2 application. Create new BlackBerry Project. Click on File > New > Project Expand BlackBerry category, select BlackBerry Project and click to Next button. Picture 9 - New BlackBerry Project
Enter a name of project. I entered SearchPeople for my project s name. And click to Finish button. Picture 10 - Sample BlackBerry Project - SearchPeople Our project looks like following picture in Package Explorer window. Picture 11 - SearchPeople Project Now we need to add our java files to project. Create a Package element under src folder with the name com.blackberry.lotus Right mouse click on the src folder. Click on New > Package Name : com.blackberry.lotus Click on Finish button. Now import Java stub files to this package. Right mouse click on the package com.blackberry.lotus Click on Import Select General > FileSystem category Type directory in From Directory field : C:\SearchPeople\com\blackberry\lotus Select *.Java files and click on Finish button.
Now our application looks like : Picture 12 - Import Stub Files in Project Picture 13 - Project Files Preview
Part 3 (Eclipse Development) In this part of tutorial will use following Development IDE & Tools. Lotus Domino 8.5.1 Lotus Domino Designer 8.5.1 BlackBerry Java Plug-in for Eclipse v1.1.2 (With this version, you have to download OS plugins (4.5.0 or etc) from Available Software Sites screen using http://www.blackberry.com/go/eclipseupdate/3.5/java) (Download) BlackBerry Email and MDS Services Simulator Package v4.1.4 (Download) Sun Java (TM) Wireless Toolkit 2.5.2_01 for CLDC (formerly known as J2ME Wireless Toolkit) (Download) We created stub files using Java Wireless Toolkit. Imported into our BlackBerry Project. Before starting to development, check the wsdl url from Common.wsdlURL variable. New value have to be your sample Lotus web service provider url. Picture 14 - Common.wsdlURL Variable Our project files are listed below. I tried to write a detailed comments into source files. If it is not enough for you, please donot hesitate to contact with me from ferhat@bestcoder.net.
AboutScreen.java : About screen file of application Common.java : Using for common variables GlobalNotificationScreen.java : Additional screen. Using to show general notifications, errors, etc. ListFieldExt.java : Extended ListField class. I don t remember the author. It was public code. PERSON.java : Web Service File from Stub Generation. Includes user details. PERSONLIST.java : Web Service File from Stub Generation. Includes users using PERSON class. SearchPeople_Stub.java : Web Service File from Stub Generation SearchPeople.java : Web Service File from Stub Generation UiAppWelcome.java : Entry Point of the Application SplashScreen.java : Additional screen for Splash SearchPeopleScreen.java : Main screen for our demo application SelectPersonScreen.java : Additional screen. Also we covered multiple language support using resource files. And also it is related to device language. The application is very clever, automatically identify language and shows application in this language. SearchPeople_en.rrc : Resource File for English language SearchPeople_tr.rrc : Resource File for Turkish language SearchPeople.rrc : Resource File SearchPeople.rrh : Resource File We covered following functionallities in this tutorial. Using Lotus Domino Web Service : BlackBerry application gets keyword from the user and invoke related function from Web Service, gets results and so on. Splash Screen Feature : It s timed splash screen and after time ends, it ll close automatically and pushes main screen to stack. Multiple Language Support : Application s front-end language determined at start-up automatically from device language. There are two language support in this tutorial.
Context Sensitive Menu : In the SearchPeopleScreen.java (a.k.a. Main Screen), we covered context sensitive menu. Modal Screen Usage : Get input from user ListField Class Usage If you have any question, please donot hesitate to contact with me from ferhat@bestcoder.net. Thanks in advance Ferhat BULUT Blog : http://www.bestcoder.net Twitter : BestCoder81