Oracle Application Server Portal Developer Kit (PDK)
Installing the Web Services Sample Portlets

Introduction

The PDK provides a sample provider containing web services portlets that can be configured to run out-of-the-box. These portlets help you understand the usage of web services renderers that PDK provides.

This document explains how to configure the sample web provider that illustrates the basic web service support provided by PDK. You can also get a basic understanding about using web services in portlets from the article Understanding Web Services for Portlets.

Assumptions

• You are using OracleAS 9.0.2 or later
• You have installed PDK as described in the article Installing the PDK Framework and samples

Configuring the Sample Provider

The web service renderer sample portlets are contained in a pre-configured web provider with a service ID of "urn:ws". Registering the provider is therefore just as simple as registering any of the other PDK sample providers. However, if your web provider is running inside a firewall (as utilized in many corporate networks), there is an extra configuration step you must take to ensure that external Web Services, such as the ones used by the samples can be contacted by the web provider through HTTP. This is explained in the following subsection.

Configuring OC4J for Proxy Server

If you have to use a proxy server to access the internet from the machine that your web provider will be running on it is important that you set the http.proxyHost and http.proxyPort system properties appropriately when you start up OC4J.

http.proxyHost should be set to the host name of your proxy server
http.proxyPort should be set to the port number your proxy server uses for HTTP communications (usually 80)

If you are unsure of these settings, you may be able to determine them from your browser configuration.

To set these system properties for a standalone OC4J instance, simply use the -D JVM command line option to define these system properties when you start up OC4J. For example:

java -jar -Dhttp.proxyHost=my.proxyserver.com -Dhttp.proxyPort=80 oc4j.jar

Once you have determined the correct settings to use, you might want to configure a shortcut (on Windows) or command alias (on UNIX) that runs this command automatically.

To set these system properties for an OC4J instance within an Oracle Application Server install (e.g. OC4J_Portal), simply add the appropriate lines to the oc4j.properties file for the particular OC4J instance in which the JPDK is installed (e.g. $ORACLE_HOME/j2ee/OC4J_Portal/config/oc4j.properties) and then restart that OC4J instance. For example:

http.proxyHost=my.proxyserver.com
http.proxyPort=80

Accessing the Provider Test Page

Once OC4J is up and running with the required proxy settings (if any) you should access the web service provider test page to ensure that PDK-Java has been configured correctly. This can be done by accessing the following URL.

http://<host name>:<port number>/jpdk/providers/ws

There are several sample portlets included with the this sample. They are:

• Simple Samples for Web Services
  
  • WhoIs
  • StockQuote
  • Dictionary
    
• Parameter Passing Samples : You could use these samples by passing zipcode either as a URL parameter or as a page parameter to these portlets.
  
  • ZipcodePortlet (Master portlet for providing URL parameter)
  • LocationInformation
  • LocalWeatherInformation
  • WeatherwithDefault StyleSheet
  • LocalTimeInformation
  • LocalTemperature
    
• Newsfeed Sample
  
  • OTNNews
    
• Personalization Sample (User Preferences)
  
  • ZipcodeInYourArea
    
• Personalization Sample (Admin Preference with Edit Defaults Mode)
  
  • MessagingWebServices
    

Registering the Samples Provider with Portal

Under the Build tab (on the Builder Page), click on Register a Portlet Provider within the portlet called Providers.

1. On the first page of the wizard, fill in the following information

• Name: WebServicesProvider
• Display Name: Web Services Sample Provider
• Timeout: 100
• Implementation Style: Web

2. On the second page, fill in the following information

• URL: http://<host name>:<port number>/jpdk/providers/ws
• Service Id: urn:ws
• Login Frequency: Never

3. Click Finish

Once registered, all the sample portlets are displayed in the Portlet Repository.

Adding Sample Portlets to a Page

Display the contents of the Portlet Repository and review the sample portlets. Add any of the sample portlets listed under the Provider called "Web Service Sample Provider" to a Portal page

Create Simple Web Services page

Once you have registered the web service sample provider, you will probably want to add its portlets to a page in the usual manner. The portlets that you can view are the Stock Quote Service portlet, Dictionary Service portlet and the Who Is Web Service portlets. Try submitting values to each of the portlets in turn and note the results you get back.

Create City Search Samples page

Similarly, create a new page for parameter communicating web service portlets based on zipcode. Add the following portlets - J2EE zip code entry portlet, Location Web Service Portlet, Weather Web Service Portlet, Weather Web Service Portlet with Default StyleSheet, Local Time Web Service Portlet and Temperature Web Service potlet - to a page.

On the top left portlet, put the master J2EE-based portlet that takes a Zip Code as input and drives the other portlets. You can enter any valid zip code and it displays corresponding information in the other four web services portlets.

You have now successfully installed and setup the Web Services Samples.

Understanding the provider.xml

You can view the source provider.xml, (found under the $ORACLE_HOME/j2ee/<OC4J Instance>/applications/jpdk/jpdk/WEB-INF/providers/webservices directory) to understand how these Web Services portlets have been invoked.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?providerDefinition version="3.1"?>
<!-- These samples consume publicly available web services not under the 
     control of Oracle Corporation -->
<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
   <session>true</session>
   
   <!-- For OracleAS Portal 9.0.2 style of parameter-passing, 
   the passAllUrlParameter tag in provider.xml either should be removed or commented. -->
   <passAllUrlParams>true</passAllUrlParams> 

   <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
      <name>prefStore1</name>
      <useHashing>true</useHashing>
   </preferenceStore>

   ...

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>4</id>
      <name>ZipcodePortlet</name>
      <title>Zipcode portlet</title>
      <description>This portlet queries the ZIP code and sends a public parameter to the page.</description>
      <timeout>30</timeout>
      <timeoutMessage>Zipcode portlet timed out.</timeoutMessage>
      <showLink>false</showLink>
      <showEdit>false</showEdit>
      <showEditToPublic>false</showEditToPublic>
      <showEditDefault>false</showEditDefault>
      <showPreview>false</showPreview>
      <showDetails>false</showDetails>
      <hasHelp>false</hasHelp>
      <hasAbout>false</hasAbout>
      <acceptContentType>text/html</acceptContentType>
      <defaultLocale>en.US</defaultLocale>
      <renderer class="oracle.portal.provider.v2.render.RenderManager">
         <autoRedirect>true</autoRedirect>
         <contentType>text/html</contentType>
         <showPage>/htdocs/webservices/zipcode_form.jsp</showPage>
      </renderer>
   </portlet>

   ...

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
		<id>5</id>
		<name>LocationInformation</name>
		<title>Location Web Service Portlet</title>
		<shortTitle>Location Information</shortTitle>
		<description>Web Service demonstration portlet.</description>
		<timeout>100</timeout>
		<timeoutMessage>Location Information portlet timed out</timeoutMessage>
		<acceptContentType>text/html</acceptContentType> 
		<inputParameter class="oracle.portal.provider.v2.DefaultParameterDefinition">
			 <name>p_zip</name>
			 <displayName>Please enter zipcode</displayName>
			 <description>Please enter zipcode</description>
		</inputParameter>
		<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>false</logging>
			<endpointURL>http://www.winisp.net/cheeso/zips/ZipService.asmx</endpointURL>
			<soapAction>http://dinoch.dyndns.org/webservices/ZipTo1CityAndState</soapAction>
			<literal class="oracle.portal.provider.v2.webservice.LiteralXML"
			  handler="oracle.portal.provider.v2.webservice.LiteralXML$Handler">
			  <element name="ZipTo1CityAndState">
				<attribute name="xmlns">http://dinoch.dyndns.org/webservices/</attribute>
				<element name="zip"
				  bind="urlParams/p_zip"
				  default="94065"
				  prompt="Please enter a zipcode"/>
			  </element>
			</literal>
			<!-- This service produces HTML as output, so don't escape tag information -->
			<escapeOutput>false</escapeOutput>
		   <responseXSL>CityState.xsl</responseXSL>
		  </showPage>
		</renderer>
	  </portlet>

   ...

</provider>

Create Messaging Sample page

Create another page or to the same page, add the SMS Messaging Web Service portlet and you can send messages to anyone. You first need to enter the Edit Defaults mode and provide an OTN username and password to configure this sample. You can even send a Voice message by entering the To address as: "Voice:1-650-555-1234" (use your own phone number to test).

Please refer to OracleAS Portal online documentation for more information about using Web Services Renderers, read the articles Understanding Web Services for Portlets and How to Build Portlets using Web Services.