Oracle9iAS Portal Developer Kit (PDK)
Building Java Portlets Using Existing Applications (based on Oracle9i JDeveloper)

Introduction

When you have successfully deployed and registered the PDK samples, you can build portlets from existing Java, JSP, and Servlet applications.  To deploy Java components in OC4J (based on J2EE), you need to package your classes, libraries, and any additional files needed to execute your component and deploy your .ear file to OC4J.  Oracle9i JDeveloper simplifies this process by automatically packaging and deploying your component.  

There are a few basic steps to build a Java portlet based on an existing application:

• Create or use an existing Java, JSP, or Servlet already deployed to OC4J.

• Include the necessary PDK libraries in your classpath.

• Update the file web.xml to point to the PDK Provider Adapter.

• Update the sample provider definition file with your component information.

• Point the PDK Provider Adapter to your provider definition file.

• Package and deploy your portlet.

This article describes how to manually use Oracle9i JDeveloper  and the PDK to build Java portlets from existing Java components. Using Oracle9i JDeveloper eliminates the need to manually package and deploy your portlets to OC4J.  In this example we use a ManagedRenderer called RenderManager to easily render an existing Java Servlet (this is used in the provider.xml).  For more information on Renderers, or the PDK Framework, review the article A Primer on the PDK Provider Framework.  

This article is based on an existing Java Servlet. To use an existing JSP or Java class instead, review Other Java Components later in this article.

Note:  This article describes how to manually build portlets using Oracle9i JDeveloper, you can also review Building Porltets Using the Java Portlet Wizard which describes how to use build, test, and deploy portlets using a wizard-based declarative UI.

Assumptions

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

2. You are using OC4J to execute and display Servlets used by the PDK.

3. You are already familiar with Oracle9i JDeveloper and know how to build and deploy Java components using Oracle9i JDeveloper.

Using an Existing Servlet

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, please skip to the Updating Your Project for the PDK section and make any necessary name adjustments.   

1. Enter the following portlet code in a project using Oracle9i JDeveloper.  Provide the name HelloServlet.java.

   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!");    } }

2. Make sure the Servlet Runtime library is in your development classpath.

   1. Right mouse click on your current project.

   2. Select Project Settings.

   3. Click Libraries under Development and move Servlet Runtime to the selected classes.

3. Click the Make Project icon on the toolbar or select Ctrl+F9 on the keyboard.  This compiles your portlet code.

   Note:  Your portlet code must compile without any errors to be successfully deployed.

4. Create an Application Server Connection.

1. In the Navigator, under Connection, right mouse click on Application Server.

2. In the popup menu, click New Connection, and follow the steps for the Connection Wizard. Provide the name and type of connection:

   • name:  <anything you want>
   • type:  Oracle9i Application Server

3. Enter the administrator username and password of the OC4J instance where you are deploying your Java component.  Check the 'Deploy Password' checkbox to store the username and password.

4. Enter the URL of the host running OC4J.  This is based on Oracle Remote Method Invocation (ORMI) protocol, so the URL should resemble:  

   ormi://hostname:port#

5. Enter the directory where the admin.jar is located for OC4J.

6. Test your connection.  You should receive a 'Success' status.  If you did not receive this status, go back and check your settings.

5. Create a Deployment Profile.

   1. Right mouse click on your project and select New...

   2. Under the Deployment Profiles Category, select J2EE Web Module (WAR file).

   3. Select he name and the location of the deployment profile, or leave the default.

   4. The WEB-INF/lib branch defines the libraries you want to attach to the deployment.  To reduce the deployment file size, the libraries listed here can also be added to the CLASSPATH of OC4J by copying them to the %OC4J_HOME%\lib folder (if not already there).

This creates two entries under your project, a deployment profile and the file web.xml.

6. Update web.xml with the following text to display your component:

<?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app> <!-- A demo servlet, add servlets below --> <servlet> <servlet-name>HelloServlet</servlet-name> <servlet-class>HelloServlet</servlet-class> </servlet> </web-app>

7. Right mouse click on the deployment profile and deploy the project to the connection you created.  You should receive the following message:

Exit status of Oracle9iAS admin tool: 0

-----Deployment finished.  -----

8. You should now be able to access you Java component with the following URL:

   http://host.domain:port/<application>/servlet/HelloServlet

UPDATING YOUR PROJECT FOR THE PDK

Now that the existing Java component is deployed using Oracle9i JDeveloper, you can update your project quickly and easily to display it as a portlet in Oracle9iAS Portal.  These are the steps involved:

• Add the PDK libraries required

• Update web.xml

• Enter information in the provider definition and point the PDK Provider Adapter to the provider definition.

1. Right mouse click on your project and select Project Settings.

2. Select the PDK libraries to include in your project.  You may need to create the libraries first:

   • pdkjava.jar
   • ptlshare.jar

3. You need to include one or more of these libraries upon deployment.  If your OC4J instance is the same one being used for Oracle9iAS Portal, then you should only need pdkjava.jar, otherwise include all of the libraries.

   1. Right mouse click on the deployment profile and select Settings.

   2. Check the libraries you want to include upon deployment.

4. Update web.xml so that OC4J calls the PDK Provider Adapter.  This web.xml enables Oracle9iAS Portal to communicate directly with the PDK Provider Adapter.  The Adapter uses the XML provider definition to render your Java component as a portlet.

   <?xml version = '1.0' encoding = 'UTF-8'?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app> <display-name>Web-App1</display-name> <description>Web-App1 Sue</description>   <servlet> <servlet-name>SOAPServlet</servlet-name> <display-name>SOAPServlet</display-name> <description>Extended Portal SOAP Server</description> <servlet-class>oracle.webdb.provider.v2.adapter.SOAPServlet</servlet-class>   </servlet> <servlet-mapping> <servlet-name>SOAPServlet</servlet-name> <url-pattern>/providers</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>SOAPServlet</servlet-name> <url-pattern>/providers/*</url-pattern> </servlet-mapping> <session-config> <session-timeout>50</session-timeout> </session-config> <login-config> <auth-method>BASIC</auth-method> </login-config> </web-app>

5. Use a text editor, save the following information as "provider.xml" in the directory:  %OC4J_HOME%\applications\<application>\<application>\WEB-INF\providers\myportlet\.

   For example:  C:\9iAS\Apache\oc4j\j2ee\home\applications\myservlet\myservlet\WEB-INF\providers\myportlet

   The names of the directories \providers\myportlet is not important as long as it matches the information in the _default.properties file (see Step 7 below).  Update the information in bold.  The <showPage> tag must point to your Java Servlet.

<?Xml version="1.0" encoding="UTF-8" standalone="yes"?> <?providerDefinition version="3.1"?> <provider class="oracle.portal.provider.v2.DefaultProviderDefinition"> <session>true</session> <useOldStyleHeaders>false</useOldStyleHeaders>   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition"> <id>1</id> <name>MyServletPortlet</name> <title>My Servlet Portlet</title> <description>This is my Servlet Portlet</description> <timeout>30</timeout> <timeoutMessage>My Servlet Portlet Timed Out</timeoutMessage> <acceptContentType>text/html</acceptContentType> <showEdit>false</showEdit> <showEditToPublic>false</showEditToPublic> <showEditDefault>false</showEditDefault> <showPreview>false</showPreview> <showDetails>false</showDetails> <hasHelp>false</hasHelp> <hasAbout>false</hasAbout> <renderer class="oracle.portal.provider.v2.render.RenderManager"> <contentType>text/html</contentType> <showPage>/servlet/HelloServlet</showPage> </renderer> </portlet>   </provider>

6. Create a directory called deployment under %OC4J_HOME%\applications\<application>\<application>\WEB-INF\.

   For example:  C:\9iAS\Apache\oc4j\j2ee\home\applications\myservlet\myservlet\WEB-INF\deployment

7. Use a text editor to save  the following information as "_default.properties" in the deployment directory.  Make sure definition specifies the location of your provider.xml file. 

   serviceClass=oracle.webdb.provider.v2.adapter.soapV1.ProviderAdapter loaderClass=oracle.portal.provider.v2.http.DefaultProviderLoader showTestPage=true definition=providers/myportlet/provider.xml autoReload=true

8. Right mouse click on your deployment profile and deploy your project.

9. You should now be able to access the PDKProvider Adapter using the following URL:

   http://host.domain/<application>/providers

   web.xml provides a URL pattern to /providers/* that allows you to use the above URL instead of the standard:  http://host.domain/<application>/servlet/SOAPServlet.  Use the URL above to register your provider.

10. You should see a successful test page when you access the URL in Step 9.

REGISTERING THE PROVIDER

Once you have successfully tested your new provider, register the provider with Oracle9iAS Portal:

1. Click Builder in the top right hand corner of the Oracle9iAS Portal Home Page, then click Register a Portlet Provider in the Provider portlet.

2. Enter the following provider information:

   1. Name:  MyHelloServletProvider.

   2. Display Name:  My Hello Servlet Provider.

   3. Timeout:  100.

   4. Timeout Message:  My Hello Servlet Provider Timed Out.

   5. Implementation Style:  Web.

   6. Provider Login Frequency:  Never.

   7. URL:  The registration URL is:

   http://{host}:{port}/<application>/providers (same as used above).

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.  You have now successfully built your own Java portlet using Oracle9i JDeveloper and an existing Java component.

OTHER JAVA COMPONENTS

You may want to build a portlet from an existing JSP or Java application. Most of the steps are the same, however updates to your XML provider definition file depend 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".  The differences 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:

1. Place your JSP is a directory under your .war root such as %OC4J_HOME%\applications\<application>\<application>\htdocs\myjsp.  Point to this location from the XML provider definition.

2. Update your project in JDeveloper as described in Updating Your Project For The PDK.

3. Create an XML provider definition as demonstrated below.

4. Finally, register the Provider and display your portlet on a page as described in Registering Your Provider.

<?Xml version="1.0" encoding="UTF-8" standalone="yes"?> <?providerDefinition version="3.1"?> <provider class="oracle.portal.provider.v2.DefaultProviderDefinition"> <session>true</session>   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition"> <id>3</id> <name>MyJSPPortlet</name> <title>My JSP Portlet</title> <shortTitle>JSPPortlet</shortTitle> <description>This is my JSP Portlet</description> <timeout>10000</timeout> <timeoutMessage>JSP Portlet timed out</timeoutMessage> <showEdit>false</showEdit> <showEditDefault>false</showEditDefault> <showPreview>false</showPreview> <showDetails>false</showDetails> <hasHelp>false</hasHelp> <hasAbout>false</hasAbout> <acceptContentType>text/html</acceptContentType> <renderer class="oracle.portal.provider.v2.render.RenderManager"> <contentType>text/html</contentType> <showPage>/htdocs/myjsp/myjspportlet.jsp</showPage> </renderer> </portlet> </provider>

Take a look at any of the JSP portlets in the PDK 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 differences 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:

1. Place your Java class in your OC4J classpath.

2. Update your project in JDeveloper as described in Updating Your Project For The PDK.

3. Create an XML provider definition as demonstrated below to point to your compiled Java class.

4. Finally, register the Provider and display your portlet on a page as described in Registering Your Provider.

<?Xml version="1.0" encoding="UTF-8" standalone="yes"?> <?providerDefinition version="3.1"?> <provider class="oracle.portal.provider.v2.DefaultProviderDefinition"> <session>true</session>   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition"> <id>3</id> <name>MyJavaPortlet</name> <title>My Java Portlet</title> <shortTitle>JAVAPortlet</shortTitle> <description>This is my Java Portlet</description> <timeout>10000</timeout> <timeoutMessage>Java Portlet timed out</timeoutMessage> <showEdit>false</showEdit> <showEditDefault>false</showEditDefault> <showPreview>false</showPreview> <showDetails>false</showDetails> <hasHelp>false</hasHelp> <hasAbout>false</hasAbout> <acceptContentType>text/html</acceptContentType> <renderer class="oracle.portal.provider.v2.render.RenderManager"> <contentType>text/html</contentType> <showPage class="oracle.portal.provider.v2.render.http.JavaRenderer"/>   <className>MyJavaApp</className>   <renderMethod>methodName</renderMethod> </showPage> </renderer> </portlet>   </provider>