# Oracle Portal Development Kit
URL-based portlets Release Notes - October 2002

System Requirements

Samples

What's New

Installation

## SYSTEM REQUIREMENTS

The following are the recommended and minimum requirements to use and install the PDK URL Services version 3.0.9.0.7.

Portal Version | 3.0.6.6.5, 3.0.7.6.2, 3.0.8.9.8 3.0.9.8.0
Browsers | Netscape 4.0.8 and above, Microsoft Internet Explorer 4.0.1 with Service Pack 1 and above.
JPDK | 3.0.9.0.6 and above

Know Issues :

1. You may encounter JavaScript errors when using a browser older than what is listed above.
2. Currently, the HtmlFilter cannot convert relative URLs of the form "../images/logo.gif" to absolute URLs.

## SAMPLES

The URL Services samples illustrate how to develop portlets using PDK-Java and URL Services. The following is a list of sample portlets included in this version of the URL Services.

- Google.com Portlet - Illustrates PDK-URL Services and Google.com.

- XML Filter Portlet - Illustrates how to use the XML Filter with URL Services to render specific content within a URL. This portlet uses the Massachusetts Institute of Technology (MIT) website as an example.

- ASP Portlet - Illustrates how to create ASP portlets using Stardeveloper.com.

- Asahi.com Portlet, Excite Japan Portlet, and Zaobao.com Portlet - Illustrate NLS capability.

- MetaLink Forum Search Result Portlet - Illustrates how to use PDK-URL Services to render content from a basic authentication URL.

- Yahoo! Finance Portlet and Yahoo! Mail Portlet - Illustrates how to use PDK-URL Services to render content from a URL that is protected by a cookie based login.

- Yahoo! Mobile Portlet - Illustrates inline rendering of portlet links.

- Yahoo! Maps Portlet, Dictionary.com Portlet, and Search.com Portlet - Illustrate parameter passing.

## WHAT'S NEW

### Changes in 3.0.9.0.8 release

Bugs fixed in this release

1. 2626233 - CANNOT RENDER SITES USING SSL USING URLSERVICES

> Description :

> > This bug fix basically overcomes the limitation of `certification chaining`. Portlets can establish relevant trust points with the HTTPS application and thus read the content. Trusted Certificate Authority (CA) details are obtained from the wallet created using Oracle Wallet Manager. These certificates are parsed from wallet and are used in establishing trust points.

### Changes in 3.0.9.0.7 release

Bugs fixed in this release

1. 2377874 - URL SERVICES EXTERNAL APP AUTHENTICATION

Description :

> URL-based portlets were not redirecting the user to the external application login screen if the mapped credentials for an external application user are wrong and the user needs to supply new credentials. In such cases, a blank portlets is shown and the page source needs to be viewed to learn that the user is not authorized. Ideally, the login link should be displayed allowing the users to re-submit their credentials.

> Now, if authentication fails, we throw an Authentication Exception from initSession which will cause JPDK to return a SOAP Fault to the Portal that will in turn cause a portlet to be displayed with a link that allows the user to correct their External Application credentials. The next time the page is requested, initSession will be called again. This cycle will repeat until the user enters the correct credentials & initSession succeeds.

2. 2357777 - URL BASED EXTERNAL APPLICATION PROVIDER MISHANDLES COOKIES

   Description :

   > URL-based portlets used to handle cookies in a way which does not suit multi-threaded environment. The extracted cookies used to be stored in a global location which was accessible to all users at all times.

   > The fix involves storing the cookies and other user information under an unique context based on user session. This information will be stored once the session is started and will be available only to the users under the specified context. Once the session is lost, user specific information will be removed from the storage.

3. 2353197 - URL SERVICES PORTLET PERSONALIZATION INCORRECTLY DEFAULTS PORTLET TITLE

   Description :

> > When portlet personalization is enabled, URL-based portlets used to default the portlet title to "PDK-URL Services Portlet" instead of taking the default title from provider.xml. Now the portlet title defined through provider.xml is made as default.

### Changes since 3.0.9.0.6 release

1. BASIC AUTHENTICATION EXTRA FIELDS

This feature allows PDK-URL Services portlets that go against basic authentication external applications to receive the additional field values stored in the SSO Server.

The new MetaLink Forum Search Result Portlet illustrates this feature by allowing the user to configure the external application to receive additional fields (to indicate the query string, etc.). The portlet is now able to pick up the names and values for these additional fields.

To implement this feature, make the following changes to existing tag values:

1. <provider> tag - <provider class="oracle.portal.provider.v1.http.BasicURLProvider">
2. <showPage> tag - <showPage class="oracle.portal.provider.v1.http.BasicURLRenderer">

2. INVALIDATION BASED CACHING

This feature allows portlets to be cached via invalidation based caching. There are two conditions under which a cache will be invalidated:

1. The user has customized the portlet and saved data.
2. The user has clicked on a link that uses inline rendering.

New tag introduced:

<useInvalidationCache> - This is a sub-tag of the <showPage> tag.

### Changes since 0.9.5 release

1. SELECTIVE INLINE RENDERING

This feature allows portlet links to be rendered inline only if they meet specified criterion, which can be defined through provider.xml.

New tags introduced:

a) hrefFieldName - optional tag. Can be used to specify href attribute name to be looked for disabling inline rendering. Default value is "id".
b) disableInlineRenderingID - value for the above attribute.
All hrefs containing attribute name specified by tag (a) and value given by tag (b), will not be rendered inline.

Example :

hrefFieldName = ID & disableInlineRenderingID = type

<filter class=" oracle.portal.provider.v1.http.SelectiveRenderingFilter>
<disableInlineRenderingID>1</disableInlineRenderingID>
<hrefFieldName>type</hrefFieldName>
</filter>

HRefs of type <a href="http://www.yahoo.com" type="1">Link to Yahoo</a> will not be rendered inline.
2. In previous releases, URLServices used UTF-8 as the default character set for the portlets. But if the page we are trying to portletize uses some other encoding which is not compatible with UTF-8, we used to land up in exceptions. Now the default character set is made as ISO-8859-1 which is more generic.

### Changes since 0.9.4 release

1. INLINE RENDERING
All portlet links can be rendered inside portlet container. If the links are pointing to different domain that that of original page, base href is extracted automatically from the pointed link's contents.
This can be specified through provider.xml with the help of a new tag called inlineRendering. Its is an optional tag with possible values as true/false.
Example:

> <filter class="oracle.portal.provider.v1.http.HtmlFilter">
> <inlineRendering>false</inlineRendering>
> </filter>

2. PORTLET PAGE PARAMETERS WITH CUSTOMIZATION OPTION
This release of PDK-URL Services contains most desired feature - Passing parameters to a portlet. There are different options available for this purpose.

- Parameters can be passed through either GET or POST method. Corresponding User Interface to pass these parameters is provided in the portlet. Alternatively the user can directly append parameters to the URL and pass them.

- User can control the passing of parameters to either a single portlet or all
  portlets in the page. For this purpose we support two types of parameters :
  - Qualified
    Parameters wil be passed only to the intiating portlet i.e., portlet which contains them.
  - Unqualified
    All portlet will be affected by the parameters sent by any portlet.

  This can be controlled through portlet customization screen. Please refer to passing parameters for more details.

- Parameters can be mandatory. If any of the mandatory parameter value is missing, an error message is shown to the user to provide the same. This is controlled through isMandatory tag in provider.xml. Please refer to new tag information to know more about inputParameter tag.
  Example :

> > <inputParameter class="oracle.portal.provider.v1.URLPortletParameter">

> > > <name>term</name>
> > > <isMandatory>false</isMandatory>
> > > <displayName>Search Oreilly for </displayName>
> > > <value>JAVA</value>

> > </inputParameter>

- Default values can be specified for parameters in provider.xml. If the portlet doesn't receive any parameters through HTTP request, this value will be used instead. A parameter can also contains displayName apart from name field. Display name is the one shown to the user while name will be used while submitting the FORM.

- Order of precedence for parameters is as follows :
  - Portlet page parameters received through HTTP request.
  - Default values specified in provider.xml
  - Customized parameter values.

3. HIDING BASIC AUTHENTICATION USER INFORMATION

If inlineRendering option is enabled through provider.xml, then user information is not shown in the href pointed to by the link. But otherwise, it will still be exposed.

4. AUTOMATIC DETECTION OF RENDERING INFORMATION

- BaseHRef and secBaseHRef are now dynamically determined. User need not worry about providing this information in provider.xml, unless he/she wished to do so.
- filterType is now not needed. Type of filter is now know through the attribute value of filter tag. But this tag will still be supported in the current version for backward compatibility.

5. LIST OF NEW (MODIFIED) TAGS

a) inputParameter : Optional tag under provider. Sets the portlet parameters. List of available tags under it :

name | Required tag. Indicates the name of this parameter.
displayName | Optional tag. It is the display name of parameter to be shown in portlet. If not specified, name of this parameter will be displayed.
isMandatory | Indicates if this tag is a mandatory one. value : Sets the pre-populated value for this parameter. If no value is passed HTTP request header, this value will be used by default.
value | Sets the pre-populated value for this parameter. If no value is passed HTTP request header, this value will be used by default.

Example :

<inputParameter class="oracle.portal.provider.v1.URLPortletParameter">
<name>term</name>
<isMandatory>false</isMandatory>
<displayName>Search Oreilly for </displayName>
<value>JAVA</value>
</inputParameter>
b) inlineRendering : Optional tag which indicates if the portlet links have to be rendered inside Potlet container itself.
Example :
<filter class="oracle.portal.provider.v1.http.HtmlFilter">
<headerTrimTag>&lt;body></headerTrimTag>
<footerTrimTag>&lt;/body></footerTrimTag>
<inlineRendering>true</inlineRendering>
</filter>
c) <filterType>, <baseHRef> and <secBaseHRef> tags have been made optional, though they are supported for backward compatibility.

- filterType will be determined from the <filter> tag's class attribute.
- baseHRef & secBaseHRef will be extracted from URL Content. If the user specifies values for these tags in provider.xml these will be used instead.

d) The following <authentication> sub-tags have been obsoleted:

- <loginURL>
- <requestType>
- <userFieldName>
- <userPwdName>
- <fieldName>

The only valid sub-tags under the <authentication> tag should be <authType> and <errorPageMessages>.

e) <headerTrimTag> has changed its behavior from prior releases. This tag now removes all HTML before BUT NOT INCLUDING the string specified by the tag. Prior releases removed HTML including the string specified by the tag. So now, the proper way to trim HTML "head" info from the portlet would be <headerTrimTag>&lt;body</headerTrimTag>, NOT <headerTrimTag>/head></headerTrimTag>.

6. Bugs fixed in this release

- 1973061 : NLS:URLSERVICES:JAPANESE SITES ARE NOT SHOWN PROPERLY
- 1866079 : URLSERVICES:NLS:JAPANESE/CHINESE PORTLETS ARE NOT SHOWN PROPERLY

> Appropriate encoding was not applied to the URL Content before rendering in the portlet because of which browser's encoding style had to be set explicitly. Moreover, any portal page was able to display portlet having similar character-encodings. This limitation has also been removed in this release. Now a single page can display portlet of multiple and different character sets. For example : Both Japanese and Chinese portlets can be displayed in a single page.

> This comes with an additional requirement in the portal side. Portal should be able to handle Multi Byte Character Set which is compatible with the character set of the portlet we are trying to view. In most of the cases UTF-8 will be sufficient.

> Additionally, in order to use PDK-URL Services to render an NLS portlet, you must specify in provider.xml the character set being used to encode the portlet content. You would use the <charSet> tag (a sub-tag of <showPage> tag) to do this. For example, the Zaobao.com portlet requires a <charSet> value of GB2312.

### Changes since 0.9.3 release

1. BASIC AUTHENTICATION

   In addition to Form based authentication, PDK-URL Services has included BASIC mode of authentication also in this release. This feature works almost similar to that of form based authentication. User information is read from portal's external application. Basic authentication needs only two parameters i.e, user name and password. So, we do not need to supply additional field information through provider.xml. The change in authentication tag for this purpose is given below

   <authentication class="oracle.portal.provider.v1.http.Authentication">

   <authType>basic</authType>

   <errorPageMessages>User is not authorized to view the content.</errorPageMessages>

   </authentication>

###

### Changes since 0.9.2 release

1. New Stylesheet to upgrade Provider Definition files (provider.xml).

   1. You will find three files in the urlservices/providers directory: upgrade.bat (NT), upgrade.sh (UNIX), and upgrade.xsl. These files are used to upgrade previous version of provider definition files to the latest version used by PDK-URL Services.

   2. Please edit JAVA_HOME and ORACLE_XML in upgrade.bat / upgrade.sh to correspond to your JDK and oracle XML parser's CLASSPATH (location).

   3. Run the upgrade.bat / upgrade.sh in the same directory as your provider.xml to complete the upgrade.

2. List of New tags
   1. <usePortalStyle> - An additional tag called <usePortalStyle> at provider level. It's a simple tag defined as follows:

   Example: <usePortalStyle>true/false</usePortalStyle>

   > 1. Removes the styles used by the external site

   > 2. Adds portal style to the following elements

   >    1. Converts all hrefs to use portal's href font.

   >    2. TABLE's first row will use standard portlet header color if it already had either bgcolor or class attribute.

   >    3. TABLE's background will use portal's tableBackground style, if the table already had bgcolor or class attribute.

3. List of Changed Tags

   1. provider tag's class attribute has been changed from DefaultURLProvider to URLProvider.

   2. portlet tag's class attribute has been changed from PortletNodeHandler to URLPortlet.

   3. showPage, editPage etc., tags's class attribute has been changed from URLPageRenderer to URLRenderer.

   4. authentication tag's class attribute has been changed from CommonNodeHandler to Authentication.

   5. proxyInfo tag's class attribute has been changed from CommonNodeHandler to ProxyInformation.

   6. httpsProxyInfo tag's class attribute has been changed from CommonNodeHandler to ProxyInformation.
   7. subscriberDetails tag's class attribute has been changed from CommonNodeHandler to SubscriberDetails.

### Changes since 0.9.1 release

1. National Language Support is incorporated. Appropriate font and character-sets are set in the browser, before viewing the portlet contents.

   1. No special setup is required for NLS portlets, but the following things should be noted.

      1. If the browser used in I.E. (5.0 or higher), the required fonts are downloaded automatically.

      2. If browser is not I.E (5.0 or higher), then you must download the appropriate fonts to render multi-byte character sets.
         1. A simple way of downloading a font is to use IE for viewing the URL. If the font is not present, it is downloaded automatically.
            1. Set the browser encoding to the respective local language encoding.

               1. In I.E. encoding can be set using View -> Encoding -> <Encoding-Type>

               2. In Netscape it can be set using View -> Character Set -> <Character-set-Type>

2. Subscriber Model is now supported. Review PDK-URL Services Subscriber ReadMe for more information.

3. List of New Tags
   1. <subscriberDetails> - An additional tag called <subscriberDetails> at provider level. It's a complex tag with two child tags.

      1. <subscriberInfo>true</subscriberInfo> - If <subscriberInfo> set true, then subscriber keys are stored persistent.

      2. <subscriberKeys>YAHOO123,ORACLE123,MIT123</subscriberKeys> - The second child introduced is <subscriberKeys>. It contains subscriber Keys separated by commas and it check for Subscriber key coming from portal. if one of the key listed in above tag matches with subscriber key the we log the subscriber details.

      3. Example of Tag:

      > <subscriberDetails class="oracle.portal.provider.v1.http.SubscriberDetails">

      > <subscriberInfo>true</subscriberInfo>

      > <subscriberKeys>YAHOO123,ORACLE123,MIT123</subscriberKeys>

      > </subscriberDetails>

### Changes since 0.9.0 release

1. Based on debuglevel parameter different types of contents are written to log file.

   Example: provider_root=D:\urlservices,sessiontimeout=1800000,debuglevel=2

   > 0 | There should not be any log messages.
   > 1 | Only basic level logging such as method entry & exit statements should appear.
   > 2 | All the log messages described in debuglevel=1 section and less. Method control flow statements.
   > 3 | HTML Contents Logging: All the log messages described in debuglevel=2 section and less. Html contents from the urls specified in provider.xml.
   > 4 | HTML Contents Logging: All the log messages described in debuglevel=3 section and less, but providing more detail.
   > 5 | XHTML Contents Logging : All the log messages described in debuglevel=2 section + XHTML contents from the urls specified in provider.xml. Handy in case of using XmlFilter.

2. List of Changed Tags

   1. <accessControl> - This tag has been moved back to <portlet> level from <xxxPage> level. Please refer to the sample provider.xml in the builds directory for reference. Previous versions of provider.xml will not work with the June URLServices until and unless this tag is moved back to <portlet> level.

3. Bugs fixed in this release
   1. 1778756 - URL Services Yahoo: Error Message is shown in the portlet.

### Changes since 0.8 release

1. SSL support is enabled. Please refer to the SSL Readme for more information.

2. Incorporated support for the sites with authenticated hyperlinks. No special setup is necessary for the same.

3. List of New Tags
   1. <errorPageMessages> - This is a child tag to <authentication> tag. Purpose is to check if the login to the external application is successful. It will take strings seperated by commas and if any of these messages are found in the url content, login is supposed to be unsuccessful.

      For example :

      <errorPageMessages>login unsuccessful, verify you login information and try again.</errorPageMessages>

      If the messages "login unsuccessful" or "verify you login information and try again." are found in the urlcontent, an error message is displayed with related information.

4. List of Changed Tags

   1. authentication (under <provider> tag) - class attribute has been changed to "oracle.portal.provider.v1.http.CommonNodeHandler" from "oracle.portal.provider.v1.http.AuthenticationNodeHandler"

   2. proxyInfo (under <provider> tag) - class attribute has been changed to "oracle.portal.provider.v1.http.CommonNodeHandler" from "oracle.portal.provider.v1.http.ProxyInfoNodeHandler"

      1. <proxyHost> tag is changed to <httpProxyHost>

      2. <proxyPort> tag is changed to <httpProxyPort>

   3. httpsProxyInfo (under <provider> tag) - class attribute has been changed to "oracle.portal.provider.v1.http.CommonNodeHandler" from "oracle.portal.provider.v1.http.HttpsProxyInfoNodeHandler"

      1. <proxyHost> tag is changed to <httpsProxyHost>

      2. <proxyPort> tag is changed to <httpsProxyPort>

   4. redirectUrl (under <filter> tag) - Has been changed to redirectUrlFieldName

5. Bugs fixed in this release

   1. 1719248 - PROXY BEING SET WITHIN THE CODE.

   2. 1711629 - DUPLICATE FILES IN URLSERVICES.JAR

## Installation

- Follow the instructions within the Installing URL Services and Samples article.

Revision History:

- November 28, 2001.
- October 03, 2001.
- June 25, 2001.
- September 15, 2002.
- October 29, 2002.