Oracle9iAS Portal Development Kit

Oracle9iAS Portal Developer Kit
Understanding Web Services for Portlets

PDK-Java provides an out-of-the-box service for invoking Web Services. It provides an abstraction to handle communication with Web Services. It allows you to declaratively invoke Web Services with the built-in Web Services Renderer classes that it provides.

With PDK-Java, you can invoke both procedure-oriented RPC style Web Services as well as document-oriented Doc style Web Service. For DOC style services, the SOAP Body carries a generic XML document, whereas in RPC style services, there's an explicit concept of "method invocation" coming into play. PDK-Java supports both these styles with specialized renderer classes.

This document provides an overview of the built-in Web Services renderers that can be used to expose any Web Service as a portlet. To see sample Web Services portlets provided as part of PDK-Java, follow the instructions provided in Installing the Web Services Sample Portlets.

ASSUMPTIONS

You have installed PDK-Java as described in the article Installing the PDK-Java Framework and samples
You are familiar with portlet basics and the concept of a renderer. If this is not the case, see the article How to Build a Java Portlet.

BUILDING WEB SERVICE PORTLETS

To build a portlet using a Web Service, you need to follow the following three main steps:

You point thePDK-Java framework to your Web Service by filling in the appropriate tags in the provider.xml file. You can fill in portlet information, and the Web Services related details using the built-in renderers.
Register your Provider with Oracle9iAS Portal
Display the portlet on a page

For building your own Web Service, you can use Oracle9i JDeveloper which has a great feature set especially for Web Services. The Web Services Description Language is an XML vocabulary that provides a standard way of describing Web Service details like the service location, method parameters and data types With Jdeveloper, you can use features like the client stub generation wizard that takes a WSDL URL and generates the stub class automatically. This stub class provides a wrapper for communication between the Portal and the Web Service.

So you can use JDeveloper to complement the capability of invoking Web Services. For an RPC style Web Service, you need you need to to use the built-in RPCWebServiceRenderer class, and fill in relevant tags in the provider.xml.

You can setup your Web Service to use the generated stub classes that facilitate communication between the Portal and the Web Service.
You can also have Web Service portlets communicate with other portlets, and pass parameters to Web Service portlets with declarative parameter bindings.
You can also control how the portlet displays the data from a Web Service by passing the data through XSL stylesheets.

For a DOC style Web Service, you need to to use the built-in DocWebServiceRenderer class.

You can setup your Web Service to use the WSDL details like endPointURL and SOAPAction that facilitate communication automatically. You can plug-in such information from the WSDL doc of the Web Service, directly into the provider.xml.
PDK-Java provides built-in classes to handle literal XML and you have to just point to the existing classes.
As before, you can also have Web Service portlets communicate with other portlets, and pass parameters to Web Service portlets with declarative parameter bindings.
You can also control how the portlet displays the data from a Web Service by passing the data through XSL stylesheets. If you do not provide a stylesheet, a default one is generated for you by PDK-Java.

MORE ABOUT THE WEB SERVICE RENDERERS

The PDK-Java Web Service Renderers are an extension to the basic portlet renderer framework designed to allow you to expose existing web services as portlets with the minimum of effort. By building on the same declarative portlet building approach that is used throughout the JPDK, the renderers provide a powerful way of "wiring in" almost any SOAP-based web service to Oracle9iAS Portal.

Take a look at the XML provider definition for the web service sample provider. You will find it in the following location:

j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/webservices/provider.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<?providerDefinition version="3.1"?>

<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">

<session>false</session>

<portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">

<id>1</id>

<name>WhoIs</name>

...

<showPage class="oracle.portal.provider.v2.webservice.DocWebServiceRenderer">

<contentType>text/html</contentType>

<logging>false</logging>

<endpointURL>http://www.esynaps.com/WebServices/WhoIsService.asmx</endpointURL>

<soapAction>http://tempuri.org/WhoIs</soapAction>

<literal class="oracle.portal.provider.v2.webservice.LiteralXML"

handler="oracle.portal.provider.v2.webservice.LiteralXML$Handler">

<element name="WhoIs">

<attribute name="xmlns">http://tempuri.org/</attribute>

<element name="DomainName"

bind="urlParams/domainName"

default="oracle.com"

prompt="Please enter an Internet Domain name"/>

</element>

</literal>



<escapeOutput>false</escapeOutput>

<responseXSL>whoIsResponse.xsl</responseXSL>

</showPage>

</renderer>

</portlet>

<portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">

<id>2</id>

<name>StockQuote</name>

...

<showPage class="oracle.portal.provider.v2.webservice.RPCWebServiceRenderer">

<contentType>text/html</contentType>

<logging>false</logging>

<className>oracle.portal.sample.v2.devguide.webservices.NetXmethodsServicesStockquoteStockQuoteServiceStub</className>

<renderMethod>getQuote</renderMethod>

<param class="oracle.portal.provider.v2.webservice.WebServiceRenderer$URLParam">

<name>symbol</name>

<default>ORCL</default>

<prompt>Please enter a stock symbol</prompt>

</param>

<responseXSL>stockQuoteResponse.xsl</responseXSL>

</showPage>

</renderer>

</portlet>

...

Notice that, like most of the other PDK-Java samples, it uses RenderManager as the portlet renderer controller. Also notice that each portlet supports the basic portlet Show mode by defining one of two classes as the showPage: DocWebServiceRenderer and RPCWebServiceRenderer. As you will see, these same flexible renderer classes can be used to expose almost any SOAP-based web service as a portlet without having to write a single line of Java.

The two web service renderer classes inherit most of their functionality from the WebServiceRenderer superclass, and are thus used and configured in roughly the same manner. The difference is that DocWebServiceRenderer is provided for calling "doc style" web services, which typically communicate using free-format XML, while RPCWebServiceRenderer is provided for calling "RPC style" web services, which typically use a more constrained form of XML for performing a remote procedure call (RPC) through SOAP.

By using information specified in the XML provider definition (provider.xml), the renderers allow inputs to a web service to be "wired up" declaratively to any of the following sources of information.

Portlet render request parameters, such as the username, locale and authentication level
Parameters from the request URL to the portlet. These may have been posted by a form generated by the portlet itself, an external parameter-passing portlet, or may be one of the parameters sent by Portal.
Provider session attributes
Items of customization data from a NameValuePersonalizationObject (as set in Edit and Edit Defaults modes)

The renderers operate as follows:

Determine the current values of each of the parameters to be sent to the web service.
Convert these values into the form the web service expects and send them to the web service (this is achieved differently, depending on whether DocWebServiceRenderer or RPCWebServiceRenderer is used).
Combine the response into an XML document containing all the request information and parameter bindings and pass it through an XSLT transformation to convert it into portlet HTML.

XSLT is an application of XML which allows you to definine how XML in one form should be transformed into another form of XML or HTML. As such, it is ideal for controlling the process of turning the response from a web service into porlet markup. Knowledge of XSLT is not required in order to get basic results from the renderers, however. If an XSL stylesheet has not been provided by the user, the renderers will automatically generate a default one based on the information in their parameter bindings. If any of these parameters are URL parameters, then an HTML form with appropriate input fields will even be included in the portlet.

By customizing the default XSL, a user can gain more control over the markup generated by the renderer, and can present structured information more effectively, e.g. in an HTML table. If you want to learn more about XSL and XSLT, refer to the official home page on the w3 site. Also have a look at the XML sections on otn.oracle.com to learn how Oracle supports XSL.

For more information about using Web Services Renderers, read the articles How to Build Portlets using Web Services and the Web Services FAQ

Revision History:

April 4, 2002.