Transcript BP201 - NetNotes Solutions Unlimited

BP201: Coding Web Service Clients For IBM Lotus Domino
Paul T. Calhoun / CTO, NetNotes Solutions Unlimited, Inc.
®
I AM !
Paul T. Calhoun
Chief Technology Officer
NetNotes 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
 Developing Web Service Clients for Domino 7
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
 Developing Web Service Clients for Domino 7
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/"
SOAPENV: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
Service
Broker
WSDL
(Discovery)
Service
Requestor
UDDI
Registry
WSDL
(Publish)
SOAP
Service
Provider
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
 Developing Web Service Clients for Domino 7
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
 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
 Developing Web Service Clients for Domino 7
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
 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
 Developing Web Service Clients for Domino 7
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 code
in 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
 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
 Developing Web Service Clients for Domino 7
Developing Web Service Clients
 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
Developing Web Service Clients
 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 document
or
– 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
 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
 Developing Web Service Clients for Domino 7
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)
Domino 6 Web Service Clients
 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
Domino 6 Web Service Clients
 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
Domino 6 Web Service Clients
 Right click on the WSDL file
From the context menu choose “Web
Services / Test with Web Services
Explorer”
Domino 6 Web Service Clients
 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
Domino 6 Web Service Clients
 Review the generated SOAP Request/Resonse
 In the “Status” window click on the “Source” link to display the SOAP
Request/Response Envelopes
Domino 6 Web Service Clients
 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
Domino 6 Web Service Clients
Database: BP201
Forms: D6WebServiceLookupForm
Web Service: GetInetAddressWebService
Web Service Client: D6GetInetAddressWebServiceClient
Pages/WSDL: GetInetAddress.wsdl
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
 Developing Web Service Clients for Domino 7
Domino 7 Web Service Clients
 Domino 7 Web Service Clients can be created in the EXACT same
way as Domino 6 Web Service Clients
Domino 7 Web Service Clients
Database: BP201
Forms: D7WebServiceLookupForm
Web Service: WSDemo1
Web Service Client: D7GetInetAddressWebServiceClient
WSDL: WSDemo1.wsdl
Domino 7 Web Service Clients
 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 WEBINF/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
Domino 7 Web Service Clients
 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)
Domino 7 Web Service Clients
 Generate Web Service Client Proxy Code
 Right click on the WSDL file and choose “Web Services / Generate Client”
Domino 7 Web Service Clients
 Roll the “Slider” on the left hand side until “Assemble client” is
displayed. Click “Finish” to create code
Domino 7 Web Service Clients
 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 for
every client generated
 If creating multiple clients in the same
project then refactor (rename) this file
 WSDLFILENAME.java
 WSDLFILENAMEProxy.java
 WSDLFILENAMEService.java
 WSDLFILENAMEServiceLocator.java
 These files are created using the WSDL
file name as a prefix
Domino 7 Web Service Clients
 You can create a test class in Eclipse to test the Web Service using
the proxy
package 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();
}
}
}
Domino 7 Web Service Clients
 Create the Web Service Client as an Agent in Domino
 Import the Proxy files from Eclipse into the Agent via the “Edit Project” button
Domino 7 Web Service Clients
 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
Domino 7 Web Service Clients
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.