Understanding the provider.xml for PDK-URL Services v2

Oracle9iAS Portal Developer Kit
Understanding the provider.xml for URL-Based Portlets

PDK Release 2 (9.0.2 and later) - URL-Based

A web provider is one that is written as a web application. It is installed and hosted in a web server and is remote from Oracle9iAS Portal. Previously, a web provider required development in Java, Java Servlets, and Java Server Pages. Now, with the addition of the URL-based provider runtime, a web provider can manage a set of portlets in any language.

With URL-based portlets, the PDK has extended its framework to create portlets in any programming language. The only requirement is that your application is accessible through a URL. To do this, the PDK offers a provider runtime called URLProviderInstance that implements the functions of a provider. The URLProviderInstance extends DefaultProviderInstance. Like DefaultProviderInstance, the URLProviderInstance's main function is to own and manage a set of portlets. The URLProviderInstance also uses provider.xml as its initialization file.

The provider.xml file lists and defines a set of portlets. The portlets are normally Java, Java Servlets, or JSPs. The provider.xml has been extended to list and define portlets of any language. This article describes the configuration of provider.xml as it pertains to the URL-based portlets.

CONFIGURATION

The provider.xml file stores information that is used by the URLProvider. URLProvider in turn is divided into two classes -

URLProviderDefinition - For holding provider meta data (information about portlets it own)
URLProviderInstance - For managing portlets registered with it.

The provider.xml file stores information by hierarchy. Its hierarchical nature starts with "Provider". The file is organized to simplify the process required by the URLProviderInstance to parse the file. The provider.xml file is also organized to increase readability.

This section describes those tags within provider.xml that have been added and/or modified for URL-based portlets. When creating your own provider.xml, you must follow the hierarchy and syntax required for the URLProviderInstance to properly parse the file.

Provider tag

The provider tag is the first tag in the provider.xml file. Since the class attribute defaults to DefaultProviderDefinition, you need to specify oracle.portal.provider.v2.http.URLProviderDefinition as the class that extends DefaultProviderDefinition. The provider tag currently has two attributes which are supported by the URLProviderDefinition. The provider tag has also been modified to accept the following tags:

authentication is an optional attribute and holds information about type of authentication. This attribute is used with portlets requiring external authentication and works directly with Oracle9iAS Portal External Applications. This attribute has the following child tags.

authType is a required tag under authentication and specifies what kind of authentication is supported. This tag has three possible values:
- none - Indicates no authentication.
- ExternalApp - Indicates that the mode of authentication is FORM based. All user details needed for authentication are fetched from External Application defined through Portal.
- Basic - For BASIC mode of authentication. User information is fetched from Portal's External Application.
errorPageMessages is an optional tag under authentication. Its purpose is to check if the login to the external application is successful. It takes strings separated by commas and if any of these messages are found in the URL content, login is supposed to be unsuccessful. You specify the error message to display within this tag.

<provider class="oracle.portal.provider.v2.http.URLProviderDefinition">
    <providerInstanceClass>oracle.portal.provider.v2.http.URLProviderInstance</providerInstanceClass>
    <session>true</session>
    <authentication class="oracle.portal.provider.v2.security.Authentication">
        <authType>externalApp</authType>
        <userFieldName>login</userFieldName>
        <userPwdName>login</userPwdName>
    </authentication>
</provider>

proxyInfo is an optional tag and holds proxy server information. This tag contains one attribute and two child tags:
- class is an optional attribute and specifies the name of the class to handle the proxy information.
- httpProxyHost is an optional tag and specifies the name of the proxy server.
- httpProxyPort is an optional tag and specifies the port for the proxy server.
<proxyInfo class="oracle.portal.provider.v2.ProxyInformation"> <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost> <httpProxyPort>80</httpProxyPort> </proxyInfo>
httpsProxyInfo is an optional tag and holds proxy server information. This tag contains two child tags:
- class is an optional attribute and specifies the name of the class to handle the proxy information.
- httpProxyHost is an optional tag and specifies the name of the proxy server.
- httpProxyPort is an optional tag and specifies the port for the proxy server.
<httpsProxyInfo class="oracle.portal.provider.v2.ProxyInformation"> <proxyHost>proxy.oracle.com</proxyHost> <proxyPort>80</proxyPort> </httpsProxyInfo>

subscriberDetails is an optional tag under the provider tag, it is complex and has the following child tag.

subscriberInfo is a required tag and if set to true, the subscriber keys are stored persistently.
subscriberKeys is a required tag. It contains subscriber keys separated by commas and it checks for a subscriber key coming from Portal. If one of the keys listed in the above tag matches with the subscriber key, the subscriber details are logged.

<subscriberDetails class="oracle.portal.provider.v2.SubscriberDetails">
    <subscriberInfo>true</subscriberInfo>
    <subscriberKeys>YAHOO123,ORACLE123,MIT123</subscriberKeys>
</subscriberDetails>

Portlet tag

The provider has a tag called portlet. The portlet has an attribute named class through which portlet's runtime class can be specified. It also contains the following tags.

registrationPortlet is an optional tag that indicates whether this portlet is a registration portlet for the provider or not. This is a boolean value and the default for this tag is false.
accessControl is an optional tag and indicates whether this portlet is publicly available or available only to registered users. There are two possible values:
- public
- registered

<registrationPortlet>false</registrationPortlet>
<accessControl>public</accessControl>

inputParameter is an optional tag for publishing public portlet parameters. There are four sub-tags to define parameter properties :
- name is a mandatory tag used which indicates the parameter name to be used in FORM submission.
- displayName is an optional tag. In many cases name of the parameter will not be very meaningful. Display name fills this gap. The display name is shown to the user in the rendered portlet while name is still used while submitting the FORM. If no value is specified, name of the parameter is displayed.
- value is an optional tag. Pre-populated value for this parameter. If the parameter value is not specified by the user, the value declared in this tag is used by default.
- isMandatory is an optional tag with a default value of false. It indicates whether this parameter must be provided in order to display the portlet.

renderer is a required tag that has been modified to accept additional tags. Below are a list of additional tags added to renderer for URL rendering.

showPage is a required tag and specifies the page that renders the portlet. It has one attribute and 5 tags.
- class is an optional attribute and names the Java class that implements oracle.portal.provider.v2.render.PortletRenderer. The class to be specified for PDK-URL Services is oracle.portal.provider.v2.render.http.URLRenderer.
- accessControl is an optional tag and indicates whether this portlet is publicly available or available only to registered users. There are two possible values:
  - public
  - registered
- pageUrl is a required tag that specifies the URL to be used to display the portlet content. This can be any URL that can be accessed from a browser. The URL must contain the http prefix. Also, if the URL contains "&", it must be replaced by the escape characters "&". This prevents provider.xml from becoming ill formed.
- filter is an optional tag which specifies the filter to be applied on rendered contents. It has one attribute and multiple tags. The tags used depend on the filter attribute specified.
  - class is an optional attribute and names the Java class that implements oracle.portal.provider.v2.render.ContentFilter. There are two possible values:
    - oracle.portal.provider.v2.render.HtmlFilter has six tags
      - headerTrimTag is an optional tag that specifies the string to be used to trim header contents. All HTML content before this tag will be trimmed. For example <BODY will remove all the content before <BODY> tag excluding the tag itself. When this is specified in proivder.xml "<" has to be substituted with its escaped representation, "<".
      - footerTrimTag is an optional tag that specifies the string to be used to trim footer contents. All HTML content after this tag will be trimmed. For example /BODY> will remove all the content before </BODY> tag excluding the tag itself.
      - convertTarget is an optional tag which specifies whether hyperlinks on the page need to be modified so they open a new browser window rather than overwriting existing portal page. This is a Boolean value.
      - useAuthLinks is an optional tag that indicates whether the hyperlinks within the portlet content need authenticated access. This is a Boolean value and the default for this tag is false.
      - redirectUrlFieldName is an optional tag and indicates the parameter name recognized by the External Application's Login URL as a URL that should be redirected to after a successful authentication. This parameter is used only if the portlet indicates it has authenticated hyperlinks. Possible values are - actual redirectUrlFieldName tag.
      - inlineRendering is an optional tag to indicate whether portlet links have to be renderered inside portlet container itself. Possible values are true/false and default is false.

<renderer class="oracle.portal.provider.v2.render.RenderManager">
<showPage class="oracle.portal.provider.v2.render.http.URLRenderer ">
<pageUrl>http://www.microsoft.com/windows2000/upgrade/default.asp</pageUrl>
        <filter class="oracle.portal.provider.v2.render.HtmlFilter">
             <headerTrimTag>&lt;BODY</headerTrimTag>
             <footerTrimTag>/BODY></footerTrimTag>
            <convertTarget>true</convertTarget>
            <useAuthLinks>false< useAuthLinks>
            <redirectUrlFieldName>inspRedirectUrl</redirectUrlFieldName>

            <inlineRendering>true</inlineRendering>
        </filter>
</showPage>
</renderer>

oracle.portal.provider.v2.render.XmlFilter has three tags:

styleSheet is an optional tag that indicates the name of the stylesheet to be applied for filtering. The stylesheet name is specified in a URL format. This can point to a stylesheet resident of the file system or on the internet. defaultXhtml.xsl stylesheet is provided which can be modified to achieve desired results.

useAuthLinks is an optional tag that indicates whether the hyperlinks within the portlet content need authenticated access. This is a Boolean value and the default is false.

urlContentType is an optional tag that specifies the mime type of the content that the URL retunrs. Possible values are "text/html" and "text/xml". The default is "text/html".

<renderer class="oracle.portal.provider.v2.render.RenderManager">
     <showPage class="oracle.portal.provider.v2.render.http.URLRenderer">   
     <accessControl>registered</accessControl>
     <pageUrl>http://support.sitescape.com/forum/support/dispatch.cgi</pageUrl>
    <filterType>text/xml</filterType>
    <filter class="oracle.portal.provider.v2.render.XmlFilter">
        <useAuthLinks>false</useAuthLinks>
        <stylesheet>D:/ sitescape/default_sitescape.xsl</stylesheet>
        <urlContentType>text/html</urlContentType>
    </filter>
    </showPage>
 </renderer>
editPage is a optional tag and specifies the page that renders the customize screen of the portlet. It can have all the tags mentioned above for showPage.

aboutPage is an optional tag and specifies the page that renders information about the portlet. It can have all the tags mentioned above for showPage.

helpPage is an optional tag and specifies the page that renders helpful information about the portlet. It can have all the tags mentioned above for showPage.

editdefaultsPage is an optional tag and specifies the page used by an administrator to customize the default settings for the portlet. It can have all the tags mentioned above for showPage.

previewPage is an optional tag and specifies the preview page of the portlet. It can have all the tags mentioned above for showPage.

detailsPage is an optional tag and specifies the page used to display the portlet in full browser window. It can have all the tags mentioned above for showPage.

portletSecurityManager has been modified to accept one new tag.
- authrizType is a required tag that indicates the type of Authorization that is allowed. It has two possible values:
  - registered - the security manager only renders the list of portlets if the user is registered, otherwise a registration portlet is displayed.
  - None - no registration needs to be applied.
<securityManager class="oracle.portal.provider.v2.security.URLSecurityManager"> <authorizType>public</authorizType> </securityManager>

For more information on the PDK runtime for URL-based portlets, refer to the following article:

Understanding the PDK Runtime for URL-Based Portlets

Revision History:

January 2002.