Oracle9iAS Portal Developer Kit

FAQ on Web Services and PDK-Java

This document provides answers for frequently asked questions about using Web Services in portlets with the Oracle9iAS Portal Developer Kit.

ASSUMPTIONS

  1. You have a basic understanding of Oracle9iAS Portal and PDK-Java.

  2. You have a basic understanding of Web Services and the SOA(Service Oriented Architecture).  For more background information, (including terminology like SOA, SOAP, UDDI, WSDL), you will find further resources here.

GENERAL

  1. What kind of Web Services can be rendered in portlets?

    ANS:  With Oracle9iAS Portal Developer Kit (PDK), you can invoke both RPC style and DOC style web services in a declarative fashion. 

  2. What do I need to install to be able to invoke Web Services with Oracle9iAS Portal?

    ANS:  To get started right away, you need to install: OC4J Oracle9iAS Release 2 - J2EE Developer's Preview, Oracle9i JDeveloper Release Candidate, and PDK-J2EE ( to be released as part of PDK-April shortly). Also remember to provide the Proxy host and port while starting up OC4J. (e.g. java -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80 -jar oc4j.jar ).

  3. What are the basic steps involved in plugging-in a Web Service to a portlet?

    ANS:  Point the PDK-Java framework to your Web Service, and add the portlet to a page:

    1. For an RPC style web service, use the JDeveloper Web Service Wizard to generate a 'stub' for your Web Service from its WSDL document.
    2. Use the sample provider definition file (provider.xml) to fill in portlet name, title, description, and Web Service details
    3. Register the provider with Oracle9iAS Portal ( you can use the hosted Portal Studio solution too)
    4. Display the portlet on a page
    5. Customize the portlet rendering with XSL transformations.
    6. Add portlet features as required

  4. How can I invoke a DOC style Web Service in a portlet?

    ANS:  To invoke a DOC style service, you need to use the built-in DocWebServiceRenderer class, and fill in relevant tags in the provider.xml.

  5. How can I invoke an RPC style Web Service in a portlet?

    ANS:  To invoke an RPC style service, you need to use a tool such as the JDeveloper to generate a 'stub' for your Web Service from its WSDL document, and then plug the stub into the RPCWebServiceRenderer class by filling in tags in the provider.xml

  6. Which are the important tags in the provider.xml file relevant to Web Services?

    ANS:  For DOC style portlets, the important tags are endpointURL, element, attribute, literal and responseXSL. For RPC style portlets, the important tags are className, renderMethod, param, and responseXSL.

  7. What do the Provider definition (provider.xml) tags signify and how do these tags map to the WSDL document (*.wsdl) of the Web Service?

    ANS:  Every web service publishes its WSDL document to a site like xmethods.com, or a UDDI directory. In lay terms, the tags:

    1. endpointURL maps to the endpoint of the service provider (DOC)
    2. literal contains elements and attributes and maps to request parameters (DOC)
    3. renderMethod maps to a particular method on the service (RPC)
    4. param maps to a method parameter (RPC)
    5. className maps to the class name of the JDeveloper generated service stub class (RPC) 

    For further details on WSDL documents, refer to WSDL 1.1.

  8. How can my portlet handle literal XML response from a Web Service?

    ANS:  Web Services (mostly DOC style) that return literal XML that can be handled by a built-in literal XML handler class in the PDK-J2EE. You need to set the literal tag of provider.xml to point to these built in classes ( LiteralXML and LiteralXML$Handler).  

  9. How do I customize the way the Web Service portlet is rendered?

    ANS:  A Web Services response can be passed through an XSL filter to apply the relevant transformations to control the look and feel. You need to set the  responseXSL tag for ponting to the name of the stylesheet which will be generated or used, if provided.

  10. Do I have to code my own stylesheets from scratch?

    ANS:  No. PDK-J2EE would generate a default stylesheet if it does not find the named .xsl. You can then modify this generated stylesheet, if you need to. 

  11. How can I track the Web Service response XML or debug issues?

    ANS:  You can set the logging tag to true for your portlet, in which case both the Web Service request and response XMLs are generated.  This is the response XML on which your XSL transformation is going to be applied.  You will find these under the j2ee/home/applications directory path of OC4J, in the same directory as the provider.xml.  You can also look at the application.log under the j2ee/home/application-deployments/<appname> directory for any error log information. 

  12. How can I make my Web Service portlet be driven by another portlet?

    ANS:  You can have one master portlet drive another details Web Services portlet(s) by passing parameters between them. You can bind the service parameter to a URL parameter declaratively, and it would automatically be driven by the URL parameter passed from another portlet. 

  13. What kind of parameter bindings can I setup?

    ANS:  Web Service parameters can use the provider.xml tags to bind to:

    1. Constants - Portlets can be setup to pass a constant value to a service parameter. (e.g. <param>10</param> )
    2. URL parameters - Portlets can be setup to bind a URL parameter to a service parameter. (e.g. bind="urlParams/zipCode")
    3. Session attributes - Portlets can use session parameters for bindings.  (e.g. bind="session/zipCode" )
    4. Portlet render request parameters - Attributes of the portlet render request can be used for bindings. (e.g. bind="request/user/name")
    5. Edit data - Customization data can be passed to the Web Service. (e.g. bind="editData/zipCode" )

  14. How can I provide  a default value for a parameter?

    ANS:  You can use the default tag n the provider.xml to provide a default value to the Web Service.

  15. How can I provide a prompt for an input parameter? 

    ANS:  You can use the prompt tag in the provider.xml to drive the generation of an HTML form which prompts for the input parameters to the Web Service.   

  16. How can I prevent the Web Service from being called, if it is not supplied a mandatory parameter?

    ANS:  You can set the mandatory tag to true for your parameter, to prevent a call to the Web Service unless a parameter value is passed.

  17. What does a sample provider definition file look like?

    ANS:  You can find a sample provider.xml for both RPC style and DOC style portlets here.

  18. How do I add additional portlet features to my Web Service portlet?

    ANS:  You can add portlet features like Customization, as you would normally do in a Java portlet. You can add an Edit page, and more pages for the different show modes. You can bind the Web Service parameters to the Edit data that is updated in the Edit page. You can save the customization data in the preference store, or the session store and even bind the session parameters to the Web Service parameters. There are other features that would make sense in coding within the Web Service, if you are the Web Service developer.

  19. How can I build my own Web Service?

    ANS:  You can use any toolkit like Oracle9i JDeveloper to develop in any programming language and deploy these as Web Services. Oracle9i JDeveloper has some great features for Web Services development and deployment, like the Web Services publishing wizard and stub generation wizard.

  20. Additional resources for Web Services?

    ANS:  You can find further resources from the links provided below.

 

RESOURCES

Get a grip on Web services

More Resources

 

BACKGROUND

Web Services are discrete business services that can be programmatically accessed over the internet in a standard manner.  They encapsulate business services that can be platform and language independent.  They can be described, published, discovered and invoked in a distributed computing environment.  

There are two "styles" of SOAP communication -  RPC  based(Remote Procedure Calls) and DOC based (Document style).  In the DOC style, the SOAP Body carries a generic XML document.  There's no explicit concept of "method invocation" coming into play here; it's simply about passing XML docs back and forth between the client and server. Most of the early work on SOAP toolkit implementations focused on RPC-style SOAP.  Today, it's more balanced between RPC and document styles. Both styles are suited for different situations.   In some cases, the expressiveness of XML documents is preferable needed; in other cases, the easy integration into development environments that SOAP RPC gives you  (with automatic type serialization/ deserialization, etc.) is important.  

Service-Oriented Architecture (SOA)  SOA is a conceptual architecture for implementing dynamic e-business. Today, most of the systems and applications running in the business world are made up of tightly-coupled applications and subsystems. The drawback with this is that a change to any one subsystem can causes breakage in a variety of dependent applications. This brittle aspect of existing systems is in part responsible for the high cost of system maintenance and the limitations around the number of trading partners one can manage.

A service provider is a Network node that provides a service interface for a software asset that manages a specific set of tasks. A service provider node can represent the services of a business entity or it can simply represent the service interface for a reusable subsystem.

A service requestor is a Network node that discovers and invokes other software services to provide a business solution. Service requestor nodes will often represent a business application component that performs remote procedure calls to a distributed object, the service provider. In some cases, the provider node may reside locally within an intranet or in other cases it could reside remotely over the Internet. The conceptual nature of SOA leaves the networking, transport protocol, and security details to the specific implementation.

The third SOA participant is that of the service broker; it is a Network node that acts as a repository, yellow pages, or clearing house for software interfaces that are published by service providers. A business entity or an independent operator can represent a service broker.

These three SOA participants interact using three basic operations: publish, find, and bind. Service providers publish services to a service broker. Service requesters find required services using a service broker and bind to them.

GLOSSARY

SOAP: Simple Object Access Protocol is an XML-based lightweight protocol for the exchange of information in a decentralized, distributed environment. SOAP defines a messaging protocol between requestor and provider objects, such that the requesting objects can perform a remote method invocation on the providing objects in an object-oriented programming fashion.

WSDL: The Web Services Description Language is an XML vocabulary that provides a standard way of describing service IDLs. WSDL provides an abstract language for defining the published operations of a service with their respective parameters and data types. The language also addresses the definition of the location and binding details of the service.

UDDI: The Universal Description, Discovery, and Integration specification provides a common set of SOAP APIs that enable the implementation of a service broker. The UDDI specification was outlined to help facilitate the creation, description, discovery, and integration of Web based services.

 

SAMPLE PROVIDER DEFINITION FILE

The following provider.xml illustrates the tags used for an RPC style Web Service portlet:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?providerDefinition version="3.1"?>
<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
  <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
    <id>1</id>
    <name>LocalTemperature</name>
    <title>Temperature Web Service Portlet</title>
    <shortTitle>Temperature Information</shortTitle>
    <description>Web Service demonstration portlet.</description>
    <timeout>100</timeout>
    <timeoutMessage>Temperature portlet timed out</timeoutMessage>
    <renderer class="oracle.portal.provider.v2.render.RenderManager">
      <showPage class="oracle.portal.provider.v2.webservice.RPCWebServiceRenderer">
        <contentType>text/html</contentType>
        <logging>false</logging>
        <className>webservices.WeatherRetrieverStub</className>
        <renderMethod>GetTemperature</renderMethod>
        <param class="oracle.portal.provider.v2.webservice.WebServiceRenderer$URLParam">
          <name>p_zip</name>
          <default>94065</default>
          <prompt>Please enter a Zip Code</prompt>
        </param>
        <responseXSL>getTemperature.xsl</responseXSL>
      </showPage>
    </renderer>
  </portlet>
</provider>

The following provider.xml illustrates the tags used for a DOC style Web Service portlet:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?providerDefinition version="3.1"?>
<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
  <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
    <id>1</id>
    <name>WeatherInformation</name>
    <title>Weather Web Service Portlet</title>
    <shortTitle>Weather Information</shortTitle>
    <description>Web Service demonstration portlet.</description>
    <timeout>100</timeout>
    <timeoutMessage>Weather Information portlet timed out</timeoutMessage>
    <acceptContentType>text/html</acceptContentType>
    <renderer class="oracle.portal.provider.v2.render.RenderManager">
      <contentType>text/html</contentType>
      <charSet>UTF-8</charSet>
      <showPage class="oracle.portal.provider.v2.webservice.DocWebServiceRenderer">
        <contentType>text/html</contentType>
        <logging>true</logging>
        <endpointURL>http://hosting001.vs.k2unisys.net/Weather/PDCWebService/WeatherServices.asmx
        </endpointURL>
        <soapAction>http://www.unisys.com/WebServices/GetWeather</soapAction>
        <literal class="oracle.portal.provider.v2.webservice.LiteralXML"
          handler="oracle.portal.provider.v2.webservice.LiteralXML$Handler">
          <element name="GetWeather">
            <attribute name="xmlns">http://www.unisys.com/WebServices/</attribute>
            <element name="ZipCode"
              bind="urlParams/p_zip"
              default="94065"
              prompt="Please enter a Zip Code"/>
          </element>
        </literal>
        <responseXSL>getWeather.xsl</responseXSL>
      </showPage>
    </renderer>
  </portlet>
</provider>

Revision History: