Understanding provider.xml for URL Services

Oracle9iAS Portal Developer Kit
Understanding the provider.xml for URL Services

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 consisted only of the JPDK which meant development in Java, Java Servlets, and Java Server Pages. Now, with the addition of the PDK URL Services, a Web Provider manages a set of portlets in any language.

The PDK URL Services has extended the existing JPDK Framework to create portlets regardless of the programming language. The only requirement is that your application is accessible through a URL. To do this, the PDK URL Services offers a Provider Runtime called URLProvider that implements the functions of a provider. The URLProvider extends DefaultProvider. Like DefaultProvider, the URLProvider's main function is to own and manage a set of portlets. The URLProvider 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. The article describes the configuration of the provider.xml as it pertains to the PDK URL Services. For information about the default configuration and usage of the provider.xml file, please review the Provider Definition XML Tag Reference.

CONFIGURATION

The provider.xml file stores information that is used by the URLProvider. 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 URLProvider 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 Services. When creating your own provider.xml, you must follow the hierarchy and syntax required for the URLProvider 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 DefaultProvider, you will need to specify oracle.portal.provider.v1.http.URLProvider as the class that implements oracle.portal.provider.v1.Provider. The provider tag currently has two attributes which are supported by the URLProvider. 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 Oracle 9iAS 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 two possible values:
- none - Indicates no authentication.
- ExternalApp - Indicates authentication is done by retrieving the authentication URL, Login userid, Login password, authentication type and other Login parameters from the Login Server.
- Basic - Indicates authentication type as BASIC. User information is again 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 will take 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.

<authType>ExternalApp</authType>

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

</authentication>

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.

<proxyHost>proxy.oracle.com</proxyHost>

</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.v1.http.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 persistent.
subscriberKeys is a required tag. 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.

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

<subscriberInfo>true</subscriberInfo>

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

</subscriberDetails>

Portlet tag

The provider has a tag called portlet. The portlet tag has three attributes. 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.
inputParameter is an optional tag which can be used to set the portlet parameters.

The following sub-tags are available under <inputParameter>: -

name: Required tag. Indicates the name of this parameter.

displayName: Optional tag. It is the display name of the parameter to be shown in the portlet. If not specified, the <name> of this parameter will be displayed.

isMandatory: Optional tag. Indicates if this parameter is a mandatory one. If a mandatory parameter value is missing, an error message is shown to the user to provide the value.

value: Optional tag. Sets the pre-populated value for this parameter. If no value is passed by the user in the portlet parameter submission form, the default value specified here is used.

Example of usage:
<inputParameter class="oracle.portal.provider.v1.URLPortletParameter"> 

    <name>term</name>

    <isMandatory>false</isMandatory>

    <displayName>Search Oreilly for </displayName> 

    <value>JAVA</value> 

</inputParameter>

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>

<redirectUrl>inspRedirectUrl</redirectUrl>

<accessControl>public</accessControl>

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.v1.http.PortletRenderer. The class to be specified for URL Services is oracle.portal.provider.v1.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 for getting the contents of portlet from. 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.v1.ContentFilter. There are two possible values:
    - oracle.portal.provider.v1.http.HtmlFilter has six tags
      - headerTrimTag is an optional tag that specifies the string to be searched in HTML contents and trim all the header contents before the occurrence of this string. This tag is used for removing <HEAD><BODY> tags and also for removing any unwanted banners in the header of the page that is retrieved. This tag takes values without "<" or ">" signs to eliminate the need to use escape characters. So if you need to trim values of header before </HEAD>, the value to be specified is /HEAD.
      - footerTrimTag is an optional tag that specifies the string to be searched in HTML contents and trim all the footer contents after the occurrence of this string. This tag is used for removing </BODY></HTML> tags. The same rules apply as the headerTrimTag.
      - baseHRef is an optional tag which specifies the base href for the html page. URLServices dynamically determines the base href from the URL Content. If the user explicitly want to set base href it can be used.
      - secBaseHRef is an optional tag which specifies a secondary base href for the html page. URLServices dynamically determines the base href from the URL Content. If the user explicitly want to set base href it can be used.
      - 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.
      - inlineRendering is an optional tag that indicates if the portlet links have to be rendered inside the portlet container itself. Possible values are true/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

<renderer class="oracle.portal.provider.v1.RenderManager">

<showPage class="oracle.portal.provider.v1.http.URLRenderer ">

<pageUrl>http://www.microsoft.com/windows2000/upgrade/default.asp</pageUrl>

         <filterType>text/html</filterType>

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

             <headerTrimTag>/HEAD</headerTrimTag>

             <footerTrimTag>/BODY</footerTrimTag>

             <baseHRef>http://www.microsoft.com/</baseHRef>

<secBaseHRef>http://www.microsoft.com/windows2000/upgrade/</secBaseHRef>

            <convertTarget>true</convertTarget>

            <useAuthLinks>false< useAuthLinks>

            <redirectUrlFieldName>inspRedirectUrl</redirectUrlFieldName>

	<inlineRendering>true</inlineRendering>

        </filter>

</showPage>

</renderer>

oracle.portal.provider.v1.http.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 whether the mime type of the content that the URL returns. Possible values are "text/html" and "text/xml". The default is "text/html".
<renderer class="oracle.portal.provider.v1.RenderManager">
 <showPage class="oracle.portal.provider.v1.http.URLRenderer">   
 <accessControl>registered</accessControl>
 <pageUrl>http://support.sitescape.com/forum/support/dispatch.cgi</pageUrl>
       <filterType>text/xml</filterType>
        <filter class="oracle.portal.provider.v1.http.XmlFilter">
               <useAuthLinks>false</useAuthLinks>
               <stylesheet>D:/sitescape/default_sitescape.xsl</stylesheet>
               <urlContentType>text/html</urlContentType>
         </filter>
 </showPage>
 </renderer>
oracle.portal.provider.v1.http.SelectiveRenderingFilter extends HtmlFilter. All child tags of HtmlFilter can be used in addition to the following new tags :

hrefFieldName - optional tag. Can be used to specify href attribute name to be looked for disabling inline rendering. Default value is "id".

disableInlineRenderingID - value for the above attribute.
<filter class=" oracle.portal.provider.v1.http.SelectiveRenderingFilter>

<disableInlineRenderingID>1</disableInlineRenderingID>

<hrefFieldName>type</hrefFieldName>

</filter>

Using the above filter, HRefs of type

<a href="http://www.yahoo.com" type="1">Link to Yahoo</a> will not be rendered inline.

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 only if the user is registered, otherwise a registration portlet will be displayed.
- None - no registration needs to be applied.

<authrizType>registered</authrizType>

Revision History:

October 03, 2001.
July 31, 2001.
January 28, 2001.