® bp201: coding web service clients for ibm lotus domino paul t. calhoun / cto, netnotes solutions...

®

BP201: Coding Web Service Clients For IBM Lotus Domino

Paul T. Calhoun / CTO, NetNotes Solutions Unlimited, Inc.

I AM !

Paul T. CalhounChief Technology OfficerNetNotes Solutions Unlimited

Paul Calhoun, ND 6 & 7 PCLI and PCLP,a highly rated speaker who provides customer-focused Java classroom instruction and consulting to Fortune 100 and 500 companies, as well as many SMBs. Paul currently builds Domino, Web, Java, and XML applications for his customers using Domino and WebSphere.

He co-authored the IBM Redbook “XML Powered by Domino,” and has developed several online XML and Java programming courses. He has written articles for both “The View” and “The Sphere” technical publications.

Agenda

The Technologies

Web Services – The Server Side

Web Services – The Client Side

Eclipse – Your Web Service Development Environment

Developing Web Service Clients

Developing Web Service Clients for Domino 6


The Technologies

XML

SOAP

WSDL

UDDI

XML Defined

Extensible markup language A specification developed and maintained by the W3C

www.w3.org XML is a pared-down version of SGML Designed especially for Web documents It allows designers to create their own customized tags, enabling the

definition, transmission, validation, and interpretation of data between applications and organizations

So What is XML in English?

Developers create their own tags to describe data structures using standard syntax Represents DATA Must be well-formed Optionally can be valid

Standard for creating markup languages which describe the structure of data WML XHTML MathML DXL

It is not a fixed set of elements like HTML

So What is XML in English? (cont.)

XML is the “Lingua Franca” of Web services That’s Latin for “common language”

If you can’t read / write XML then learn it first Need to understand

Well-formed

– XML documents can’t be “kinda” right Validation

– Using DTDs and XSDs Transformation

– XSLT, XSL-FO

– Not AS important with Web services but still essential

Why Learn XML?

XML is used to communicate the data that is Sent to the Web service

Usually via SOAP Received back from the Web service

Usually via SOAP

And because it is one of the qualifications for UBER GEEK

SOAP Defined

Simple Object Access Protocol An XML based protocol for information exchange in decentralized and

distributed environments Co-developed by

IBM and Microsoft (now that’s collaboration)

So What is SOAP in English?

Send XML data formatted as a SOAP message TO the Web service Message is “parsed” to read the request

Data for one of the defined service methods

Receive XML data formatted as a SOAP message FROM the Web service Message is “parsed” to read the response

Data that provides the information that fulfills the service request Or an error message

SOAP Protocols

You need to send and receive messages based upon a common SOAP version Version 1.1 Version 1.2

Specification maintained at the W3C http://www.w3.org/TR/soap

SOAP 1.1 Request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> <SOAP-ENV:Body> <m:GetLastTradePriceDetailed xmlns:m="Some-URI"> <Symbol>DEF</Symbol> <Company>DEF Corp</Company> <Price>34.1</Price> </m:GetLastTradePriceDetailed> </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

SOAP 1.1 Response

<SOAP-ENV:Envelope … same ns as request>

<SOAP-ENV:Body>

<m:GetLastTradePriceResponse

xmlns:m="Some-URI">

<PriceAndVolume>

<LastTradePrice>34.5

</LastTradePrice>

<DayVolume>10000

</DayVolume>

</PriceAndVolume>

</m:GetLastTradePriceResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

SOAP 1.2 Request

<?xml version='1.0' ?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

<env:Header>

<test:echoOk xmlns:test=http://example.org/ts-tests env:role="http://www.w3.org/2003/05/soap-envelope/role/next">

foo

</test:echoOk>

</env:Header>

<env:Body>

</env:Body>

</env:Envelope>

SOAP 1.2 Response

<?xml version='1.0' ?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

<env:Header>

<test:responseOk xmlns:test="http://example.org/ts-tests">

foo

</test:responseOk>

</env:Header>

<env:Body>

</env:Body>

</env:Envelope>

Do I Really Have To Learn All That Syntax?

Yes, you should! If you don’t know the syntax (or at least how to read the reference)

then you can’t Troubleshoot ill-formed envelopes Parse the packet to get the data easily

But, no you don’t Most Web services development platforms / toolkits produce the SOAP

envelops for you The SOAP request envelopes are produced dynamically by your code SOAP responses can be parsed with any XML parser

WSDL Defined

Web Services Description / Definition language An XML-formatted language used to describe a Web service's

capabilities as collections of communication endpoints capable of exchanging messages

WSDL describes the public interface to the Web service These are the methods that get invoked

This is an XML-based service description on how to communicate using the Web service

WSDL documents are stored in a UDDI registry for discovery

So What is WSDL in English?

Seems to be some confusion about what the “D” stands for Description/Definition Don’t worry about it, all the same thing

WSDL is A description of the services provided by a Web service

Method names, Return data types Written in XML syntax as an XML document

A WSDL Document<?xml version="1.0"?>

<definitions name="StockQuote"

targetNamespace="http://example.com/stockquote/definitions"

xmlns:tns="http://example.com/stockquote/definitions"

xmlns:xsd1="http://example.com/stockquote/schemas"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns="http://schemas.xmlsoap.org/wsdl/">

<import namespace="http://example.com/stockquote/schemas"

location="http://example.com/stockquote/stockquote.xsd"/>

<message name="GetLastTradePriceInput">

<part name="body" element="xsd1:TradePriceRequest"/>

</message>

<message name="GetLastTradePriceOutput">

<part name="body" element="xsd1:TradePrice"/>

</message>

<portType name="StockQuotePortType">

<operation name="GetLastTradePrice">

<input message="tns:GetLastTradePriceInput"/>

<output message="tns:GetLastTradePriceOutput"/>

</operation>

</portType></definitions>

UDDI Defined

Universal description, discovery, and integration A platform-independent, XML-based registry for businesses worldwide

to list themselves on the Internet UDDI is an open industry initiative (sponsored by OASIS) enabling

businesses to discover each other and define how they interact over the Internet

So What is WSDL in English?

The UDDI authors had a vision of a world in which consumers of Web Services would be linked up with providers through a dynamic brokerage system Anyone needing a service would go to a broker and select one This vision has not come to pass

Instead, services write custom service endpoints with custom WSDL descriptions

Consumers then hard-code the URLs to their SOAP endpoints, working only with specific systems

The most common place that a UDDI system can be found is inside a company where it is used to dynamically bind client systems to implementations

Web Services – The Graphic

UDDIRegistry

ServiceRequestor

ServiceProvider

ServiceBroker

SOAP

WSDL(Publish)

WSDL(Discovery)

Agenda

The Technologies







The Server Side

Web Services are a Request/Response architecture

The Server is the “Response” side Responds to a Web Service Client Request

Typically over port 80

Does not have a User Interface

Can be written in any language LotusScript Java C# C++ etc

The Server Side

Web Services are encoded using one of the following WSDL Styles RPC/encoded RPC/literal Document/encoded Document/literal

The WSDL style determines the formatting of the SOAP request/response

See the following Developerworks article on a discussion of WSDL Styles http://www-128.ibm.com/developerworks/webservices/library/ws-

whichwsdl/

The Server Side

Receives a Web Service Client Request (formatted as SOAP) Parses the request

Reads the invoking method and parameters Invokes the specific method

Using parameters passed in the request Returns

The method response (formatted as SOAP)or

An Error (formatted as SOAP)

The Server Side

New Design Element in Domino 7 Allows for both LotusScript and Java coded Web Services

No specific Design element in Domino 6 Web Services can be coded as Java Agents

Agenda

The Technologies







The Client Side

The “Response” side of the Web Service Request/Response architecture

Includes the User Interface Designed to capture method parameters to be passed to the web

service

Can be written in any language LotusScript Java C# C++ etc

The Client Side

Uses the Web Service WSDL file to determine Methods Data Types Service End Points (URL of Web Service)

Sends a Web Service Server Request (formatted as SOAP) Takes method parameters from the UI and formats a SOAP request that is

posted to the Server Side Web Service Waits for the Response

The returned method call values An error

Processes the Response Takes the response and formats it to appropriate output for the calling user

interface

– Typically HTML

The Client Side

Neither Domino 6 or 7 have native Web Service Client capabilities

Web Service clients are coded as Agents

Java Agents work best Using native networking available in the java.net package Post SOAP Envelope to the Web Service Process the response from the web service Use Proxy classes generated by Web Service tools (like Eclipse)

Agenda

The Technologies







Eclipse

Eclipse is an Open Source Tool platform Current version is 3.2.x Download from

http://www.eclipse.org Additional functionality is available via the Callistro project

Java EE and Web Tools Plug-in (WTP) Data Tools (DTP) Graphical Editing Framework (GEF) Visual Editor (VE) … and more

Eclipse

In order to develop Web Services and Web Service Clients in Eclipse Download the following software

Java SDK from Sun or IBM ( 1.5 or higher) J2EE runtime Server (like Tomcat 5.5 ) Eclipse 3.2.x

Install software in this order Java SDK J2EE Runtime Server Eclipse

Eclipse

After Eclipse is installed From the menus choose

Help / Software Updates / Find and Install Choose “Search for new features to install” Select “Callistro Discover Site” At the very least include the J2EE and Web Tool (WTP) project

Eclipse

Periodically run “Help / Software Updates / Find and Install“ to keep Eclipse up to date

Add Tomcat Server Runtime to Eclipse configuration From the menu choose “Window / Preferences” In the dialog box choose “Server / Installed Runtimes” Add Tomcat to the

configuration

Eclipse

Create a Dynamic Web Project File / New Project

Dynamic Web Project

Eclipse

Provide a project name and target runtime

Eclipse

Change the Java compiler level to 1.4 for Domino 7 and 1.3 for Domino 6

Keep ND6 and ND7 codein separate projects

Eclipse

The default values for the rest of the dialog settings are fine

Click “Finish” to create the Dynamic Web Project

Eclipse

Add the necessary Domino Jar files to the project Notes.jar (For Clients)

ND7

– Located in the installdir\jvm\lib\ext ND6

– Located in the installdir Websrv.jar (For Server Services)

ND7

– Located in the installdir\jvm\lib\ext

ND6

– N/A

Eclipse

In the new project, under Java Resources Create a new Package (Your companies reverse DNS name) Place all Web Service Services and Web Service Client code in this

package

Eclipse

There is a known issue (bug) when working with Web Services in Eclipse that causes an Out Of Memory Exception (OOME) To circumvent this add the following to the Eclipse start up settings

-vmargs -XX:MaxPermSize=256m

Configuring Eclipse

Agenda

The Technologies








The steps to develop a Web Service Client are the same regardless of the Domino Platform Get a copy of the Web Service WSDL

The encoding used to create the Web Service will determine the SOAP format that will need to be used

In Eclipse Import the WSDL file into a Dynamic Web Project Use the Web Service wizards to generate needed code

For manual clients Test the Web Service in Eclipse’s Web Service Explorer

– This will create the SOAP Request/Response objects needed to code the web service client by hand

For Dynamic Clients Generate Client code from Web Services menu


General Consideration for Web Service clients If you will be consuming a Domino Web Service (6 or 7) FROM a web

agent in Domino (6 or 7) then you must Enable concurrent web agents

– Change the Server documentor

– Update the notes.ini

– DominoAsynchronizeAgents=1 If this is not set then the server will “hang”

All agents that are web service clients must have a runtime security setting of“2. Allow restricted operations”

Agenda

The Technologies







Domino 6 Web Service Clients

Web Services in Domino are implemented as Agents

Parameters can be passed into the Agents via Web Forms Create a form in Domino with the fields that will contain the data to be

passed to the Web Service In the WebQuerySave Event of the form

Create a Java Agent that Reads the parameter values from the form Creates the SOAP Envelope using the form data Post the SOAP XML to the Web Service Parse the response from the web service Output the results (Typically HTML)


The required SOAP Request/Response code can be generated by the Eclipse Web Services Explorer

To generate the required SOAP Request/Response Import the WSDL file into Eclipse Test with the Web Services Explorer Review the generated SOAP Request/Response output Use this code to create a Web Service Agent in Domino


Import the Web Service WSDL into an Eclipse Dynamic Web Project under the “WebContent” folder Importing WSDL documents to WSDL folder is not required, but will

keep all of your project WSDL document in the same folder


Right click on the WSDL fileFrom the context menu choose

“Web Services / Test with Web Services Explorer”


Test with the Web Services Explorer Click on the Method Name in the Navigator on the left hand side Provide a valid value for the method and click the “Go” button in the

“Actions” window The results will be displayed in the “Status” window on the bottom


Review the generated SOAP Request/Resonse In the “Status” window click on the “Source” link to display the SOAP

Request/Response Envelopes


The raw text xml of the SOAP Request/Response can be accessed by right clicking over the Envelope code and choosing “View Source” from the context menu

Use this code in your Web Service Client


Database: BP201

Forms: D6WebServiceLookupForm

Web Service: GetInetAddressWebService

Web Service Client: D6GetInetAddressWebServiceClient

Pages/WSDL: GetInetAddress.wsdl

Agenda

The Technologies








Domino 7 Web Service Clients can be created in the EXACT same way as Domino 6 Web Service Clients


Database: BP201

Forms: D7WebServiceLookupForm

Web Service: WSDemo1

Web Service Client: D7GetInetAddressWebServiceClient

WSDL: WSDemo1.wsdl


Instead of hard coding the SOAP Request/Response into the agent, you can use “Proxy” code that is generated by Eclipse when creating a Web Service Client

This will require that specific resources be copied to the developers workstation and the server The following files will need to be copied to the installdir/jvm/lib/ext folder

axis.jar commons-logging.jar commons-discovery.jar

These files are part of the Eclipse Dynamic Web Project and are located in WEB-INF/lib folder

These files can not be added to individual agents The developer client / server will have to be restarted after these files are

added to the ext folder


Create Web Service Client Proxy Code Import the WSDL file into a Dynamic Web Project in Eclipse Use the Web Service “Generate Client” wizard to develop client proxy

code Optionally create a Test client in eclipse that uses the proxy code

to call the Web Service

Create an Agent that Imports the proxy code as part of the agent Instantiates a new instance of the Proxy Class Calls the web Service method passing the appropriate parameters Outputs the results of the Web Service (Typically HTML)


Generate Web Service Client Proxy Code Right click on the WSDL file and choose “Web Services / Generate

Client”


Roll the “Slider” on the left hand side until “Assemble client” is displayed. Click “Finish” to create code


This will generate the proxy code in the src folder of the current project

Five files will be created DominoSoapBindingStub.java

This file is created with the same name forevery client generated

If creating multiple clients in the sameproject then refactor (rename) this file

WSDLFILENAME.java WSDLFILENAMEProxy.java WSDLFILENAMEService.java WSDLFILENAMEServiceLocator.java

These files are created using the WSDLfile name as a prefix


You can create a test class in Eclipse to test the Web Service using the proxypackage com.nnsu;

public class WSDemo1TestClient {

public static void main(String args[]){

try {

WSDemo1Proxy wsd1 = new WSDemo1Proxy();

String emailaddress = wsd1.getEmailAddress("Jeanne");

System.out.println(emailaddress);

} catch (Exception e){

e.printStackTrace();

}

}

}


Create the Web Service Client as an Agent in Domino Import the Proxy files from Eclipse into the Agent via the “Edit Project”

button


Complete the Agent code to Accept parameter input from a Web Form Create an Instance of the Web Service Client proxy Call the Web Service method Process the response


Database: BP201

Forms: D7WebServiceLookupFormWithProxy

Web Service: WSDemo1

Web Service Client: ND7WebServiceClientWithProxy

WSDL: WSDemo1

Wrap Up

Two biggest “Gotchas” in coding web service clients in Domino Agent Run Time Security level not set to “2” Domino Web Service Clients calling Domino Web Services without enabling

run web agents concurrently DominoAsynchronizeAgents=1

All you need to create web service clients A copy of the Web Service WSDL file Eclipse with the Web Tools Plug-in

Web Service Clients are implemented as Agents in Domino

Web Service Clients can be coded Manually – Hard coded SOAP request/response Dynamically – Use generated proxy code

Wrap Up

References and Resources TLCC (Booth Number 611)

Java Computer based training via Notes Databases www.tlcc.com

The View (Booth Number 303) www.eview.com

SUN Developer Network java.sun.com

Eclipse Project www.eclipse.org

Tomcat tomcat.apache.org

Wrap Up

References and Resources (cont) IBM Developer Works

www.ibm.com/developerworks www.ibm.com/developerworks/java www.ibm.com/developerworks/lotus www.ibm.com/developerworks/webservices

Questions?

[email protected]

© IBM Corporation 2007. All Rights Reserved.

© IBM Corporation 2007. All Rights Reserved.

The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are provided for informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or advice to any participant. While efforts were made to verify the completeness and accuracy of the information contained in this presentation, it is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this presentation or any other materials. Nothing contained in this presentation is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Sametime, WebSphere, Workplace and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

® bp201: coding web service clients for ibm lotus domino paul t. calhoun / cto, netnotes solutions...

Documents

web serviceusually

web servicemessage

web documentsit

coding web service clients

xml applications

online xml

service requestor

soap message