Oracle9iAS Portal Developer Kit
How to Add Java Portlets to an Existing Provider

Once you have successfully installed and deployed the PDK-Java samples, and have built a Java portlet of your own by following one of the "Getting Started" articles, you may consider adding portlets to an existing Web Provider (provider.xml). This article describes how to add Java portlets to an existing XML provider definition, i.e. provider.xml you created in the article How to Build a Java Portlet.

### ASSUMPTIONS

1. You have already installed the samples downloaded with the PDK-Java and understand the steps required to display a Java portlet on a portal page. For more information on installing the sample, please review the article Installing the PDK-Java Framework and Samples.

2. You are using the Oracle HTTP Server to execute and display servlets used by the PDK-Java. This listener need not be the same listener that serves your portal pages. If you are using a third party listener, this article will still be useful, but you may have to take alternative steps.

3. You have followed through and understood the article How to Build a Java Portlet.

4. You have already created a second Web portlet and would like to add it to an existing provider.xml file.

### ADDING PORTLETS

This section describes how to add a portlet, by editing the XML provider definition created in the previous article.

Each XML provider definition contains only one provider. The provider tags begins with <provider class="oracle.portal.provider.v1.http.DefaultProvider" <session>true</session> and ends with </provider> .

Even though a XML provider definition is limited to a single provider, it may contain many portlets. Each portlet begins with <portlet class="oracle.portal.provider.v1.http.DefaultPortlet"> and ends with </portlet>.

The following table displays the XML provider definition created in the article How to Build a Java Portlet. It contains one provider and a single portlet called MyCustomRenderer.

    <?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>

    <?providerDefinition version="2.0"?>

    <provider class="oracle.portal.provider.v1.http.DefaultProvider">

       <session>true</session>

       <portlet class="oracle.portal.provider.v1.http.DefaultPortlet">

          <id>1</id>

          <name>MyFirstPortlet</name>

          <title>My first portlet</title>

          <description>My first ever portlet, using my own custom renderer</description>

          <timeout>10</timeout>

          <timeoutMessage>Timed out waiting for MyFirstPortlet</timeoutMessage>

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

             <showPage class="MyCustomRenderer"/>

          </renderer>

       </portlet>

    </provider>

1. Stop the Oracle HTTP Server.

2. Using your favorite text editor, open the XML provider definition created by following the article How to Build a Java Portlet.

   For example C:\MyProvider\provider.xml.

3. Add a second portlet, by updating the file as shown below.

   Make sure to replace the information within <appPath>, <appRoot>, and <showPage> with information relating to your second portlet.

> Note: All additions are shown in bold. The second portlet begins after the </portlet> tag of the first portlet.

>     <?Xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>

>     <?providerDefinition version="2.0"?>

>     <!DOCTYPE provider [

>      <!ENTITY virtualRoot "/MyProvider/">

>      <!ENTITY physicalRoot "C:\MyProvider\htdocs\">

>     ]>

>     <provider class="oracle.portal.provider.v1.http.DefaultProvider">

>        <session>true</session>

>        <portlet class="oracle.portal.provider.v1.http.DefaultPortlet">

>           <id>1</id>

>           <name>MyFirstPortlet</name>

>           <title>My first portlet</title>

>           <description>My first ever portlet, using my own custom renderer</description>

>           <timeout>10</timeout>

>           <timeoutMessage>Timed out waiting for MyFirstPortlet</timeoutMessage>

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

>              <showPage class="MyCustomRenderer"/>

>           </renderer>

>        </portlet>

>     <portlet class="oracle.portal.provider.v1.http.DefaultPortlet">

>           <id>2</id>

>           <name>MySecondPortlet</name>

>           <title>My second portlet</title>

>           <description>My second portlet!</description>

>           <timeout>10</timeout>

>           <timeoutMessage>MySecondPortlet timed out.</timeoutMessage>

>           <hasHelp>true</hasHelp>

>           <hasAbout>true</hasAbout>

>           <showDetails>true</showDetails>

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

>              <contentType>text/html</contentType>

>              <appPath>&virtualRoot;MySecondPortlet</appPath>

>              <appRoot>&physicalRoot;MySecondPortlet</appRoot>

>              <showPage class="MyCustomRenderer"/>

>              <helpPage>help.html</helpPage>

>              <aboutPage>about.jsp</aboutPage>

>              <showDetailsPage class="oracle.portal.provider.v1.http.Servlet20Renderer">

>                 <servletClass>MyShowDetailsServlet</servletClass>

>              </showDetailsPage>

>           </renderer>

>        </portlet>

>     </provider>

> Note the following:

> - <id> is a required tag and holds the portlet ID number. This number must be unique within a portlet provider.
> - <name> is a required tag and holds the portlet name. The name must be unique and contain no spaces or special characters.
> - <title> is a recommended tag. The title is the display name for the portlet and is what is seen by users accessing your portlet. The title may contain spaces and special characters.
> - <description> tag is a recommended tag. The description is displayed to users adding portlets to a page.
> - <timeout> tag is optional and specifies the time (in seconds) that the Portal will wait for the portlet, before it times out. If no timeout is specified, it defaults to the timeout of the Provider.
> - <timeoutMsg> is optional and holds the message that is displays when the portlet times out. If no timeout message is specified, it defaults to the timeout message of the Provider.
> - The rest of the tags relate to the various show modes.
> - <appPath> is a required tag for JSPs and holds the virtual path to root of pages that render the portlet.
> - <appRoot> is a required tag for JSPs and holds the physical path to the root of pages that render the portlet.
> - <showPage>is a required tag for JSPs and specifies the page that renders the portlet.

2. Save and close the file.

3. Start the Oracle HTTP Server.

### VIEWING THE PORTLET

1. As your XML provider definition is already registered (as MyProvider), you just need to refresh the portlet repository view the additional portlet.

2. Log in to Oracle9iAS Portal as a Portal administrator.

3. Click the Administer tab located in the Oracle9iAS Portal HomePage.

4. Within the Provider portlet, click Display Portlet Repository.

5. In the top-right hand screen, click Refresh.

   You should now see the second portlet under your provider in the portlet repository.

You have now successfully added additional Java portlets to an existing XML Provider definition and can now add the second portlet to your page. To continue adding portlets, repeat the steps listed within the sections "Adding Portlets" and "Viewing the Portlet".

Revision History:

- July 12, 2001.