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
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)
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 : [email protected] 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
Public Persons () As Person End Class
Class SearchPeople
Public Function Search ( Key As String ) As PersonList On Error Goto ErrorHandler
Dim oSession As New NotesSession Dim oDatabase As NotesDatabase
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:
REM Debug
Print "WebService : SearchPeople - Function : Search - End" Exit Function
ErrorHandler: 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.
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
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.
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.
Picture 12 - Import Stub Files in Project
Now our application looks like :
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 [email protected].
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
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 [email protected].
Thanks in advance Ferhat BULUT
Blog : http://www.bestcoder.net Twitter : BestCoder81
