IBM Lotus Component Designer V6.0 provides a powerful way to leverage the almost unlimited number and variety of Web Services available on the Internet or within your organization. Web services can perform tasks for your component, such as converting currencies, searching the Internet, or returning a United States zip code.

In this article, we briefly discuss Web services in general, discuss them in the context of Lotus Component Designer, and then walk through the process of employing a fictional Web service in a Lotus Component Designer component.

What are Web services?

Generally speaking, Web services are programmatic interfaces that allow software to interact with other software over a network.

The Web service is hosted on a server in the network and described in XML in a Web Services Description Language (WSDL) document. WSDL files can be stored on your local computer, on a network, or in Universal Description, Discovery, and Integration (UDDI) directories.

The Web service consumer software provides data in the XML format specified in the WSDL file, and then sends it to the Web service provider in XML documents (called request documents in Lotus Component Designer). The Web Service provider performs its service on the data, and then returns acted-on data to the consumer in XML documents (called response documents in Lotus Component Designer).

Back to top

Using Web services in Lotus Component Designer

Figure 1 shows the basic high-level workflow for using a Web Service in Lotus Component Designer:

1. You find a Web service you want to use, and then create a Web service adapter for it in Lotus Component Designer.
2. You add to a page UI controls that accept input parameters and display results returned by the service.
3. You deploy the component to IBM WebSphere Portal as a portlet.
4. At runtime, a component user enters parameters on the page in the portlet.
5. The portlet sends those parameters in an XML request document to the Web service provider.
6. The Web service provider receives the request document, performs an action on the data, and returns an XML results document to the portlet that contains the results.
7. The portlet displays results to the user.

Back to top

Using the stockInfo Web service in a component

Our component consumes a fictional Web service called stockInfo that returns information on companies based on stock tickers users provide. Users enter a stock ticker ID into a field and click a button, and the Web service returns information about that company, such as its name, ticker, and current stock price.

You perform these steps to consume the Web service:

1. Create an adapter.
2. Create design elements.
3. Bind the elements to the Web service.

Back to top

Creating the adapter

The first thing you do is create an adapter for the Web service in Lotus Component Designer.

To create an adapter, you must either provide a service’s WSDL location directly (URL or local) or search for the WSDL in a UDDI directory. The stockInfo service is provided by a fictional company called Stock Prices For You, and its WSDL file is in a UDDI directory at the Web site StockPricesForYou.com.

You perform these steps to create an adapter:

1. In Lotus Component Designer, select the component in the Component Navigator on the left, double-click Component Options as shown in figure 2, and then select Show external data options.

This displays an External Data section in the Component Navigator, which includes a Web Services Adapters section, as shown in figure 3.

2. Double-click Web Services Adapters and then click the New Web Services Adapter button. In the New Web Services Adapter dialog box, name the adapter and click Next.
   In this case, the company has posted its service in a UDDI directory on the Web, so in the Web Service Sources dialog box, select the "Use a Web Service from a UDDI directory" option, then click Add.

3. In the UDDI Search dialog box shown in figure 4, enter a UDDI server URL and (optionally) an organization and service name, then click Search.

The Results section on the right is populated with the available Web services and their operations. Select the stockInfo service and all of its operations, then click OK and OK again.

As part of the adapter creation process, a copy of the service's WSDL file is pulled down to your computer and stored in the component's directory in your Eclipse workspace, for example C:\Eclipse32\Designer\workspace\MyComponent\WebContent\WebServiceAdapter. Also in that directory is an Adapter file containing the information necessary to pass the request and results documents between your computer and the Web services server, plus a Properties document, which contains some information, such as the creator of the adapter, the date and time created, and the author's name.

In the Component Navigator, expand the External Data - Web service Adapters section, and then double-click the new adapter to open it. You can see all relevant information for the Web Service in figure 5, including the schemas of the request, response, and fault documents. (The fault document describes in XML what happens when there is an error; for example, if the data provided was not in an acceptable format, the component might display the text “Please use an acceptable format in this field.” The stockInfo service has no fault document.)

By clicking the Test Adapter tab at the bottom of the canvas containing the Web service description, you can test the operation by editing the request document and clicking Invoke Web Service.

Back to top

Adding design elements

You want to design a page in the component so that a user enters stock tickers into a field and clicks a button, and the results information is displayed in a group of fields lower on the page. You'll use an edit box for users to enter stock tickers, a button to invoke the Web service, and a repeat control containing edit boxes to display the response data.

Repeat controls contain a set of other controls, and they repeat that set of controls multiple times on a page. In this case, users can enter multiple stock tickers, andyou don't want to have to create many sets of the same controls on the page to display multiple sets of response data. The repeat control allows you to create one set of display controls, and if you get multiple responses, it repeats the display for each response. For example, if a user types “IBM YHOO” (YHOO is a stock ticker for Yahoo!), one set of data displays for IBM and another set displays for Yahoo!.

NOTE: For help performing the Lotus Component Designer tasks such as creating a page or controls, see the Lotus Component Designer Help.

Perform these steps to add the design elements:

Create a page in the component.

Make the Web Service adapter the page's data source.

1. Click in the page.
2. Click the Data tab in the Properties view.
3. Click Add, then Web Service.
4. In the Web Service field, select the stockInfo adapter.
5. Click File - Save.
6. Add a label titled "Please enter one or more stock tickers separated by space:" to the page.
7. Add an edit box below the label.
8. Add a button with the label Get Stock Quote.
9. Add a repeat control.
10. Add labels and edit box controls to the repeat control to display the results data as shown in figure 6, for example, company name, stock ticker, and stock quote.

Back to top

Binding the elements to the Web service

Next you bind your controls. Once you have an adapter for the Web service, you can use the service's request document, response document, or fault document as a data source for a page, and you can bind controls to elements in any of them.

First, bind the edit box in which users type stock tickers to the element in the request document that contains stock ticker data. Then, bind the repeat control to the response document because everything that is displayed in the repeat control will be from the response document. Then, edit boxes that display the company name, stock ticker, and stock quote to the elements in the results document that contain that data. Then, create an event for the button that invokes the Web service.

Bind the stock ticker edit box to the stockTicker element in the request document as shown in figure 7.

1. Click in the edit box in which users type tickers.
2. Click the Data tab in the Properties view.
3. Select the Use data binding option.
4. Select requestDocument in the Data source field.
5. Select the stockTicker element in the Data binding field.

Bind the repeat control to the highest element in the response document as shown in figure 8.

1. Click in the repeat control.
2. In the Repeat tab in the Properties view, select Use data binding.
3. In the Data source field, select responseDocument.
4. In the Data binding field, select an element that contains the display elements somewhere within it. In this case, you'll bind to the top element in the response document, /stockInfo.

Bind each edit box in the repeat control to an appropriate element in the response document, as shown in figure 9. For example:

1. Click in the edit box that displays the name of the company.
2. Click the Data tab in the Properties view.
3. Select Use data binding.
4. Select responseDocument in the Data source field.
5. Select the companyName element in the Data binding field.

Add an Invoke the Web Service event to the button as shown in figure 10:

1. Select the button.
2. Click the Events tab in the Properties view.
3. Expand the Mouse section in the pane on the left, and then click onClick.
4. In the pane on the right, select Simple Actions, and then click Add Action.
5. In the Category field, select All.
6. In the Action field, select Invoke Web Service.
7. In the Web service name field, select the name of the service, in this case stockInfo.
8. Select Full Update.

Back to top

Conclusion

In a fiture release, look for support for WebSphere Service Registry and Repository (WSRR), which is IBM Service-Oriented Architecture functionality. It is a directory similar to UDDI, but it provides an extended set of capabilities. A WSRR directory stores information about Web Services and makes that information available to components. Components deployed as portlets on WebSphere Portal that consume Web services are also registered in WSRR, so administrators can keep track of which portlets use which Web services.

Resources

Learn

• Lotus Component Designer product page.
  
  
• Lotus Component Designer product documentation.
  
  
• Read the article, "Using JavaScript in IBM Lotus Component Designer".
  
  
• Read the W3C Web Services Activity Statement.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• What are Web services?
• Using Web services in Lotus Component Designer
• Using the stockInfo Web service in a component
• Creating the adapter
• Adding design elements
• Binding the elements to the Web service
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

WebSphere Application Server can leverage its built in Web Services support to expose services to remote consumers in an industry-standard way.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and includes built in Web Services support.
• Article: Learn how to use of the JAX-WS programming model to create dispatch and dynamic proxy clients and how to create an asynchronous Web service client.
• Tutorial: This tutorial takes you through the steps to deploy Data Web Services to the WebSphere Application Server Community Edition.
• Demo: This demo shows how to extract and install the IBM Java Platform, Java EE 5 SDK with WebSphere Application Server.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers