| Last Updated: | April 3, 2003 |
| Status: | Production |
| Version: | PDK Release 2 (9.0.2) and later |
Once you have successfully installed and deployed the PDK samples, you will probably want to begin building Java portlets of your own. The PDK Framework makes this easy, as it provides two way to quickly and easily begin building portlets:
When using the PDK Framework to create a Java portlet, you'll follow these two basic steps:
First, select or implement the portlet controller classes that provide your portlet's behavior. The default runtime uses controller classes which enable you to 'plug in' your components such as Java classes, Java Servlets, Java Server Pages (JSPs), etc. The controllers classes extend the following abstract classes:
PortletRenderer: Generates a visual representation of the portlet (usually in HTML) in all the various 'render modes' that it supports. Since a portlet must always support at least one render mode (the basic 'show' mode), every portlet requires such an object.
PortletPersonalizationManager: If portlet behavior can be customized through an HTML form, one of these controller classes are required in order to store and retrieve customized parameters.
PortletSecurityManager: More advanced portlets may want to restrict users to certain portlet instances. An object of this type is required to enforce such security policies.
Then, create an XML provider definition that configures your portlet and its controller classes within a provider.
This article describes how to manually build portlets for the PDK by plugging in your applications to the predefined renderers, This article describes this in more detail, showing you how to create a portlet from an existing Java Servlet, Java Server Page (JSP), Java class or build your own 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. Whether using an existing Java component or building your renderer, you plug-in your component to a controller class such as RenderManager in the XML provider definition file. For more information on building portlets using the Java Portlet Wizard, an extension of Oracle9i JDeveloper, review Building Portlets Using the Java Portlet Wizard.
For more information about controller classes and rendering portlets using the PDK Framework, review Understanding the PDK Provider Framework.
You have already installed the samples downloaded with the PDK 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 Framework and Samples.
You are using the Oracle9iAS (Oracle J2EE container, OC4J) to execute and display components used by the PDK. 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".
You can use an existing Servlet or the sample provided below. The sample is a standard "HelloWorld" Servlet and it does not require special Oracle9iAS Portal or PDK imports or references. This article assumes you are using this sample.
Note: If you are using your own compiled Servlet class that has already been deployed to OC4J, skip to the XML Provider Definition - Servlet section and make any necessary name adjustments.
import javax.servlet.*;
Import javax.servlet.http.*;
public class Time 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("Welcome to My Java Component!");
}
}
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 Oracle9iAS Portal page. Within a XML provider definition you list and define one or more portlets as well as provider and portlet parameters.
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 point to your Servlet mapping for 'show' mode. This Servlet mapping is file system based, your Servlet must reside on the same OC4J instance where you have deployed the PDK. For example, this Servlet may be stored within your OC4J library.
Remember the name of the directory where the file is saved as you will need this later. For example: C:\MyProvider\provider.xml
You can use an existing JSP or the sample provided below. The sample is a standard "HelloWorld" JSP and it does not require special Oracle9iAS Portal or PDK imports or references. This article assumes you are using this sample.
Note: If you are using your own compiled JSP, skip to the XML Provider Definition - JSP section and make any necessary name adjustments.
<%@ page contentType="text/html;charset=WINDOWS-1252"%> <HTML> <HEAD> <TITLE>OC4J JSP Sample - Hello Oracle World</TITLE> </HEAD> <BODY background="../images/Background.gif"> <P> <BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> <B><CENTER><FONT COLOR=BLACK SIZE=5> <TABLE BORDER BGCOLOR=BLACK> <TR> <TD ALIGN=CENTER VALIGN=CENTER> <B><FONT COLOR=RED SIZE=5> <% out.println(" Hello Oracle World"); %> ! </B> </TD> </TR> </TABLE> </CENTER></B> </P> </BODY> </HTML>
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 Oracle9iAS Portal page. Within a XML provider definition you list and define one or more portlets as well as provider and portlet parameters.
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 point to your JSP for 'show' mode.
Remember the name of the directory where the file is saved as you will need this later. For example: C:\MyProvider\provider.xml
public class HelloWorldApp { public static void main(String[] args) { // Display "Hello World!" System.out.println("Hello World!"); } }
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 Oracle9iAS Portal page. Within a XML provider definition you list and define one or more portlets as well as provider and portlet parameters.
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 point to your Java class mapping for 'show' mode.
Remember the name of the directory where the file is saved as you will need this later. For example: C:\MyProvider\provider.xml
Your first task is to set up a PortletRenderer controller to render portlet output. For this, the PDK 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 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 illustrate how to use of some of these classes, but in this article you create your own, just to show you how easy it is.
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.v2.*; Import oracle.portal.provider.v2.render.*; Import oracle.portal.provider.v2.render.http.*; 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); } } }
Remember the name of the directory where the file is saved as you will need this later.
Verify that the path to the PDK Framework library pdkjava.jar, and also ptlshare.jar and jazn.jar are included in the CLASSPATH environment variable. If not, you must add it manually. These files can be found in the jpdk.war which is itself part of jpdk.ear.
For example, if files from jpdk.war are placed in C:\jpdk\lib, at the system prompt type:
On Windows NT:
set CLASSPATH=C:\jpdk\lib\pdkjava.jar;C:\jpdk\lib\ptlshare.jar;C:\ias\j2ee\home\jazn.jar;%CLASSPATH%
On UNIX (csh):
setenv CLASSPATH ~/jpdk/lib/pdkjava.jar:~/jpdk/lib/ptlshare.jar:$J2EE_HOME/jazn.jar:$CLASSPATH
Verify that the Java executable is available in your system path.
To do this, type "java -version" at the 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 step 3 above.
For example, if you have an Oracle9i Application Server installed in C:\iAS on Windows NT, issue the following command:
set PATH=C:\iAS\Apache\jdk\bin;%PATH%
Or on UNIX:
setenv PATH ~/$ORACLE_HOME/jdk/bin:$PATH
Make the directory 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.
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.
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.
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<?providerDefinition version="3.1"?>
<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
<session>false</session>
<portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
<id>1</id>
<name>MyFirstPortlet</name>
<title>My first portlet</title>
<ShortTitle>MyFirstPortlet</ShortTitle>
<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.v2.render.RenderManager">
<showPage class="MyCustomRenderer"/>
</renderer>
</portlet>
</provider>
|
Remember the name of the directory where the file is saved as you will need this later. For example: C:\MyProvider\provider.xml
To add your portlet to a provider and install that provider into OC4J, refer the article "Packaging and deploying Your Provider".
After setting up the Web Provider Sample with the Oracle HTTP Server, you must register the provider with Oracle9iAS Portal before adding the sample portlet(s) to a page.
Under the Build tab (on Oracle9iAS Portal Home Page), click on Register a Portlet Provider within the portlet called Providers.
Name: SampleWebProvider
Display Name: Sample Web Provider
Timeout: 100
Timeout Message : Application Timed Out
Implementation Style : Web
Click Next.
On the General Properties page, provide the following (leave other entries as default):
URL: eg http://myserver.mydomain.com:port/jpdk/providers/ (replace this with your provider URL)
Service ID: sample (you can also choose one of the other providers listed above)
Under the User/Session Information section, select the User radio button.
Login Frequency : Once per User Session
Proxy Settings : If you need to go through a Proxy Server to access your providers, you must setup your Proxy Settings for Oracle9iAS Portal, otherwise leave as default.
Click Next.
Grant Access to your provider.
Once your provider is registered you can add your new Java portlet to a page. Please refer to the Oracle9iAS Portal Help for detailed information on how to do this.
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: |
|
| Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ |
Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 |
Copyright and Corporate Info |