How to Build a Java Portlet

Oracle9iAS Portal Developer Kit
How to Build a Portlet Using an Existing Java Component

Once you have successfully installed and deployed the PDK-Java samples, you may want to build portlets from your existing Java, JSP, and Servlet applications. The PDK-Java Framework makes this easy, as it provides a generic mechanism for building portlets and you can easily 'plug in' your own applications.

To use the PDK-Java Framework to create a Java portlet, follow these three basic steps:

Create or use an existing Java, JSP, or Servlet.
Tell the PDK which Java component(s) to use in your portlet by editing a configuration file, called an XML provider definition
Then, register your provider and display your portlets on a page.

This article describes these steps in more detail, showing you how to create a Java portlet from an existing Servlet class and display it on a portal page. In this example we use a ManagedRenderer called Servlet20Renderer to easily render your existing Servlet.

For more information on Renderers or the PDK-Java Framework, review A Primer on the PDK-Java Provider Framework. To create Java portlet from an existing JSP or Java class, review Other Java Components.

ASSUMPTIONS

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.
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 when you get to the section "Configuring your Webserver".

USING AN EXISTING SERVLET

You can use an existing Servlet or the sample provided below. This is a standard HelloWorld Servlet and it does not require special Oracle9iAS Portal or PDK-Java imports or references. This article assumes you are using the sample.

Note: If you are using your own compiled Servlet class, please skip to the "Creating an XML provider definition" section and make any necessary name adjustments.

Using your favorite text editor, save the sample below as "MyServletPortlet.java". Remember the name of the directory where the file is saved as you will need this later. For example: C:\MyProvider\MyClasses

import java.io.*;

import javax.servlet.*;

import javax.servlet.http.*;

public class ShowServlet extends HttpServlet

{

public void doPost(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException

{

doGet(req, res);

}

public void doGet(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException

{

PrintWriter out = res.getWriter();

out.println("<B>Hello Servlet World!</B>");

}

}
 

Verify that the path to the servlet library (servlet.jar) is included in the CLASSPATH environment variable. If not, you will need to add it manually.
For example, at the system prompt type:
- On Windows NT:
```
set CLASSPATH=D:\9iAS\lib\servlet.jar;%CLASSPATH%
```
- On UNIX (csh):
```
setenv CLASSPATH ~/9iAS/lib/servlet.jar:$CLASSPATH
```
Verify that the Java executable is available in your system path.

To do this, type "java -version" at your system prompt. If this command is unsuccessful, locate the directory of the Java executable, and add it to your PATH environment variable, in a similar manner to the step above.

For example, if you have an Oracle9i Application Server installed in C:\iAS on Windows NT you would issue the following command:
Navigate to the directory where "MyServletPortlet.java" is saved and then compile this file using the following command:
This creates a class file called MyServletPortlet.class in the same directory.

CREATING AN XML PROVIDER DEFINITION

This section explains how to create an XML provider definition. This configuration file lists and defines your portlets and the providers they belong to. Each XML provider definition represents one provider with one or more portlets.

Using your favorite text editor, create an XML file that configures a provider for your portlet.

<?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>MyServletPortlet</name>
<title>My Servlet Portlet</title>
<description>This is my Servlet displayed as a portlet.</description>
<timeout>30</timeout>
<timeoutMessage>My Servlet Portlet timed out</timeoutMessage>
<acceptContentType>text/html</acceptContentType>

<renderer class="oracle.portal.provider.v1.RenderManager">
<showPage class="oracle.portal.provider.v1.http.Servlet20Renderer">
<servletClass>MyServletPortlet</servletClass>
</showPage>
</renderer>
</portlet>

</provider>

Save the file as "provider.xml", making sure not to overwrite one of the PDK-Java 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

Once you have configured your XML provider definition, you will tell your web server where the file is. This will allow your web server to expose your providers and portlets to Oracle9iAS Portal installations. The steps below describe how to configure the Oracle HTTP Server only. If you are using a third party listener, please take the appropriate steps.

Stop the Oracle HTTP Server.
Open the configuration file zone.properties
Under the Servlet Aliases section, register an alias myservlet for a new instance of the Provider Adapter servlet, to use the XML provider definition you have just created.

For example, add the line:
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:
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.
Save zone.properties
Make sure that MyServletPortlet.class is in the Oracle HTTP Server classpath, so that Provider Adapter can locate the class file (this step is not applicable to JSP applications):
1. Open the file jserv.properties
2. Add a wrapper.classpath entry at the end of the file which specifies the name of the directory containing MyServletPortlet.class.
  For example:
Start the Oracle HTTP Server.
Access your provider's test page by entering into a browser the URL for the aliased servlet you just set up. For example:
Note: You will use this URL later when you register the provider with Oracle9iAS Portal.
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.

Under the Administer tab (Oracle Portal Home Page), click Add a Portlet Provider.
Enter the following provider information:
1. Name: MyServletPortletProvider
2. Display Name: My Servlet Portlet Provider
3. Timeout: 100
4. Timeout Message: My Servlet Portlet Timed Out
5. Implementation Style: Web
6. Provider Login Frequency: Once per User Session
7. URL: the URL you used to display your provider's test page

ADDING THE JAVA PORTLET TO A PAGE

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

Now that you have successfully built your own Java portlet using an existing Java component, please look for future articles that describe how to add extra render modes and features to your portlet, including customization, session storage, multi-language capabilities, and more.

OTHER JAVA COMPONENTS

You may want to build a portlet from an existing JSP or Java application. You may want to build a portlet from an existing JSP or Java application. Most of the steps are the same, however you would need to update the XML provider definition file based on the Java component. This is illustrated in the examples below.

EXAMPLE - EXISTING JSP APPLICATION

Below is an XML provider definition for an existing JSP application called "MyJSPPortlet.jsp" in a directory: D:\9iAS\Apache\Apache\htdocs\jpdk\myjsp. The changes within the provider definition from a servlet to a JSP are noted in bold below. The steps to create a Java portlet from a JSP application are:

Place your JSP in the default JSP runtime directory, for example: D:\9iAS\Apache\Apache\htdocs.
Create an XML provider definition as demonstrated below. Be sure to update the physicalRoot and virtualRoot to point to the correct location.
Update the Oracle9iAS configuration files as demonstrated in Configuring Your WebServer.
Finally, register the Provider and display your portlet on a page as described in Registering Your Provider.

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

<!DOCTYPE provider [

<!ENTITY virtualRoot "/jpdk/">

<!ENTITY physicalRoot "D:\9iAS\Apache\Apache\htdocs\jpdk\">

]>

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

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

  <id>1</id>

  <name>MyJSPPortlet</name>

  <title>My JSP Portlet</title>

  <description>This is my JSP displayed as a portlet.</description>

  <timeout>30</timeout>

  <timeoutMessage>My JSP Portlet timed out</timeoutMessage>

  <acceptContentType>text/html</acceptContentType>

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

  <appPath>&virtualRoot;myjsp</appPath>

  <appRoot>&physicalRoot;myjsp</appRoot>

  <renderContainer>true</renderContainer>

  <contentType>text/html</contentType>

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

  <name>MyJSPPortlet.jsp</name>

  </showPage>

  </renderer>

</portlet>

</provider>

Take a look at the HelloServletWorld portlet in the PDK-Java Framework Samples provider.xml for more information on using the different ManagedRenderers.

EXAMPLE - EXISTING JAVA APPLICATION

Below is an XML provider definition for an existing Java application called "MyJavaApp.class". The changes within the provider definition from a servlet to a Java application are noted in bold below. The steps to create a Java portlet from a Java application are:

Create an XML provider definition as demonstrated below to point to your compiled Java class.
Update the Oracle9iAS configuration files as demonstrated in Configuring Your WebServer.
Finally, register the Provider and display your portlet on a page as described in Registering Your Provider.

<?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>MyJavaPortlet</name>

  <title>My Java Portlet</title>

  <description>This is my Java application displayed as a portlet.</description>

  <timeout>30</timeout>

  <timeoutMessage>My Java Portlet timed out</timeoutMessage>

  <acceptContentType>text/html</acceptContentType>

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

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

  <name>MyJavaApp.class</name>

  </showPage>

  </renderer>

</portlet>

</provider>

Revision History:

October 31, 2001