Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Tutorial - How to Use Lotus Domino Web Services in Java Development

by Developer on ‎02-08-2011 04:02 PM (11,992 Views)

This tutorial contains detailed information about how can we use IBM® 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
  • IBM® Lotus® Notes
  • IBM® Domino® 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
    • Name : SearchPeople
    • PortType Class : SearchPeople
    • Tab : Advance
      • Options \ Programming model : RPC
      • SOAP Message Format : Doc/literal
      • Include operation name in SOAP action : Checked
      • Port type name : SearchPeople
      • Service element name : SearchPeopleService
      • 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

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 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:

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 http keywords 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 Windows® Internet Explorer® or any Browser.
  • Write to Address field.
    • 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 Wireless Toolkit 2.5.2_01 for CLDC (formerly known as J2ME Wireless Toolkit) (Download)

Note : Sun Java 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 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.

 

 

Resim 1.jpg

 

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
    • Type on console “show tasks”. On the list “HTTP Server” “Listen for connect requests on TCP Port : 80”
    • Check server configuration (I mentioned about in Part I)
    • Check Web Service Provider codes
    • 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 pciture 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.

Resim 2.jpg

Picture 12 - Import Stub Files in Project

 

Now our application looks like :

 

Resim 3.jpg

 

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 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.

 

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.

 

Before starting to development, check the wsdl url from Common.wsdlURL variable. New value have to be your sample Lotus web service provider url.

 

Resim 4.jpg

Picture 14 - Common.wsdlURL Variable

 

 

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

Users Online
Currently online: 32 members 1,916 guests
Please welcome our newest community members: