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. New to the forum? Please visit the ‘Getting Started’ link below.
All New Topics | All New Posts
inside custom component

Java Development

Article Options

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

by Developer on ‎02-08-2011 04:02 PM - edited on ‎02-08-2011 04:02 PM by BlackBerry Development Advisor
Labels:

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

Attachment Lotus-SearchPeople.zip ‏59 KB
Attachment Tutorial - How to Use Lotus Domino Web Services in Java Development.pdf ‏3008 KB
Attachment Eclipse Source Files - Search People.zip ‏137 KB
By downloading, accessing or otherwise using the Knowledge Base documents you agree: (a) that the terms of use for the documents found at http://www.blackberry.com/support/knowledgebase/disclaimer.shtml apply to your use or reference to these documents; and (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.
Users Online
Currently online: 49 members 4,355 guests
Recent logins:
Please welcome our newest community members:
View All
Article Tags