Oracle9iAS Portal Developer Kit
How to Build a Java Portlet

Once you have successfully installed and deployed the PDK-Java samples, you will probably want to begin building Java portlets of your own.  The PDK-Java Framework makes this easy, as it provides a generic mechanism for building portlets and you can easily 'plug in' your own extensions.

When using the PDK-Java Framework to create a Java portlet, you'll follow these two basic steps:

This article describes these steps in more detail, showing you how to create a simple Java portlet and display it on a portal page. In this example we use a single PortletRenderer controller called RenderManager to give the portlet its basic rendering capabilities.  In further articles, we will show you how to extend your portlet's functionality using other types of controller class.

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

CREATING A RENDERER

Your first task is to set up a PortletRenderer controller to render portlet output.  For this, PDK-Java Framework provides a very flexible RenderManager implementation.  RenderManager takes care of the basics required of any PortletRenderer, for example it renders standard headers and footers for portlet 'containers'.  All you need to do is to provide a simple 'content generator', or ManagedRenderer that generates the main body of your portlet for a particular render mode. Note that a content generator is required for each of the render modes the portlet is to support.

The PDK-Java Framework provides a range of ManagedRenderers that allow you to utilize other Web technologies to generate portlet content, such as static HTML files, JSPs and Servlets.  In later articles, we will illustrate how to use of some of these classes, but in this article you will create your own, just to show you how easy it is.

  1. Using your favorite text editor, create a Java class called MyCustomRenderer, that extends BaseManagedRenderer (the base of all ManagedRenderers) and provide an implementation of the renderBody method to generate the content of your portlet.

    You may write your own Java code, or use the sample code provided below which outputs a personalized greeting to the user currently logged in. 

    import java.io.*;
import oracle.portal.provider.v1.*;
import oracle.portal.provider.v1.http.BaseManagedRenderer;

public class MyCustomRenderer extends BaseManagedRenderer
{
    public void renderBody(PortletRenderRequest pr) throws PortletException
    {
        try
        {
            // Get a writer for this renderer's output
            PrintWriter out = pr.getWriter();

            // Generate output and send to the writer
            out.println("<b>Hi " + pr.getUser().getName() + "!</b><br>");
            out.println("This output was generated by my very own renderer!");
        } 
        catch (IOException ioe)
        {
            throw new PortletException(ioe);
        }
    }
}

  2. Save the file as MyCustomRenderer.java.

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

  3. Verify that the path to the PDK-Java Framework library (provider.jar) is included in the CLASSPATH environment variable.  If not, you will need to add it manually.

    For example, at the system prompt type:

  4. 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:

      set PATH=C:\iAS\Apache\jdk\bin;%PATH%

  5. Make the directory you in which you saved MyCustomRenderer.java the current directory and then compile this file using the following command:

      javac MyCustomRenderer.java

    This creates a class file called MyCustomRenderer.class in the same directory.

CREATING AN XML PROVIDER DEFINITION

This section explains how to create an XML provider definition for the provider object that will host your new portlet and allow it to be added to an Oracle Portal page.  Within a XML provider definition you configure provider parameters for your portlets and any 'controller' objects that they use.

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

    For this example, specify that you are using a RenderManager object as a controller for rendering and an object of your own custom class (MyCustomRenderer) as the ManagedRenderer for 'show' mode.

  2. 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

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 myfirst for a new instance of the Provider Adapter servlet, to use the XML provider definition you have just created.

    For example, add the line:

  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:

    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. Make sure that MyCustomRenderer.class is in the Oracle HTTP Server classpath, so that Provider Adapter can locate the class file for your custom renderer:

    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 MyCustomRenderer.class. 

      For example:

  7. Start the Oracle HTTP Server.

  8. 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 on a portal.  

  9. 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:  MyFirstPortletProvider

    2. Display Name:  My First Portlet Provider

    3. Timeout:  100

    4. Timeout Message:  My First 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, please look for future articles that describe how to add extra features to your portlet, including customization, session storage, multi-language capabilities, and more.

Revision History: