Oracle9iAS Portal Developer Kit
How to Build a URL-Based Portlet

Once you have successfully installed and deployed the PDK-URL Services samples, you will probably want to begin building URL-based portlets of your own. With PDK-URL Services, building URL-based portlets is simple process involving no coding at all.

This article shows you how to create a simple URL-based portlet and display it on an Oracle9iAS Portal page.

### ASSUMPTIONS

1. You have successfully installed the PDK-Java runtime and samples by following the Installing the PDK-Java Framework and Samples article.

2. You have successfully installed the PDK-URL Services runtime and samples by following the Installing the PDK-URL Services Samples article.

### CREATING AN XML PROVIDER DEFINITION

This section explains how to create an XML provider definition for your URL-based portlet provider. You can configure provider-specific information like portlet title and portlet description in the XML file. This XML file is also where you specify the URL that gets displayed in your portlet.

1. Using a text editor, create an XML file for your portlet provider. Use the pageURL tag to specify the URL that your portlet will display. You may use the sample below (you must change the httpProxyHost and httpProxyPort values to point to your own proxy server and port). Please refer to the article Understanding provider.xml for PDK-URL Services for an explanation of the required XML tags and their functions.

       <?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
       <?providerDefinition version="2.0"?>
       <provider class="oracle.portal.provider.v1.http.URLProvider">
          <session>true</session>
          <proxyInfo class="oracle.portal.provider.v1.http.ProxyInformation">
             <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost>
             <httpProxyPort>80</httpProxyPort>
          </proxyInfo>
          <portlet class="oracle.portal.provider.v1.http.URLPortlet">
             <id>1</id>
             <name>Google.com Portlet</name>
             <title>Google.com Portlet</title>
             <description>Display Google.com as a portlet.</description>
             <timeout>100</timeout>
             <timeoutMessage>Timed out waiting for Google.com Portlet.</timeoutMessage>
             <showEdit>false</showEdit>
             <showEditDefault>false</showEditDefault>
             <showPreview>false</showPreview>
             <showDetails>false</showDetails>
             <hasHelp>false</hasHelp>
             <hasAbout>false</hasAbout>
             <acceptContentType>text/html</acceptContentType>
             <registrationPortlet>false</registrationPortlet>
             <accessControl>public</accessControl>
             <renderer class="oracle.portal.provider.v1.RenderManager">
                <showPage class="oracle.portal.provider.v1.http.URLRenderer">
                   <contentType>text/html</contentType>
                   <pageExpires>60</pageExpires>
                   <pageUrl>http://www.google.com</pageUrl>
                   <filter class="oracle.portal.provider.v1.http.HtmlFilter">
                      <headerTrimTag>&lt;body</headerTrimTag>
                      <footerTrimTag>/body></footerTrimTag>
                   </filter>
                </showPage>
             </renderer>
             <securityManager class="oracle.portal.provider.v1.http.URLSecurityManager">
                <authorizType>public</authorizType>
             </securityManager>
          </portlet>
       </provider>

1. Save the file as "provider.xml", making sure not to overwrite one of the PDK-Java or PDK-URL Services sample files of the same name.

   Remember the name of the directory where the file is saved as you will need this later. For example: C:\MyProvider\provider.xml

### CONFIGURING YOUR WEBSERVER

These steps describe how to configure the Oracle HTTP Server only. If you are using a third party listener, please take the appropriate steps.

1. Stop the Oracle HTTP Server.

2. Open the configuration file zone.properties

3. Under the Servlet Aliases section, register an alias, myurlprovider, for a new instance of the Provider Adapter servlet. This servlet will use the XML provider definition you have just created.

   For example, add the line:

       servlet.myurlprovider.code=oracle.portal.provider.v1.http.HttpProvider

4. Under the Aliased Servlet Init Parameters section, add settings for the provider_root and sessiontimeout parameters, making sure that provider_root points to the directory where you saved your provider.xml file.

   For example, add the line:

       servlet.myurlprovider.initArgs=provider_root=C:\MyProvider,sessiontimeout=1800000,debuglevel=1

   Note: If the debuglevel parameter is set to 1, you will activate a special "test page" feature which allows you to ensure that your provider is configured properly before you try and register it with a portal.

5. Save zone.properties.

6. Start the Oracle HTTP Server.

7. Access your provider's test page by entering into a browser the URL for the aliased servlet you just set up. For example:

       http://host.domain:port/servlet/myurlprovider

   Note: You will use this URL later when you register the provider on a portal.

8. Review the test page which displays information about your provider. If the test page is not displayed, carefully review the previous configuration steps.

### REGISTERING THE PROVIDER

Once you have successfully tested your new provider you may register the provider with Oracle9iAS Portal.

1. Under the Administer tab (Oracle Portal Home Page), click Add a Portlet Provider.

2. Enter the following provider information:

   1. Name: MyURLProvider

   2. Display Name: My URL Provider for Google.com

   3. Timeout: 100

   4. Timeout Message: My URL-Based Portlet Timed Out

   5. Implementation Style: Web

   6. Provider Login Frequency: Never

   7. URL: http://myserver.mydomain.com:port/servlets/myurlprovider (replace this with your URL)

### ADDING THE URL-BASED PORTLET TO A PAGE

When you have registered your provider you can add your new URL-based portlet to a page. Please refer to the Oracle9iAS Portal online documentation for more information.

Now that you have successfully built your own URL-based portlet, please look for other portlet development articles that describe how to add extra features to your portlet, including single sign-on to external URL-based applications, HTML and XML filtering, parameter passing, and more.

Here are some reference articles to help you better understand the architecture and technical details of PDK-URL Services:

> - A Primer on PDK-URL Services
> - Understanding PDK-URL Services Runtime
> - Understanding provider.xml for PDK-URL Services

Revision History:

- November 2001