7 Enhancing Java Portlets

This chapter explains how to enhance Java portlets you created with the Oracle JDeveloper Portal Add-In, and how to make a portlet out of your struts application. This chapter contains the following sections:

• Section 7.1, "Enhancing JPS Portlets"

• Section 7.2, "Enhancing PDK-Java Portlets"

• Section 7.3, "Building Struts Portlets with Oracle JDeveloper"

The source code for many of the examples referenced in this chapter is available as part of PDK-Java. You can download PDK-Java on Oracle Technology Network (OTN):

http://www.oracle.com/technology/products/webcenter/index.html

When you unzip PDK-Java, you will find the examples in:

../pdk/jpdk/v2/src/oracle/portal/sample/v2/devguide

You can find the Javadoc reference for PDK-Java in:

../pdk/jpdk/v2/apidoc

7.1 Enhancing JPS Portlets

Once you have built your initial portlet in the Portlet Wizard as described in Section 6.3.1, "Creating a JSR 168 Portlet", you will want to enhance it. Because JPS portlets adhere to the Java standards, you can find substantial information about enhancing them from many different sources, such as third party books and Web pages. One of the more important enhancements that you might wish to perform is Section 7.1.1, "Adding Personalization", which is described in this section.

7.1.1 Adding Personalization

In this section, you enhance the portlet you created in Section 6.3.1, "Creating a JSR 168 Portlet" with some code that allows a user in Edit or Edit Defaults mode to paste HTML into a field for the portlet to render. You will also see how easily you can redeploy a portlet.

7.1.1.1 Assumptions

To perform the tasks in this section, we are making the following assumption:

• You built a portlet using the wizard, successfully registered the producer, and added the portlet to the page.

7.1.1.2 Implementing Personalization

In this section, you add some code to My Java Portlet, redeploy the portlet, and then test it in Oracle Portal. To do this, perform the following steps:

1. In Oracle JDeveloper, double-click the view.jsp file for your JPS-Standard portlet in the Application Navigator.

2. Add the code that is indicated in bold in the following snippet:

   <%@ page contentType="text/html"
      import="javax.portlet.*,java.util.*,mypackage1.Portlet1,
       mypackage1.resource.Portlet1Bundle"%>"
   <%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
   <portlet:defineObjects/>
   <%
      PortletPreferences prefs = renderRequest.getPreferences();
   %>
   <%= prefs.getValue("portletContent", "Portlet Content") %>
   

3. Open edit.jsp in the visual designer and click the Design tab. Notice that the JSP consists of a form field, a form input field, and two form button fields, as shown in Figure 7-1.

   Figure 7-1 edit.jsp in the Design View

   
   Description of "Figure 7-1 edit.jsp in the Design View"
   
   

4. Add the code that is indicated in bold in the following snippet to implement a form field called Content:

   <FORM ACTION="<portlet:actionURL/>" METHOD="POST">
   <TABLE BORDER="0">
   <TR><TD WIDTH="20%">
   <P CLASS="portlet-form-field" ALIGN="right">
   <%= res.getString(Portlet1Bundle.PORTLETTITLE) %>
   </P></TD><TD WIDTH="80%"><INPUT CLASS="portlet-form-input-field" TYPE="TEXT"
     NAME="<%= Portlet1.PORTLETTITLE_KEY %>"
     VALUE="<%= prefs.getValue(Portlet1.PORTLETTITLE_KEY,
        res.getString("javax.portlet.title")) %>"
     SIZE="20">
   </TD></TR>
   <tr><td width="20%">
   <p class="portlet-form-field" align="right">
   Content
   </p>
   </td><td width="80%">
   </td></tr>
   <TR><TD COLSPAN="2" ALIGN="CENTER">
   <INPUT CLASS="portlet-form-button" TYPE="SUBMIT" NAME= 
      "<%= Portlet1.OK_ACTION%>"
      VALUE="<%= res.getString(Portlet1Bundle.OK_LABEL) %>">
   <INPUT CLASS="portlet-form-button" TYPE="SUBMIT" NAME=
      ="<%=Portlet1.APPLY_ACTION %>"
      VALUE="<%= res.getString(Portlet1Bundle.APPLY_LABEL) %>"></TD></TR>
   </TABLE>
   

5. Click the Design tab to see the new form field that you just added (Figure 7-2).

   Figure 7-2 Modified edit.jsp in the Design View

   
   Description of "Figure 7-2 Modified edit.jsp in the Design View"
   
   

6. Open WelcomePortlet.java in the visual editor and insert the following two lines of code (indicated in bold) in the processAction method:

   // Save the preferences.
   PortletPreferences prefs = request.getPreferences();
   String param = request.getParameter(PORTLETTITLE_KEY);
   prefs.setValues(PORTLETTITLE_KEY, buildValueArray(param));
   String contentParam = request.getParameter("portletContent");
   prefs.setValues("portletContent", buildValueArray(contentParam));
   prefs.store();
   

7. Redeploy the portlet. Notice that Oracle JDeveloper automatically saves and compiles the code before deploying the portlet. Refer to Section 6.3.3, "Deploying Your JSR 168 Portlet to the Oracle WebLogic Server" for a reminder of how to perform this step.

8. In Oracle Portal, reload the page that contains the portlet. The portlet displays the text Portlet Content, which was one of the changes you made in Oracle JDeveloper.

9. Click the Customize link. You can see the new form field that you added in Oracle JDeveloper.

10. Enter the following HTML in the Content field, replacing the words Portlet Content.

11. <p>Read <em>The Path to Portlet Interoperability</em> by John Edwards in
    <strong>Oracle Magazine</strong>, Nov-Dec 2003. </p>
    <p>It discusses JSR 168 and WSRP open portals. </p>
    

12. Click Apply and then click Close. The HTML is rendered in the portlet.

7.2 Enhancing PDK-Java Portlets

Once you have built your initial portlet in the Portlet Wizard as described in Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper", you may perform the following tasks to enhance it:

• Section 7.2.1, "Adding Show Modes"

• Section 7.2.2, "Adding Personalization"

• Section 7.2.3, "Passing Parameters and Submitting Events"

• Section 7.2.4, "Using JNDI Variables"

• Section 7.2.6, "Accessing Session Information"

• Section 7.2.7, "Implementing Portlet Security"

• Section 7.2.8, "Controlling the Export/Import of Portlet Personalizations"

• Section 7.2.9, "Enhancing Portlet Performance with Caching"

• Section 7.2.11, "Writing Multilingual Portlets"

This section assumes the following:

• You are familiar with portlet terminology such as portlet Show modes. Refer to Chapter 1, "Understanding Portlets" and Section 6.1, "Guidelines for Writing Java Portlets".

• You have already downloaded and installed the Java Portlet Container.

• You are already familiar with Oracle JDeveloper and know how to build and deploy Java components using it. You can download Oracle JDeveloper from OTN. Visit the Oracle JDeveloper page on OTN:

  http://www.oracle.com/technology/products/jdev/index.html
  

7.2.1 Adding Show Modes

In the Portlet Wizard, you add Show modes by checking boxes on the wizard pages. Refer to Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper" for more information about using the wizard. For each Show mode that you select in the wizard, a basic HelloWorld skeleton is created. If you need to add a Show mode after creating the portlet or you are adding one of the modes (preview or link) not available through the wizard, you can do that manually by updating provider.xml and HTML or JSPs in Oracle JDeveloper. The following sections explain how to add Show modes to a PDK-Java portlet:

• Section 7.2.1.2, "Implementing Extra Show Modes"

• Section 7.2.1.3, "Updating the XML Provider Definition"

• Section 7.2.1.4, "Viewing the Portlet"

Once you have completed this section, you will be able to implement any Show mode using RenderManager because the principles are the same for all modes. For example, even though this section does not describe how to implement the Help mode in detail, you will understand how to do it, as the process is the same as for Preview mode, which is described here.

For more detailed information on the PDK runtime classes used in this section, refer to the Javadoc on OTN by clicking Java Doc API on the Portlet Development page available at

http://www.oracle.com/technology/products/ias/portal/portlet_development_10g1014.html

For more information on the syntax of provider.xml, refer to the provider Javadoc:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

7.2.1.1 Assumptions

To perform the tasks in this section, we are making the following assumption:

• You built a portlet using the wizard, successfully registered the producer, and added the portlet to the page.

7.2.1.2 Implementing Extra Show Modes

Your first task when creating Show modes manually is to create an HTML file or JSP for each mode. For example, if you want to implement Preview mode, you need to create an HTML file to provide preview content.

To create an HTML file to preview content, perform the following steps:

1. In Oracle JDeveloper, open the project that contains your portlets.

2. Under Web Content, htdocs\myportlet, create an HTML page called PreviewPage.html. The content of the file could be something similar to the following:

   <p>This is the <i>preview</i> mode of your portlet!</p>
   

Once you have created the HTML file for previewing content, you are ready to update the XML provider definition.

7.2.1.3 Updating the XML Provider Definition

When you want to expose additional Show modes you must update your XML provider definition as follows:

• Set a boolean flag that indicates to the PDK Framework that a link or icon to that mode should be rendered.

• Point to the HTML file or JSP that you created for that mode.

For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

For example, if you want to render Preview mode, perform the following steps:

1. Edit the provider definition file, provider.xml and add the tag to activate Preview mode within the <portlet></portlet> tags:

   <showPreview>true</showPreview>
   

2. Specify the preview page to be the HTML page that you created in Section 7.2.1.2, "Implementing Extra Show Modes":

   <previewPage>/htdocs/myportlet/MyPortletPreviewPage.html</previewPage>
   

3. Save the updates to provider.xml.

4. Redeploy your portlet. Refer to step 11 in Section 6.5.4, "Deploying Your Oracle PDK-Java Portlet to an Application Server.".

   When you redeploy, Oracle JDeveloper automatically saves and compiles the code before deploying the portlet.

7.2.1.4 Viewing the Portlet

To view the new Show modes, you must ensure that your updated XML provider definition is re-parsed. To do this, perform the following steps:

1. Copy the HTML file you created in Section 7.2.1.2, "Implementing Extra Show Modes" and provider.xml to the WebLogic Server instance where you plan to deploy the portlet.

2. Refresh the provider.

3. Refresh the portal page containing your portlet.

To view Preview mode, do the following:

1. Edit a page or create a new page and choose Add Portlet.

2. Navigate to the location of your provider in the Portlet Repository (for example, Portlet Staging Area) and find your portlet. Note the magnifying glass icon next to the portlet shown in Figure 7-3

   Figure 7-3 Add Portlet Page

   
   Description of "Figure 7-3 Add Portlet Page"
   
   

3. Click the magnifying glass icon next to the portlet and a preview window similar to the one in Figure 7-4 displays.

   Figure 7-4 Preview Window

   
   Description of "Figure 7-4 Preview Window"
   
   

7.2.2 Adding Personalization

In Section 7.2.1, "Adding Show Modes" you learned how to use the PDK Provider Framework to activate and render additional Show modes that were either not activated when creating the portlet with the wizard or not available through the wizard (such as Link and Preview modes). This section describes the two Personalization modes (Edit and Edit Defaults) in more detail. When selected in the Java Portlet Wizard, Edit page and Edit Defaults page cause the generation of skeleton code for the two Personalization modes. The skeleton code enables you to access the personalization framework with a few lines of code rather than completely hand coding a personalization framework and a data store to hold the values.To add personalization to your portlet, you need to do the following:

• Update the Edit page of your portlet to set and retrieve personalization changes.

• Update the Edit Defaults page of your portlet to set and retrieve personalization changes.

• Update the Show page of your portlets to use the personalization set by the user.

The Edit and Edit Defaults modes allow portlet users to change a set of customizable parameters supported by the portlet, which typically drive the way the portlet is rendered in other modes. For a particular instance of a portlet on an Oracle Portal page, the personalizations made in the Edit and Edit Defaults modes apply only to that instance of the portlet. This is explained as follows:

• Edit mode personalizations are specific to the individual user making the personalizations. This mode is activated by clicking the Personalize link on the portlet header in show mode.

• Edit defaults mode personalizations apply to all users in the same locale who have not yet made specific personalizations to that portlet instance. This mode is generally only available to page designers, and can be activated by following the Edit icon on the page.

When rendering Edit and Edit Defaults modes, a PortletRenderer can carry out either of the following tasks to support the personalization process:

• Render the Edit Form: For each of the portlet's customizable parameters, PortletRenderer uses a PortletPersonalizationManager to retrieve the current value and renders a control in an HTML form so the current value can be edited.

• Handle Edit Form actions: When an OK or Apply button is clicked on the standard edit form header, PortletRenderer uses a PortletPersonalizationManager to store the personalized parameters submitted by the edit form and redirects the browser to the appropriate portal page.

Therefore, the purpose of the PortletPersonalizationManager controller is to enable a PortletRenderer to store and retrieve the current values of customizable parameters that apply to a particular portlet instance and user. The PDK Framework uses the abstraction of a PersonalizationObject as a container for a set of personalized parameters and a PortletReference as the key under which a set of personalizations are stored. Thus, a PortletPersonalizationManager is simply a mechanism that allows the storage and retrieval of persisted PersonalizationObjects under a given PortletReference.

A preference store is a mechanism for storing information like user preference data, portlet/provider settings, or even portlet data, while using Oracle Portal. The information stored in the preference store is persistent in the sense that, even if you log out and log back in later, you can still access previously saved preferences. The preference store maintains the user preference information and invokes the user preferences whenever the user logs in again. PDK-Java provides the PrefStorePersonalizationManager, which uses a PreferenceStore implementation to persist personalized data. Currently, PDK-Java has two PreferenceStore implementations: DBPreferenceStore and FilePreferenceStore. The DBPreferenceStore persists data using a JDBC compatible relational database and FilePreferenceStore persists data using the file system.

For more details of these implementations, refer to the Javadoc on OTN by clicking Java Doc API on the Portlet Development page available at

http://www.oracle.com/technology/products/ias/portal/portlet_development_10g1014.html

Note:

PDK-Java provides the Preference Store Migration/Upgrade Utility to help migrate the preference store from a file system to a database and upgrade personalizations from earlier releases. This utility is described more fully on OTN.

http://www.oracle.com/technology/products/webcenter/index.html

To add personalization functionality to your portlet you use PrefStorePersonalizationManager in conjunction with NameValuePersonalizationObject, that is, the default PersonalizationObject implementation. By default, the wizard generates a simple edit form for both the Edit and Edit Defaults modes to enable users to personalize the portlet title. This section describes how to update the existing code to enable portal users to personalize the portlet greeting.

7.2.2.1 Assumptions

To perform the tasks in this section, we are making the following assumptions:

1. You have followed through and understood the following sections:

   • Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper"

   • Section 7.2.1, "Adding Show Modes"

2. You built a portlet using the wizard, with Edit page and Edit Defaults page selected, and successfully added it to a page.

7.2.2.2 Implementing Personalization for Edit and Edit Defaults Pages

The Edit page of your portlet is called when a user personalizes the portlet. By default, the JSP generated by the wizard includes all of the required code to provide personalization of the portlet title. You just need to insert a few lines of code into the Edit page for additional personalization.

7.2.2.2.1 Reviewing the Generated Code

The wizard creates the following code for you by default:

<%@page contentType="text/html; charset=windows-1252"
   import="oracle.portal.provider.v2.render.PortletRenderRequest"
   import="oracle.portal.provider.v2.http.HttpCommonConstants"
   import="oracle.portal.provider.v2.personalize.NameValuePersonalizationObject"
   import="oracle.portal.provider.v2.render.PortletRendererUtil"
%>

<%
 PortletRenderRequest pReq = (PortletRenderRequest)
   request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
%>

<P>Hello <%=pReq.getUser().getName() %>.</P>
<P>This is the <b><i>Edit</i></b> render mode!</P>
<%-- This page both displays the personalization
     form and processes it,. Display the form if
     there is no action parameter, process it
     otherwise --%>

<%
 String actionParam = PortletRendererUtil.getEditFormParameter(pReq);
 String action = request.getParameter(actionParam);
 String title = request.getParameter("my2portlet_title");
 NameValuePersonalizationObject data = (NameValuePersonalizationObject)
    PortletRendererUtil.getEditData(pReq);
 // Cancel automatically redirects to the page, so
 // will only receive OK or APPLY
 if (action !=null)
 {
    data.setPortletTitle(title);
    PortletRendererUtil.submitEditData(pReq, data);
    return;
 }

 // Otherwise just render the form.
 title = data.getPortletTitle();
%>
<table border="0">
  <td width="20%">
   <p align="right">Title:</p>
  </td>
  <td width="80%">
   <input type="TEXT" name="my2portlet_title" value="<%= title %>">
  </td>
</table>

7.2.2.2.2 Modifying the Generated Code

The JSP contains an input field for the portlet title. This field represents the Personalize page of the portlet where users can update the portlet title. To modify the generated code, perform the following steps:

1. Following the table in the generated code, add a second table containing a text field and a prompt, allowing users to enter a new greeting for the portlet:

   <table border="0">
     <tr>
       <td width="20%">
         <p align="right">Greeting:</p>
       </td>
       <td width="80%">
         <input type="TEXT" name="myportlet_greeting" value="<%= greeting %>">
       </td>
     </tr>
   </table>
   

2. This HTML simply specifies a field to enter a new greeting on the Edit page. This new greeting is displayed in the portlet's Shared Screen mode. Next, you add a string below String title that retrieves the value of the greeting:

   String title = request.getParameter("my2portlet_title");
   String greeting = request.getParameter("myportlet_greeting");
   

3. Generating an Edit page from the wizard automatically includes access to the personalization framework in the page code. At the top of the Edit page, you see the NameValuePersonalizationObject declared. This form of personalization in Oracle Portal allows easy storage of name/value pairs.

   The Edit page handles two cases: viewing the page or applying changes to it. The changes we have made so far affect the code for viewing the page. Applying changes to the Edit page is handled in the block of code beginning with if (action !=null).

   In this block of code, you must store the new portlet greeting. You must also account for the case where the user decides to make no changes and you simply retrieve the existing greeting:

   if (action !=null)
   {
        data.setPortletTitle(title);
        //Put the new greeting.
        data.putString("myportlet_greeting", greeting);
        PortletRendererUtil.submitEditData(pReq, data);
        return;
   }
   //Otherwise just render the form.
   title = data.getPortletTitle();
   //Get the old greeting.
   greeting = data.getString("myportlet_greeting");
   

You are now done updating the Edit page.

You can simply duplicate these changes for the Edit Defaults page. The Edit Defaults page is called when a page designer or portal administrator clicks Edit on the page and then clicks the Edit Defaults icon for the portlet. This page sets the default personalization for this instance of the portlet. Even though the code in the JSP is identical, the PDK Framework and Oracle Portal automatically handle the personalization differently depending on the Show mode (Edit or Edit Defaults).

7.2.2.3 Implementing Personalization for Show Pages

To have access to the personalization data in the portlet's Shared Screen mode, you need to add a few lines of code to the Show page. By adding these lines you perform the following:

• Adding import statements.

• Declaring the NameValuePersonalizationObject.

• Retrieving the personalization data.

To implement personalization of the Show page, perform the following steps:

1. Edit your Show page and import NameValuePersonalizationObject and PortletRendererUtil. You can copy these from the Edit page if necessary.

   <%@page contentType="text/html; charset=windows-1252"
      import="oracle.portal.provider.v2.render.PortletRenderRequest"
      import="oracle.portal.provider.v2.http.HttpCommonConstants"
      import="oracle.portal.provider.v2.personalize.
        NameValuePersonalizationObject"
      import="oracle.portal.provider.v2.render.PortletRendererUtil"
   %>
   

2. Declare the NameValuePersonalizationObject and retrieve the edit data from the portlet render request. You can copy this from the portlet's Edit page.

   <%
    PortletRenderRequest pReq = (PortletRenderRequest)
      request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
      NameValuePersonalizationObject data = (NameValuePersonalizationObject)
        PortletRendererUtil.getEditData(pReq);
   %>
   

3. Get the string information from the personalization framework:

   <%
   String greeting = data.getString("myportlet_greeting");
   %>
   

4. Add some text to the Show page that displays the greeting in the Shared Screen mode of the portlet.

   <P>Hello <%= pReq.getUser().getName() %>.</P>
   <P>This is the <b><i>show</i>,</b> render mode!</P>
   <P>Greeting: <%= greeting %></P>
   

You have now completed updating the Show page of the portlet.

7.2.2.4 Preference Information Within the XML Provider Definition

The Portlet Wizard generates all of the necessary tags for accessing the PreferenceStore in the XML provider definition file (provider.xml). By default, at the provider level, the wizard uses the FilePreferenceStore class to store preferences:

<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
<session>false</session>
<passAllUrlParams>false</passAllUrlParams>
<preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
     <name>prefStore1</name>
     <useHashing>true</useHashing>
</preferenceStore>

At the portlet level, tags are added to use PrefStorePersonalizationManager as the personalizationManager class and NameValuePersonalizationObject as the data class:

<personalizationManager class="oracle.portal.provider.v2.personalize.
   PrefStorePersonalizationManager">
    <dataClass>oracle.portal.provider.v2.NewValuePersonalizationObject</dataClass>
</personalizationManager>

You need not make any changes or updates to the XML Provider Definition if you choose to continue to use the FilePreferenceStore class. However, if you have a global environment for Oracle Portal (for example, you are running in a load balanced, multi-node cluster of Oracle Containers for Java EE instances) or would prefer to store preferences in the database, you can change the class from FilePreferenceStore to DBPreferenceStore.

For more information on using DBPreferenceStore, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

7.2.2.5 Viewing the Portlet

To view the personalization changes you made in the preceding sections, you need to deploy the portlet to your application server or Oracle Containers for Java EE and refresh the page containing your portlet. For more information on deploying your portlet, refer to Section 6.5.4, "Deploying Your Oracle PDK-Java Portlet to an Application Server".

You should now see that the portlet contains a null greeting. Click Personalize in the portlet title bar and update the greeting. When you return to the page, you should see your changes.

You can also test Edit Defaults by clicking Edit on the page and then clicking the Edit Defaults icon. Since you have already modified the portlet, the changes will not appear to you in Shared Screen mode unless you view the page as a public user or a different user.

7.2.3 Passing Parameters and Submitting Events

Oracle Portal and the PDK provide page parameters, public and private portlet parameters, and events to enable portlet developers to easily write reusable, complex portlets. The Portlet Wizard in Oracle JDeveloper creates portlets that are already set up to use parameters and events. This feature enables you to focus solely on adding business logic to your portlets and does not require any changes to provider.xml.

For an overview of parameters and events, refer to the following:

• Section 2.12, "Public Portlet Parameters Support"

• Section 2.13, "Private Portlet Parameter Support"

• Section 2.14, "Event Support"

7.2.3.1 Assumptions

To perform the tasks in this section, the following assumptions are made:

1. You have followed through and understood Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper".

2. You built a portlet using the wizard and successfully added it to a page.

Note:

Each portlet is limited to 4K of data. The lengths of parameter and event names, display names, and descriptions all contribute toward this 4K limit. Hence, you should not use an excessive number of parameters and events for each portlet, or give them lengthy names and descriptions.

7.2.3.2 Adding Public Parameters

Using the wizard in Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper", you built a basic portlet and specified a parameter called MyParam. If you did not create a parameter, you can create a new portlet now by right clicking on provider.xml in the Applications - Navigator of Oracle JDeveloper, selecting Add Portlet, and following the steps in Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper".

By default, the wizard creates a portlet to which you can easily map page parameters without updating any code or files. In this section, you will use the default parameter created for you by the wizard.

To use the default parameter, you need only register the provider and add the portlet to a page. After that, you perform the following tasks:

• Create a page parameter.

• Wire the page parameter to your Java portlet.

• Enter parameter values in the URL or another portlet that passes this page parameter.

To add parameters to your portlet:

1. Go to the Parameter tab of the page properties. Note that parameters should be enabled by default, but, if not, you must enable them before proceeding.

2. Create a page parameter called MyParameter with a default value of My Default Value.

3. Expand your Java portlet and map the page parameter you just created to the portlet parameter. The portlet's parameter should map to the page parameter called MyParameter.

4. Go back to the page. Notice that, in the portlet, a value of My Default Value appears.

5. View the page and enter the parameter and a value at the end of the URL:

   &MyParameter=This%20portlet%20works
   

   Figure 7-5 shows an example of a parameter portlet.

   Figure 7-5 Parameter Portlet

   
   Description of "Figure 7-5 Parameter Portlet"
   
   

If you have a portlet, such as the Simple Parameter Form included with OmniPortlet, that can pass parameters, you can map parameters from that portlet to your Java portlet using the Events tab.

If you now take a look at the code and tags generated by the wizard, you see that very little code was needed to enable parameters in the Java portlet.

Review provider.xml. Note that the wizard added one tag group called inputParameter, which includes the name of the parameter for which the portlet listens.

<inputParameter class="oracle.portal.provider.v2.DefaultParameterDefinition">
  <name>MyParam</name>
  <displayName>My Portlet Parameter</displayName>
</inputParameter>

For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

The wizard also generated code in the JSP for your Show page that receives this parameter, and displays the parameter name and its value.

<% 
ParameterDefinition params[] = 
  pReq.GetPortletDefinition().getInputParameters();
%>

<p>This portlets input parameters are ...</p>
<table align="left" width="50%"><tr><td><span class="PortletHeading1">Value
  </span></td></tr>
<%
  String name = null;
  String value = null;
  String[] values = null;
for (int i = 0; i < params.length; i++)
{
  name = params[i].getName();
  values = pReq.getParameterValues(name);
  if (values != null)
  {
   StringBuffer temp = new StringBuffer();
   for (int j = 0; j < params.length; j++)
    {
       temp.append(values[j]);
       if (j + 1 != values.length)
       {
         temp.append(", ");
       }
    }
    value = temp.toString();
  }
  else
  {
    value = "No values submitted yet.";
  }
%>
<tr>
  <td><span class="PortletText2" <%= name %></span></td>
  <td><span class="PortletText2" <%= value %></span></td>
</tr>
<%
}
%>
</table>

7.2.3.3 Passing Private Portlet Parameters

Parameters that are used within a single portlet are known as private parameters. They are visible to a single portlet instance only. Portlet parameters are created and accessed using PDK-Java APIs described in this section. Parameter names are qualified so that it will be correctly handled by the portlet consumer. The following API will do this:

HttpPortletRendererUtil.portletParameter(HttpServletRequest request, String param);

HttpPortletRendererUtil is in the package oracle.portal.provider.v2.render.http.

For example:

qualParamQ = HttpPortletRendererUtil.portletParameter(r, "q");

To fetch the value of a portlet parameter from the incoming request, you can use the following API:

Note:

The API converts the parameter name into the qualified parameter name before fetching the value from the incoming request. Hence, you need not perform this step.

PortletRenderRequest.getQualifiedParameter(String name);

PortletRenderRequest is in the package oracle.portal.provider.v2.render.

For example:

valueQ = r.getQualifiedParameter("q");

The utilities for using private parameters are discussed in Section 7.2.3.3.2, "Building Links with the Portlet URL Types" and Section 7.2.3.3.3, "Building Forms with the Portlet URL Types."

7.2.3.3.1 Portlet URL Types

Intraportlet links refer to the Oracle Portal page on which the portlet resides, and that portlet is most likely running remotely from Oracle Portal. Hence, you must consider how the portlet can render a link to the correct page without some knowledge of the Oracle Portal page's URL. For more information about the types of links used by portlets, refer to Section 6.1.2, "Guidelines for Navigation within a Portlet".

When Oracle Portal requests that a portlet render itself, Oracle Portal passes it various URLs, which the portlet can then use to render links, including any intraportlet links it requires. You can fetch and manipulate these URLs to simplify the task of creating links among portlets and pages in Oracle Portal.

Oracle Portal provides the following URLs to its portlets:

• PAGE_LINK is a URL to the page upon which the portlet instance resides. You use this URL as the basis for all intraportlet links. If the portlet renders a link that navigates the user to another section of the same portlet, then this navigation must be encoded as a set of parameters using the PAGE_LINK. This URL is useful to both desktop and mobile portlets.

• DESIGN_LINK is a URL to an Oracle Portal page that represents the portlet's personalization page. In Oracle Portal, a portlet's Edit and Customize modes are not rendered on the same page as the portlet. The Edit and Customize modes take over the entire browser window. Oracle Portal's portlet edit/customize page is not accessible to every user. It represents a minimal, static framework in which the portlet is free to render its personalization or edit options. This URL is only of use when rendering edit and customize links, which themselves are only supported in desktop clients.

• LOGIN_LINK is a URL to OracleAS Single Sign-On Server, should the portlet need to prompt the user (if PUBLIC) to login. This link is rarely used and only applicable to the desktop rendering of portlets.

• BACK_LINK is a URL to a page that Oracle Portal considers a useful return point from the current page where the portlet renders itself. For example, when the portlet is rendering it's Edit page, this link refers to the page on which the portlet resides and from which the user navigated to the Edit page. Consequently, it is the link you would encode in the buttons that accept or cancel the pending action. This URL is only useful for the desktop rendering of portlets (usually in Edit or Customize mode). Mobile portlets render a Back link automatically leaving the portlet to render just it's own content.

• EVENT_LINK is a URL that raises an event rather than explicitly navigate to some page. This link points to the Oracle Portal entry point to the event manager. This URL is useful to both desktop and mobile portlets.

7.2.3.3.2 Building Links with the Portlet URL Types

To build links with the URL parameters, you need to access them and use them when writing portlet rendering code. To fetch the URL for a link, you call the following APIs in the PDK:

portletRenderRequest.getRenderContext().getPageURL()
portletRenderRequest.getRenderContext().getEventURL()
portletRenderRequest.getRenderContext().getDesignURL()
portletRenderRequest.getRenderContext().getLoginServerURL()
portletRenderRequest.getRenderContext().getBackURL()

In the case of portlet navigation, you need to add (or update) your portlet's parameters in the page URL. To perform this task, you can use the following API to build a suitable URL:

UrlUtils.constructLink(
    PortletRenderRequest pr,
    int linkType, -- UrlUtils.PAGE_LINK in this case
    NameValue[] params,
    boolean encodeParams,
    boolean replaceParams)

UrlUtils resides in the package called oracle.portal.provider.v2.url. Notice that you do not actually fetch the page URL yourself. Rather you use one of the supplied portlet URL types, UrlUtils.PAGE_LINK.

The parameter names in the params argument should be fully qualified. Moreover, assuming that you properly qualify the parameters, UrlUtils.constructLink with the appropriate linkType does not disturb other URL parameters that are not owned by the portlet.

An alternative version of UrlUtils.contructLink accepts a URL as the basis for the returned URL. If you require an HTML link, you can use UrlUtils.constructHTMLLink to produce a complete anchor element.

The following example portlet, ThesaurusLink.jsp, uses the parameter q to identify the word for which to search the thesaurus. It then creates links on the found, related words that the user may follow in order to get the thesaurus to operate on that new word. Refer to the example in Section 7.2.3.3.3, "Building Forms with the Portlet URL Types" to see the initial submission form that sets the value of q.

Note:

When rendering attributes in SimpleResult (for a mobile portlet), you must escape the attribute value if it is likely to contain invalid XML characters. Most URLs contain & to separate the URL's parameters. Hence, you usually need to escape attributes that contain URLs with:

oracle.portal.utils.xml.v2.XMLUtil.escapeXMLAttribute

<%
    String paramNameQ = "q";
    String qualParamNameQ = 
    HttpPortletRendererUtil.portletParameter(paramNameQ);
    PortletRenderRequest pRequest = (PortletRenderRequest)
        request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String paramValueQ = pRequest.getQualifiedParameter(paramNameQ);
%>
<!-- Output the HTML content -->
<center>
    Words similar to <%= paramValueQ %>
    <br>
    Click on the link to search for words related to that word.
    <br>
    <ul>
<%
        String[] relatedWords = Thesaurus.getRelatedWords(paramValueQ);
        NameValue[] linkParams = new NameValue[1]; 
        for (int i=0; i<=relatedWords.length; i++)
        {
            linkParams[0] = new NameValue(
                qualParamNameQ, relatedWords[i]);
%>
            <li>
            <b> <%= relatedWords[i] %> </b>
            <%= UrlUtils.constructHTMLLink(
                pRequest,
                UrlUtils.PAGE_LINK,
                "(words related to " + relatedWords[i] + ")",
                "",
                linkParams,
                true,
                true)%>
           </li>
<%
        }
%>
   </ul>
</center>

7.2.3.3.3 Building Forms with the Portlet URL Types

Use of portlet parameters in forms is little different from links. The following two fundamental rules continue to apply:

• Qualify the portlet's parameter names.

• Do not manipulate or remove the other parameters on the incoming URL.

In terms of markup and behavior, forms and links differ quite considerably. However, just as with links, PDK-Java contains utilities for complying with these two basic rules.

The code for properly qualifying the portlet's parameter name is the same as described in Section 7.2.3.3.2, "Building Links with the Portlet URL Types". After all, a parameter name is just a string, whether it be a link on a page or the name of a form element.

Forms differ from links in the way you ensure that the other parameters in the URL remain untouched. Once you open the form in the markup, you can make use of one of the following APIs:

UrlUtils.htmlFormHiddenFields(pRequest,UrlUtils.PAGE_LINK, formName);
UrlUtils.htmlFormHiddenFields(someURL);

where formName = UrlUtils.htmlFormName(pRequest,null).

Note:

Just as parameters in URLs and element names in forms require qualification to avoid clashing with other portlets on the page, form names must be fully qualified because any given page might have several forms on it.

The htmlFormHiddenFields utility writes HTML hidden form elements into the form, one form element for each parameter on the specified URL that is not owned by the portlet.

<INPUT TYPE="hidden" name="paramName" value="paramValue">

Thus, the developer needs only to add their portlet's parameters to the form.

The other item of which you need to be aware is how to derive the submission target of your form. In most cases, the submission target is the current page:

formTarget = UrlUtils.htmlFormActionLink(pRequest,UrlUtils.PAGE_LINK)

The value of formTarget can be the action attribute in an HTML form or the target attribute in a SimpleForm. Even though the method name includes HTML, it actually just returns a URL and thus you can use it in mobile portlets, too.

The following example form renders the thesaurus portlet's submission form. Refer to the example in Section 7.2.3.3.2, "Building Links with the Portlet URL Types" for the portlet that results from the submission of this form.

<%
    String paramNameSubmit = "submit";
    String paramNameQ = "q";
    String qualParamNameQ =
        HttpPortletRendererUtil.portletParameter(paramNameQ);
    String qualParamNameSubmit = 
    HttpPortletRendererUtil.portletParameter(paramNameSubmit);
    PortletRenderRequest pRequest = (PortletRenderRequest)
        request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String formName = UrlUtils.htmlFormName(pRequest,"query_form");
%>
<!-- Output the HTML content -->
<center>
    <b>Thesaurus</b>
    Enter the word you wish to search for
    <form name="<%= formName %>" method="POST" 
        action="<%= UrlUtils.htmlFormActionLink(pRequest,UrlUtils.PAGE_LINK) %>"> 
        <%= UrlUtils.htmlFormHiddenFields(pRequest,UrlUtils.PAGE_LINK, formName)%> 
        <table><tr><td>
            Word of interest:
        </td><td>
            <input
                type="text"
                size="20"
                name="<%= qualParamNameQ %>"
                value="">
        </td></tr></table>
        <input type=submit name="<%= qualParamNameSubmit %>" Value="Search">
    </form>
</center>

7.2.3.3.4 Implementing Navigation within a Portlet

You can implement navigation within a portlet in one of three ways, as follows:

• Pass navigation information in rendered URLs using explicit portlet parameters. Branching logic within the portlet code then determines which section of the portlet to render based on the URL. This option represents a small extension to the thesaurus example presented in Section 7.2.3.3.2, "Building Links with the Portlet URL Types" and Section 7.2.3.3.3, "Building Forms with the Portlet URL Types". Basically, instead of performing thesaurus search operations using the value of parameter q, the portlet branches based on the parameter value and renders different content accordingly.

• Pass navigation information as described in the previous item but use PDK-Java to interpret the parameter and thus branch on its value. This option requires some further changes to the thesaurus example and is more fully explained subsequently.

• Use session storage to record the portlet state and URL parameters to represent actions rather than explicit navigation. This method provides the only way that you can restore the portlet to it's previous state when the user navigates off the page containing the portlet. Once the user leaves the page, all portlet parameters are lost and you can only restore the state from session storage, assuming you previously stored it there. This option requires that you understand and implement session storage. Refer to Section 7.2.6.2, "Implementing Session Storage" for more information about implementing session storage.

The following portlet code comes from the multi-page example in the sample provider of PDK-Java:

<portlet>
    <id>11</id> 
    <name>Multipage</name> 
    <title>MultiPage Sample</title> 
    <shortTitle>MultiPage</shortTitle> 
    <description>
        This portlet depicts switching between two screens all 
        in the context of a Portal page.
    </description> 
    <timeout>40</timeout> 
    <timeoutMessage>MultiPage Sample timed out</timeoutMessage> 
    <renderer class="oracle.portal.provider.v2.render.RenderManager">
        <contentType>text/html</contentType> 
        <showPage>/htdocs/multipage/first.jsp</showPage> 
        <pageParameterName>next_page</pageParameterName> 
    </renderer>
</portlet>

Notice that the value of pageParameterName is the name of a portlet parameter, next_page, that the PDK framework intercepts and interprets as an override to the value of the showPage parameter. If the PDK framework encounters the qualified version of the parameter when the multi-page portlet is requested, it will render the resource identified by next_page rather than first.jsp. Note that the PDK does not render the parameter within the portlet, that responsibility falls to the portlet.

You can modify the thesaurus example to operate with the use of this parameter. Specifically, you can use the form submission portlet to be the input for the thesaurus (the first page of the portlet), then navigate the user to the results page, which contains links to drill further into the thesaurus. The following examples illustrate these changes.

Note:

The example that follows is most useful for relatively simple cases, such as this thesaurus example. If your requirements are more complex (for example, you want to build a wizard experience), then you should consider using an MVC framework such as Struts. For information on how to build portlets from struts applications, refer to Section 7.3, "Building Struts Portlets with Oracle JDeveloper".

ThesaurusForm.jsp:

<%
    PortletRenderRequest pRequest = (PortletRenderRequest)
        request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String paramNameSubmit = "submit";
    String paramNameQ = "q";
    String qualParamNameQ =
        HttpPortletRendererUtil.portletParameter(pRequest, paramNameQ);
    String qualParamNameSubmit = 
    HttpPortletRendererUtil.portletParameter(pRequest, paramNameSubmit);
    String formName = UrlUtils.htmlFormName(pRequest,"query_form");
%>
<!-- Output the HTML content -->
<center>
    <b>Thesaurus</b>
    Enter the word you wish to search for
    <form name="<%= formName %>" method="POST" 
        action="<%= UrlUtils.htmlFormActionLink(pRequest,UrlUtils.PAGE_LINK) %>"> 
        <%= UrlUtils.htmlFormHiddenFields(pRequest,UrlUtils.PAGE_LINK, formName)
%> 
        <%= UrlUtils.emitHiddenField(
                HttpPortletRendererUtil.portletParameter(request, "next_page"),
                "htdocs/path/ThesaurusLink.jsp" ) %>
        <table><tr><td>
            Word of interest:
        </td><td>
            <input
                type="text"
                size="20"
                name="<%= qualParamNameQ %>"
                value="">
        </td></tr></table>
        <input type=submit name="<%= qualParamNameSubmit %>" Value="Search">
    </form>
</center>

Notice how next_page must be explicitly set to point to ThesaurusLink.jsp. If you do not explicitly set next_page in this way, it defaults to the resource registered in provider.xml, which is ThesaurusForm.jsp.

ThesaurusLink.jsp:

<%
    PortletRenderRequest pRequest = (PortletRenderRequest)
        request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String paramNameQ = "q";
    String paramNameNextPage = "next_page";
    String qualParamNameQ = 
    HttpPortletRendererUtil.portletParameter(pRequest, paramNameQ);
    String qualParamNameNextPage = 
        HttpPortletRendererUtil.portletParameter(pRequest, paramNameNextPage);
    String paramValueQ = pRequest.getQualifiedParameter(paramNameQ);
%>
<!-- Output the HTML content -->
<center>
    Words similar to <%= paramValueQ %>
    <br>
    Click on the link to search for words related to that word.
    <br>
    <ul>
<%
        Thesaurus t = new Thesaurus();
        String[] relatedWords = t.getRelatedWords(paramValueQ);
        NameValue[] linkParams = new NameValue[2]; 
        linkParams[0] = new NameValue(
            qualParamNameNextPage, "htdocs/path/ThesaurusLink.jsp");
        for (int i=0; i<relatedWords.length; i++)
        {
            linkParams[1] = new NameValue(
                qualParamNameQ, relatedWords[i]);
%>
            <li>
            <b> <%= relatedWords[i] %> </b>
            <%= UrlUtils.constructHTMLLink(
                pRequest,
                UrlUtils.PAGE_LINK,
                "(words related to " + relatedWords[i] + ")",
                "",
                linkParams,
                true,
                true)%>
           </li>
<%
        }
%>
   </ul>
   <a href="<%=XMLUtil.escapeXMLAttribute
               (pRequest.getRenderContext().getPageURL())%>">
      Reset Portlet
   </a>
</center>

Partial Page Refresh

Portlets can refresh themselves without refreshing the entire page. For example, in the multi-page portlet sample, firstpage.jsp uses the API to specifically enable the portlet to link to and display the second page without refreshing the entire portal page. The text in bold in the following example shows how this can be set:

<%@ page contentType="text/html;charset=UTF-8" %>
<%@ page language="java" session="false" %>
<%@ page import="oracle.portal.provider.v2.url.UrlUtils" %>
<%@ page import="oracle.portal.provider.v2.render.http.HttpPortletRendererUtil" %>
<%@ page import="oracle.portal.provider.v2.render.PortletRenderRequest" %>
<%@ page import="oracle.portal.provider.v2.http.HttpCommonConstants" %>
<%@ page import="oracle.portal.utils.NameValue" %>
<%
PortletRenderRequest prr = (PortletRenderRequest)
request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);

NameValue[] linkParams = new NameValue[1];
linkParams[0] = new NameValue(HttpPortletRendererUtil.portletParameter(request,
"next_page"), "/htdocs/multipage/second.jsp");
%>

<center>
Hello, this is the first page<p>
<%=UrlUtils.constructHTMLLink(prr, UrlUtils.REFRESH_LINK, "second page", "", linkParams, true, true)%>
</center>

7.2.3.4 Submitting Events

In the previous section, you created a portlet that received parameters. Now you will create a portlet that passes parameters and events to other portlets on the same page or a different page. Some portlets, like the Simple Parameter Form in OmniPortlet, provide an easy, declarative interface to create a simple form to pass parameters to other portlets. If you want complete control over the events passed and the look of your portlet, though, you can add events to your Java portlet.

The Portlet Wizard does not create all of the code needed to pass parameters to other portlets. The wizard updates the tags in provider.xml and requires that you add the necessary business logic to your JSP code. To create a portlet that uses events, you perform the following tasks:

• Create a new portlet with the Portlet Wizard.

• Add code to your JSP page.

• Map this portlet's parameters to the portlet you created in Section 7.2.3.2, "Adding Public Parameters".

Creating an Events Portlet

To create an events portlet, perform the following steps:

1. Create a new portlet called MyEventsPortlet in the same provider you used for the parameter portlet in Section 7.2.3.2, "Adding Public Parameters"by invoking the Portlet Wizard (Figure 7-6). Go through the wizard as normal. In step 5 of the wizard, create a parameter. In step 6 of the wizard, enter the information shown in Table 7-1.

   Table 7-1 Events

   Events Area	Name	Display Name	Description
   Events Exposed	MyEvent	My Event	This is my event.
   Parameters Associated	MyParam	My Parameter	This is my parameter

   
   

   Figure 7-6 Public Portlet Events Page of Portlet Wizard

   
   Description of "Figure 7-6 Public Portlet Events Page of Portlet Wizard"
   
   

   The wizard generates the following code in provider.xml:

   Note:

   In the following example, notice that the input parameter and the event parameter have the same name, MyParam. They are two different parameters, even though they have the same name.

   <showDetails>false</showDetails>
   <inputParameter class="oracle.portal.provider.v2.
     DefaultParameterDefinition">
      <name>MyParam</name>
      <displayName>My Parameter</displayName>
   </inputParameter>
   <event class="oracle.portal.provider.v2.DefaultEventDefinition">
      <name>MyEvent</name>
      <displayName>My Event</displayName>
      <parameter class="oracle.portal.provider.v2.DefaultParameterDefinition">
        <name>MyParam</name>
        <displayName>My Parameter</displayName>
      </parameter>
   </event>
   <renderer class="oracle.portal.provider.v2.render.RenderManager">
   

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

2. Import the following necessary classes into MyEventsPortlet:

   • oracle.portal.provider.v2.event.EventUtils

   • oracle.portal.utils.NameValue

   • oracle.portal.provider.v2.url.UrlUtils

3. In MyEventsPortlet, add a link that passes the parameter value to another portlet. As shown in the following sample code, you receive the same page parameter as the previous portlet, but in addition you create a link that passes an event as well:

   <%@page contentType="text/html; charset=windows-1252"
   import="oracle.portal.provider.v2.render.PortletRenderRequest"
   import="oracle.portal.provider.v2.http.HttpCommonConstants"
   import="oracle.portal.provider.v2.ParameterDefinition"
   import="oracle.portal.provider.v2.event.EventUtils"
   import="oracle.portal.utils.NameValue"
   import="oracle.portal.provider.v2.url.UrlUtils"
   %>
   <%
   PortletRenderRequest pReq = (PortletRenderRequest)
   request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
   %>
   <% 
     NameValue[] parameters = new NameValue[2];
     parameters[0] = new NameValue( EventUtils.eventName("MyEvent"),"");
     parameters[1] = new
   NameValue(EventUtils.eventParameter("MyParam"),pReq.getParameter
     ("MyParam"));
   %>   
   <span class="portletText1"><br>
   
   <a href="<%= UrlUtils.constructLink
     (pReq, pReq.getRenderContext().getEventURL(), parameters , true, true)%>">
   The value of the stock is <%= pReq.getParameter("MyParam") %>
   </a>
   <br><br></span>
   

   Note:

   This sample code does not handle NULL values. When the portlet is initially added to the page, you may receive an error, but, after wiring the portlet to the page parameter, it should work fine.

4. Add the portlet to a different page (in the same page group) than the previous portlet (the Parameter Portlet). Expand the portlet and wire it to receive the same parameter as the previous portlet.

   My Parameter = Page Parameter MyParameter
   

5. Apply your changes on the Parameter tab and go to the Events tab. Expand the Event portlet and select the event. Select Go to Page and find the page to which you want to pass the event. Choose the page where the Parameter portlet is located. Configure this portlet to pass an event as the page parameter MyParameter as shown in Figure 7-7.

   MyParameter = Event Output MyParameter 
   

   Figure 7-7 Portlet Events in the Edit Page

   
   Description of "Figure 7-7 Portlet Events in the Edit Page"
   
   

6. Click OK to view the page. Your Event portlet should have a link that displays the value received from the page (Figure 7-8).

   Figure 7-8 My Event Portlet Before Parameter Change

   
   Description of "Figure 7-8 My Event Portlet Before Parameter Change"
   
   

7. You can append a parameter value to the URL and the portlet displays the value in the link.

   &MyParameter=20
   

8. When you click the link, that value is passed to the Parameter portlet on its page (Figure 7-9).

   Figure 7-9 My Event Portlet After Parameter Change

   
   Description of "Figure 7-9 My Event Portlet After Parameter Change"
   
   

7.2.4 Using JNDI Variables

When writing Java portlets, you may set deployment specific properties through the JNDI service such that their values may be retrieved from your provider code. In this way, you can specify any property in a provider deployment and then easily access it anywhere in your provider code. PDK-Java provides utilities to enable the retrieval of both provider and non-provider JNDI variables within a J2EE container. To use JNDI variables, you need to perform the following tasks:

• Section 7.2.4.1, "Declaring JNDI Variables"

• Section 7.2.4.2, "Setting JNDI Variable Values"

• Section 7.2.4.3, "Retrieving JNDI Variables"

7.2.4.1 Declaring JNDI Variables

You declare JNDI variables in the web.xml file for your provider. The format for declaring a JNDI variable is as follows:

<env-entry>
    <env-entry-name>variableName</env-entry-name>
    <env-entry-type>variableType</env-entry-type>
    <env-entry-value>variableValue</env-entry-value> 
</env-entry>

The env-entry-name element contains the name by which you want identify the variable. env-entry-type contains the fully qualified Java type of the variable. env-entry-value contains the variable's default value.

7.2.4.1.1 Variable Types

In the env-entry-type element, you should supply the fully-qualified Java type of the variable, which will be expected by your Java code. The Java types you may use in your JNDI variables are as follows:

• java.lang.Boolean

• java.lang.String

• java.lang.Integer

• java.lang.Double

• java.lang.Float

The J2EE container uses these type declarations to automatically construct an object of the specified type and gives it the specified value when you retrieve that variable in your code.

7.2.4.1.2 Variable Naming Conventions

The PDK-Java defines a number of environment variables that can be set at the individual provider service level or at the Web application level. To avoid naming conflicts between different provider services or different application components packaged in the same Web application, we recommend you devise some naming convention.

Note:

If you use the EnvLookup method, you must use oracle/portal/provider/service/property. You cannot substitute your own company name or component in this case.

For example:

• Provider service specific names should be of the form:

  {company}/{component name}/{provider name}/{variable name}
  

• Shared names should be of the form:

  {company}/{component name}/{provider name}/global
  

where:

• {company} is the name of the company owning the application.

• {component name} is the name of the application or component with which the provider is associated.

• {provider name} is the service name of the provider.

• {variable name} is the name of the variable itself.

As you can see, these naming conventions are similar to those used for Java packages. This approach minimizes the chance of name collisions between applications or application components. PDK-Java provides utilities that allow you to retrieve variables in this form without hard coding the service name of the provider into your servlets or JSPs. The service name need only be defined in the provider's WAR file. Refer to Section 7.2.4.3, "Retrieving JNDI Variables" for more information on retrieving JNDI variables.

7.2.4.1.3 Examples

The following examples illustrate provider variable names:

oracle/portal/myProvider/myDeploymentProperty
oracle/portal/myprovider/myProperties/myProperty

The following example illustrates non-provider variable names:

oracle/portal/myOtherProperty

7.2.4.2 Setting JNDI Variable Values

In your provider deployment, you may want to set a new value for some or all of your JNDI variables. You can perform this task by setting the values manually in a Oracle WebLogic Server deployment plan as follows:

1. Go to the provider deployment in the Oracle WebLogic Administration Console, and create a new Deployment Plan if one hasn't been set against it.

2. Edit the Deployment Plan XML file. For each deployment property you want to set, add the following variable definition directly under the <deployment-plan> tag:

   <variable-definition>
         <variable>
           <name>jndi_var_def</name>
           <value>false</value>
         </variable>
       </variable-definition>
   

3. To tie this variable definition to and actual JNDI variable that you want to set, do the following for each property under the WEB-INF/web.xml module descriptor (oracle/portal/sample/rootDirectory is used as an example):

   <module-descriptor external="false">
         <root-element>web-app</root-element>
         <uri>WEB-INF/web.xml</uri>
         <variable-assignment>
           <name>jndi_var_def</name>        <xpath>/web-app/env-entry/[env-entry-name=&quot;oracle/portal/sample/rootDirectory&quot;]/env-entry-value</xpath>
         </variable-assignment>
       </module-descriptor>
   

4. Save the file.

5. Select 'Update' on the provider deployment to apply the Deployment Plan for the new settings to take effect.

7.2.4.3 Retrieving JNDI Variables

JNDI is a standard J2EE technology. As such, you can access JNDI variables through J2EE APIs. For example:

String myVarName = "oracle/portal/myProvider/myVar"
String myVar = null;
try 
{
   InitialContext ic = new InitialContext();
   myVar = (String)ic.lookup("java:env/" + myVarName);
}
catch(NamingException ne)
{
   exception handling logic
}

In addition to the basic J2EE APIs, PDK-Java includes a simple utility class for retrieving the values of variables defined and used by the PDK itself. These variables all conform to the naming convention described in Section 7.2.4.1.2, "Variable Naming Conventions" and are of the form:

oracle/portal/provider_service_name/variable_name
oracle/portal/variable_name

To use these APIs, you need only provide the provider_service_name and the variable_name. The utilities construct the full JNDI variable name, based on the information you provide, and look up the variable using code similar to that shown earlier and return the value of the variable.

The EnvLookup class (oracle.portal.utils.EnvLookup) provides two lookup() methods. One retrieves provider variables and the other retrieves non-provider variables. Both methods return a java.lang.Object, which can be cast to the Java type you are expecting.

The following code example illustrates the retrieval of a provider variable:

EnvLookup el = new EnvLookup();
String s = (String)el.lookup(myProviderName, myVariableName);

myProviderName represents the service name for your provider, which makes up part of the variable name. myVariableName represents the portion of the variable name that would come after the provider's service name. The example assumes the variable being retrieved is of type java.lang.String.

To retrieve a non-provider variable, you use the same code, you pass only one parameter, the variable name, to the lookup(), again excluding the oracle/portal prefix.

EnvLookup el = new EnvLookup();Object o = el.lookup(myVariableName);

Table 7-2 shows the JNDI variables provided by default with PDK-Java. If you do not declare these variables, PDK-Java looks for their values in their original locations (web.xml and the deployment properties file).

Table 7-2 PDK-Java JNDI Variables

Variable	Description
oracle/portal/provider/provider_name/autoReload	Boolean auto reload flag. Defaults to true.
oracle/portal/provider/provider_name/definition	Location of provider's definition file.
oracle/portal/provider/global/log/logLevel	Log setting (0 through 8). 0 being no logging and 8 the most possible logging.
oracle/portal/provider/provider_name/maxTimeDifference	Provider's HMAC time difference.
oracle/portal/provider/<service_name>/resourceUrlKey	Authentication key for resource proxying through the Parallel Page Engine. Refer to Oracle Fusion Middleware Administrator's Guide for Oracle Portal for more information.
oracle/portal/provider/provider_name/rootDirectory	Location for provider personalizations. No default value.
oracle/portal/provider/provider_name/sharedKey	HMAC shared key. No default value.
oracle/portal/provider/provider_name/showTestPage	(non-provider) A boolean flag that determines if a provider's test page is accessible. Defaults to true.
oracle/portal/provider/global/transportEnabled	A boolean flag that determines whether Edit Defaults personalizations may be exported and imported. Refer to Section 7.2.8.3.2, "Disabling Export/Import of Personalizations" for more information.

7.2.5 Creating Private Events

In some cases, it is useful for a portlet to complete a transaction before rendering a page on which it resides rather than having the transaction and the rendering executed simultaneously. For example, suppose a portlet has a link that initiates an update of some data value that might effect other portlets on the page. If the transaction takes place simultaneously with a refresh of the page, other portlets that rely on that data value may or may not be refreshed with the latest value. Furthermore, when transactions and rendering are tied together in this way, an action such as the user hitting Back in their browser could cause the transaction to be repeated, perhaps creating a duplicate record.

In JPS portlets, this situation is solved using the processAction method, which allows an individual portlet to complete a transaction, such as updating a value, before allowing the page rendering to take place. PDK-Java does not have processAction, but you can achieve the same results by submitting data to your servlet through a different mechanism. If you are using Struts for the page flow and control of a portlet, you could use the form tag and transaction tokens to avoid submitting the same parameter twice. Refer to Section 7.3, "Building Struts Portlets with Oracle JDeveloper" for more information about Struts portlets.

Another possibility is to submit data through Edit mode rather than Shared Screen mode. Requests based on full page Show modes, such as Edit mode, are sent only to the portlet that generated the link. Other portlets on the same portal page never even see a render request. Hence, these full page Show modes provide you with the capability to execute a transaction for a portlet separately from the page and its other portlets.

Once you have processed the portlet's submission, you redirect from the full page Show mode back to the page using the back URL. This action has two desirable effects, as follows:

• It returns the user to the page from which they came.

• It clears all traces of the form submission from the browser.

As a result, any refreshing of the page is guaranteed to occur after the processing of the data submission. Because the page refresh comes after the submission you can be sure that all portlets on the page will access the updated data and not cause a duplicate submission.

This technique is illustrated by a sample portlet in the PDK called the private event submission portlet. It demonstrates submitting a simple form to the portlet and logging the contents of the form. In the private event submission portlet, we overload Edit mode to handle both the data submission and the portlet's rendering for personalizations. Note that any of the other full page Show modes (Edit, Help, About, and Edit Defaults) would be equally effective for this purpose.

Edit mode for this portlet includes additional code that first looks for a specific parameter. If this parameter is present, it means that the request represents a private event. The same mode can handle many different private events by using different values for the distinguishing parameter. If the distinguishing parameter does not exist, then Edit mode falls through to the standard portlet personalization logic.

After handling the private event, this mode redirects to the page using exactly the same logic that Edit mode uses when a user clicks OK. Refer to EditServlet.java in the sample files for the complete source code illustrating this technique.

Note:

When you use this technique, you must take care that the details of your event are persisted somewhere. Since portlet rendering does not happen in the same request cycle as the event processing, any data from the event required to render the portlet must be available from storage. Otherwise, the portlet or the page may lack the data it requires the next time it is rendered.

If you need to persist your data, be sure to store it in a qualified manner (by the user and portlet reference). Otherwise, you may accidentally associate an event from one user/portlet with the rendering of the same portlet for another user on a different page, or even associate the same user/same portlet with a different portlet reference on the same page.

7.2.6 Accessing Session Information

When a user accesses any portal page, Oracle Portal initiates a public unauthenticated session and maintains a cookie to track information about the session across requests. If the user logs in to Oracle Portal, this session becomes an authenticated session of the logged-in user. This portal session terminates when the any of the following occur:

• The browser session terminates (that is, the user closes all the browser windows).

• The user explicitly logs out.

• The session times out because the user's idle time exceeds the configured limit.

As part of the metadata generation, Oracle Portal contacts all of the providers that contribute portlets to the page, if they specify during registration that they get called for some special processing. This call allows providers to do processing based on the user session, log the user in the provider's application if needed, and establish provider sessions in Oracle Portal. For Database providers, this call is referred to as do_login and for Web providers it is initSession. Since most Web-enabled applications track sessions using cookies, this API call allows the provider of the application to return cookies.

You can utilize the session store to save and retrieve information that persists during the portal session. This information is only available, and useful, to you during the life of the session. You should store only temporary information in the session store. Application developers may use the session store to save information related to the current user session. Data in the session store can be shared across portlets.

If the information you want to store must persist across sessions, you may want to store it in the preference store instead. Some common applications of the session store are as follows:

• to cache data that is expensive to load or calculate (for example, search results).

• to cache the current state of a portlet (for example, the current range, or page, of search results displayed in the portlet, or sequence of events performed by user).

Before you implement session storage, you should carefully consider the performance costs. Because portlets and providers are remote, it can be a relatively expensive operation to create and maintain even a small amount of information in the session store. For this reason, you may want to avoid altogether any session storage for public pages that are accessed frequently by many users.

If scalability is an important concern for you, a stateful application may cause you problems. Stateful applications can impact the load-balancing and failover mechanism for your Oracle Portal configuration. Even though you may deploy multiple middle-tiers accessing the same Oracle Portal instance, you must implement sticky routing (where the same node handles subsequent requests in the same session) to track state. Sticky routing may result in lopsided load-balancing or loss of session data in case a node crashes, impacting failover. This issue is one reason why many developers prefer to build stateless applications. However, if scalability is not a concern, then a stateful application should present no problems for you.

In the example in this section, session storage is used to count the number of times your portlet has rendered in Shared Screen mode.

7.2.6.1 Assumptions

To perform the tasks in this section, we are making the following assumptions:

1. You have followed through and understood Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper".

2. You built a portlet using the wizard and successfully added it to a page.

7.2.6.2 Implementing Session Storage

The PDK Framework represents the session with a ProviderSession object, which is established during the call to the Provider Instance's initSession method. This object is associated with the ProviderUser. To make data persistent between requests from Oracle Portal, you need to write data into the session object using the setAttribute method on the ProviderSession object. This method maps a java.lang.Object to a java.lang.String and stores that mapping inside the session object. The String can then be used to retrieve the Object during a subsequent request, provided the session is still valid.

A provider session may become invalid for the following reasons:

• The session times out.

• The invalidate method on ProviderSession is called.

• The JVM process running the servlet container is terminated.

All portlets contained by the same ProviderInstance share the same session for a particular ProviderUser. Therefore, data unique to a particular portlet instance must be mapped to a unique String in the session. This is accomplished using the portletParameter method in the PortletRendererUtil class. This method makes a supplied String parameter or attribute name unique to a PortletInstance, by prefixing it with a generated identifier for that instance. You can use the returned instance-specific name to write portlet instance data into the session.

For more detailed information on the PDK Framework classes, refer to the Javadoc on OTN by clicking Java Doc API on the Portlet Development page available at

http://www.oracle.com/technology/products/ias/portal/portlet_development_10g1014.html

To implement session storage, you need to perform the following tasks:

• Import ProviderSession, PortletRendererUtil, and HttpPortletRendererUtil.

• Retrieve the provider session.

• Read and write the session by accessing it from within your Java portlet.

• Set the session to true in provider.xml.

• Register the provider for session storage and set the Login Frequency.

The steps that follow describe how to add a session count to your portlet that displays how many times the portlet has been rendered for the current session.

1. After using the wizard to create a portlet, you can edit the JSP for the Show page in Oracle JDeveloper. You need to import the following classes:

   <%@page contentType="text/html; charset=windows-1252"
   import="oracle.portal.provider.v2.render.PortletRenderRequest"
   import="oracle.portal.provider.v2.http.HttpCommonConstants"
   import="oracle.portal.provider.v2.ProviderSession"
   import="oracle.portal.provider.v2.render.PortletRendererUtil"
   import="oracle.portal.provider.v2.render.http.HttpPortletRendererUtil"
   %>
   

2. Insert code that checks for a valid session first and then increments the count and displays it. If the session is valid and a previously stored value exists, you display the value, increment the count, and store the new value. If the session is valid but no previously stored value exists, you initialize a new count starting with 1, and display and store the value. You also want to obtain the unique string key for this portlet and then use an it in an array to count the session. If no session information was received, you want to provide information to the user indicating they may need to log back in.

   <%
   PortletRenderRequest pReq = (PortletRenderRequest)
   request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
   ProviderSession pSession = pReq.getSession();
     if (pSession != null)
     {
       String key = PortletRendererUtil.portletParameter(pReq, "count");
       Integer i = (Integer)pSession.getAttribute(key);
       if (i == null)
       {
         i = new Integer(0);
       }
       i = new Integer(i.intValue()+1);
       pSession.setAttribute(key, i);
   %>
   
   <p>Render count in this session: <%=i%> </p>
   
   <% 
     } 
     else 
     {
   %>
   
   <p>The session has become invalid</p>
   <br>
   Please log out and log in again.
   <%
     } 
   %>
   

3. By default, the wizard does not set session to true in provider.xml. You need to update this flag in order for the provider to receive session information from the portal. You should only set this tag to true if you are using session information in your provider or portlets. By setting this flag to true, extra load is added to the provider calls.

   <provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
   <session>true</session>
   

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

4. Register the provider in Oracle Portal. Ensure that you select the User radio button and choose a Login Frequency of Once Per Session on the Define Connections page of the wizard. For a reminder on how to register your portlet, refer to Section 6.5.5, "Registering and Viewing Your Oracle PDK-Java Portlet".

7.2.6.3 Viewing the Portlet

If you have not already added your Java portlet to a page, do so now. Ensure that you perform the following tasks:

• Set your provider to Once per User Session for the login frequency value.

• Refresh the provider to accept the new changes.

• Re-login in case your session is no longer valid.

7.2.7 Implementing Portlet Security

This section describes the available security services for your Java portlet.

For more detailed information about the PDK classes referred to in this section, refer to the Javadoc on OTN by clicking Java Doc API on the Portlet Development page available at

http://www.oracle.com/technology/products/ias/portal/portlet_development_10g1014.html

7.2.7.1 Assumptions

To perform the tasks in this section, we are making the following assumptions:

1. You have followed through and understood Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper".

2. You built a portlet using the wizard and successfully added it to a page.

7.2.7.2 Introduction to Portlet Security Features

This section introduces the major features that are available to secure your portlet providers.

7.2.7.2.1 Authentication

When a user first logs in to an Oracle Portal instance, they must enter their password to verify their identity and obtain access. This authentication is performed by OracleAS Single Sign-On Server server. Refer to Section 7.2.7.3, "Single Sign-On" for more information.

Once the user's identity is passed to the provider in shown requests, the provider code has access to the authenticated user's identity from the PortletRenderRequest that is available from the HttpServletRequest object as follows:

PortletRenderRequest pr = (PortletRenderRequest)request.getAttribute
   (HttpCommonConstants.PORTLET_RENDER_REQUEST);
   String userName = pr.getUser().getName();

Refer to Oracle Fusion Middleware Administrator's Guide for Oracle Portal for more information.

7.2.7.2.2 Authorization

Authorization determines if a particular user may view or interact with a portlet. Oracle Portal provides the following two types of authorization checking:

• Portal Access Control Lists (ACLs): After a user is authenticated by OracleAS Single Sign-On Server, Oracle Portal uses ACLs to determine what privileges that user has to perform actions on portal objects, such as folders and portlets. The actions available to a user can range from simply viewing an object to performing administrative functions on it. If a user does not belong to a group that has been granted a specific privilege, Oracle Portal prevents that user from performing the actions associated with that privilege. Refer to Section 7.2.7.4, "Oracle Portal Access Control Lists (ACLs)" for more information.

• Programmatic Portlet Security: You can also implement your own security manager programmatically. Refer to Section 7.2.7.5, "Portlet Security Managers" for more information.

7.2.7.2.3 Communication Security

To this point, we have covered user authentication and authorization, which do not check the authenticity of messages received by a provider. The following measures can be used to properly secure communication between a portal and a web provider:

• Oracle Portal Server Authentication restricts access to a provider to a small number of recognized machines. This method compares the IP address or the host name of an incoming HTTP message with a list of trusted hosts. If the IP address or host name is in the list, the message is passed to the provider. If not, it is rejected before reaching the provider. Refer to Section 7.2.7.6, "Oracle Portal Server Security" for more information.

• Message Authentication uses a shared key to assert the Portal client identity and to prevent message tampering. Refer to Section 7.2.7.7, "Message Authentication" for more information.

• Message Encryption encrypts message contents. Refer to Section 7.2.7.8, "HTTPS Communication" for more information.

• User Input Escape causes Oracle Portal to escape any user input strings and treat them as text only to protect against XSS attacks, where an attacker attempts to pass in malicious scripts through user input forms. Refer to Section 7.2.7.10, "User Input Escape" for more information.

For more information about communication security, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

7.2.7.3 Single Sign-On

Portlets act as windows into an application. They display summary information and provide a way to access the full functionality of the application. Portlets expose application functionality directly in the portal or provide deep links that take you to the application itself to perform a task.

An application may need to authenticate the user accessing the application through the portlet. Following are the possible application authentication methods:

• Section 7.2.7.3.1, "Partner Application". In this case, the application user is the same authenticated user used by Oracle Portal.

• Section 7.2.7.3.2, "External Application". In this case, the Oracle Portal user is different from the application user, but the application user name and password are managed by the Oracle Portal user.

• Section 7.2.7.3.3, "No Application Authentication". In this case, the communication between provider and Oracle Portal is not protected at all.

For more information about Single Sign-On, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

7.2.7.3.1 Partner Application

A partner application is an application that shares the same OracleAS Single Sign-On Server as Oracle Portal for its authentication. Thus, when a user is already logged in to Oracle Portal, their identity can be asserted to the partner application without them having to log in again.

Partner applications are tightly integrated with OracleAS Single Sign-On Server. When a user attempts to access a partner application, the partner application delegates the authentication of the user to OracleAS Single Sign-On Server. Once a user is authenticated (that is, has provided a valid user name and password) for one partner application, the user does not need to provide a user name or password when accessing other partner applications that share the same OracleAS Single Sign-On Server instance. OracleAS Single Sign-On Server determines that the user was successfully authenticated and indicates successful authentication to the new partner application.

The advantages of a partner application implementation are as follows:

• Provides the tightest integration with Oracle Portal and OracleAS Single Sign-On Server.

• Provides the best single sign-on experience to users.

• Provides the most secure form of integration because user names and passwords are not transmitted between Oracle Portal and the provider.

The disadvantages of a partner application implementation are as follows:

• The application must share the same user repository as Oracle Portal even though the application's user community may be a subset of the Oracle Portal user community. While worth some consideration, this issue is a minor one because the portal pages that expose the application can be easily restricted to the application's user community.

• The application can only be tightly integrated to one or more OracleAS Single Sign-On Server instances if they share the same user repository.

• The application must be written such that it delegates authentication to OracleAS Single Sign-On Server.

• You must have access to the application source code.

7.2.7.3.2 External Application

An external application uses a different authentication server than Oracle Portal. The application may use a different instance of OracleAS Single Sign-On Server than that used by Oracle Portal or some other authentication method. However OracleAS Single Sign-On Server does store the user name and password of the external application for that user. This means that when a user is already logged into Oracle Portal, they will be logged into the external application without having to type in their user name or password.

Applications that manage the authentication of users can be loosely integrated with OracleAS Single Sign-On Server if the administrator registers them as external applications. When a user who was previously authenticated by OracleAS Single Sign-On Server accesses an external application for the first time, OracleAS Single Sign-On Server attempts to authenticate the user with the external application. The authentication process submits an HTTP request that combines the registration information and the user's user name and password for the application. If the user has not yet registered their user name and password for the external application, OracleAS Single Sign-On Server prompts the user for the required information before making the authentication request. When a user supplies a user name and password for an external application, OracleAS Single Sign-On Server maps the new user name and password to the user's Oracle Portal user name and stores them. They will be used the next time the user needs authentication with the external application.

The advantages of an external application implementation are as follows:

• Allows integration with many portals. If, however, one of the portals is preferred over the others, the application could be integrated as a partner application of that preferred portal and an external application of the others.

• Provides a single sign-on experience for users. However, users still must maintain different user names and passwords. In addition, the external application user name mapping must be maintained.

• Allows integration with multiple portals independent of their user repositories and OracleAS Single Sign-On Server.

• Avoids the requirement of having access to the application source code.

The disadvantages of an external application implementation are as follows:

• Does not share the same user repository as the portal, which requires additional maintenance of user information by the end user.

• Transmits the user name and password to the provider in plain text, unless you implement SSL.

7.2.7.3.3 No Application Authentication

The provider trusts the Oracle Portal instance sending the request completely. The provider can determine if the user is logged in and the portal user name, but the application has not authenticated the user.

The advantages of no application authentication are as follows:

• Provides the easiest form of integration and the fastest to implement.

The disadvantages of no application authentication are as follows:

• Provides the least security.

• Provides the weakest integration with Oracle Portal.

7.2.7.4 Oracle Portal Access Control Lists (ACLs)

When users log in to an Oracle Portal instance, they are authenticated by an OracleAS Single Sign-On Server instance. Having verified their identity, Oracle Portal uses ACLs to determine whether they are authorized to access particular portlets and add them to pages from the Portlet Repository.

Oracle Portal ACLs operate according to the following security characteristics:

• Privileges define the actions that can be performed on the object to which they are granted. Privileges include actions such as Manage and Execute.

• Oracle Portal users and their privileges are granted from the Administer tab of the Builder.

• Oracle Portal user groups are administered from the Administer tab of Oracle Portal Builder. Membership in the groups and privileges granted to the groups are all defined and maintained here. A privilege granted to a user group is inherited by all the users of that group.

• Provider privileges apply to the provider and all of its portlets. Provider ACLs are administered on the Provider tab of the Oracle Portal Navigator.

• Portlet privileges can override the privileges set for the provider of the portlet. Portlet ACLs are administered from the Provider tab of the Oracle Portal Navigator. Clicking Open for a provider takes you to a page that manages the portlets of the provider.

For more information on the available privileges for objects, users, and user groups in Oracle Portal, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

The advantages of ACLs are as follows:

• ACLs offer a simple, yet powerful, mechanism to secure Oracle Portal objects.

• Central management of user group membership simplifies the management of ACLs because it negates the necessity of modifying the ACLs associated with each object.

The disadvantages of ACLs are as follows:

• ACLs are applied at the provider or portlet level. You cannot vary the security rules for a portlet depending on the page where you place it.

7.2.7.5 Portlet Security Managers

Portlet security managers are implemented within a provider to verify that a given user may view an instance of the portlet. When a user views a page with a portlet instance on it, security managers determine whether the user has the appropriate privileges to see the portlet. Implementing access control methods in the provider restricts the retrieval of content from a portlet (that is, hides the portlet) from users without the appropriate privileges. Only if the specified characteristics, such as user details and preferences, pass the authorization logic will the content be retrieved for the user. If no portlet security methods are implemented in the provider, then any user name may be passed in, even fictitious, unauthenticated ones.

A provider can implement two portlet security methods as follows:

• Get a list of portlets.

• Verify the accessibility of the portlet.

Portlets have access to the Oracle Portal user privileges and groups of which the user is a member. The following information can be used by the security methods:

• The default group of the user

• The privileges of a user or group

• The highest available privilege of a user across all groups

• The objects the user can access (only in database providers)

AuthLevelSecurityManager has access to the following information about authorization level:

• Strongly authenticated.

  The user has been authenticated by OracleAS Single Sign-On Server in the current Oracle Portal session, that is, the user logged in with a valid user name and password, and requested the portlet in the context of that session.

• Weakly authenticated.

  A user who was previously strongly authenticated returns to view a page without an active Oracle Portal session. A persistent cookie (maintained by the user's browser) indicates that in some previous session the user logged on with a valid user name and password.

• Public or not authenticated.

  The user has not logged in within the context of the current Oracle Portal session, and does not have a persistent cookie to indicate that such a state previously existed.

To incorporate these security services into your Java portlet, you simply need to update provider.xml and set the security level to strong, weak, or public. Place the following XML right before the </portlet> tag in provider.xml:

<securityManager class="oracle.portal.provider.v2.security.AuthLevelSecurityManager">
   <securityLevel>strong</securityLevel>
</securityManager>

After you make this change to provider.xml, refresh the provider.

For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

The advantages of security methods are as follows:

• You can enable a portlet to produce different output depending on the level of authorization.

The disadvantages of security methods are as follows:

• Most security manager implementations will use the authorization level or some other user specific element in an incoming message. A check of this type could be bypassed by an entity imitating an Oracle Portal instance.

7.2.7.5.1 Viewing the Portlet

After you add a security manager to a portlet, you can validate it by following these steps:

1. Ensure you are logged in to an Oracle Portal instance with privileges to create pages and add portlets to a page.

2. Create a new portal page, ensuring it is visible to PUBLIC.

3. Add your Java portlet to the page.

4. Make a note of the direct URL to your new Portal page.

5. Now log out of the Portal instance by clicking the Logout link.

6. Directly access the Portal page by entering the URL noted in Step 4 into your browser's address bar.

You will see the page created in Step 2 but not the portlet added in Step 3. When you added the portlet to the page, you were logged in and hence strongly authenticated. The PDK runtime detected this and allowed you to add the portlet. When you logged out and viewed the page, you were no longer strongly authenticated and hence the PDK Framework did not allow rendering of the portlet's contents.

If you log in again and view the page, you will see that the portlet is still there.

7.2.7.5.2 Implementing Your Own Security Manager

If your portlet requires special security arrangements which are not provided by the implementations shipped with the PDK, you will need to supply your own custom PortletSecurityManager controller class. To do this, extend the oracle.portal.provider.v2.security.PortletSecurityManager class and supply implementations for the two methods specified by the interface. Then replace the class attribute of the securityManager controller element in the XML provider definition with you new class name and configure child elements appropriately.

7.2.7.6 Oracle Portal Server Security

One way to prevent unauthorized access to providers is to restrict access to the provider to known client machines at the server level. Because only the identified clients may access the provider, this method defends against denial of service attacks.

In Oracle Fusion Middleware, you use the allow and deny directives in the httpd.conf file to control access to client machines based on their host names or IP addresses. If host names are used as discriminators, the server needs to look them up on its Domain Name Server (DNS), which adds extra overhead to the processing of each request. Using the IP address circumvents this problem, but the IP address of a remote client may change without warning.

The advantages of server security are as follows:

• It limits access to the provider to trusted hosts only.

• It simplifies configuration.

The disadvantages of server security are as follows:

• Oracle Web Cache does not have IP address checking capability. If Oracle Web Cache sits in front of a provider, you have no protection from a client on any host sending show requests to Oracle Web Cache.

• Restricting access to certain IP addresses and host names may be circumvented by sending messages to a provider containing fake IP addresses and host names. This trick is difficult to perform effectively since return messages go to the machine whose IP address was copied, but it can still cause problems.

For more information on this topic, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

7.2.7.7 Message Authentication

Message authentication uses a shared key known to the client (Portal instance) and provider to restrict access to known clients. This may be used in SSL communication with a provider instead of client certificates.

Oracle Portal sends a digital signature, calculated using a Hashed Message Authentication Code (HMAC) algorithm, with each message to a provider. A provider may authenticate the message by checking the signature using its own copy of the shared key. This technique may be used in Secure Socket Layer (SSL) communication with a provider instead of client certificates.

A single provider instance cannot support more than one shared key because it could cause security and administration problems. For instance, if one copy of the shared key is compromised in some way, the provider administrator has to create a new key and distribute it to all of the Oracle Portal clients, who then must update their provider definitions. The way around this problem is to deploy different provider services, specifying a unique shared key for each service. Each provider service has its own deployment properties file so that each service is configured independently of the others. The overhead of deploying multiple provider services within the same provider adapter is relatively small.

In a provider without Oracle Web Cache in front of it, this use of the same signature cookie over the lifetime of a provider session implies a trade-off between performance and the security provided by authenticating the requests. The signature cookie value is only calculated once after the initial SOAP request establishes the session with the provider. The shorter the provider session timeout, the more often a signature will be calculated providing greater security against a show request being resent illegally. However, the SOAP request required to establish a session incurs a time penalty.

In a provider using Oracle Web Cache to cache show request responses, you have a similar trade-off. Cached content is secured in the sense that incoming requests must include the signature cookie to retrieve it, but caching content for an extended period of time leaves the provider open to show requests being illegally trapped and resent to the provider.

While the signature element provides protection against interception and resending of messages, it does nothing to prevent interception and reading of message contents. Messages are still transmitted in plain text. If you are concerned about the content of messages being read by unauthorized people, you should use message authentication in conjunction with SSL.

The advantages of message authentication are as follows:

• Ensures that the message received by a provider comes from a legitimate Oracle Portal instance.

The disadvantages of message authentication are as follows:

• Causes administration problems if a provider serves more than one portal. Entails performance implications if made very secure by having a short session timeout.

For more information on this topic, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

Credential Store Share Key

The Producer's shared key is stored in the credential store. To store a shared key into the credential store do the following:

Create the Credential

To create the credentials, run the following WLST command:

createCred(map='PDK', key='pdk.omniPortlet.sharedKey', user='sharedKey', password='1234567890abc')

Grant PDK Java Code Access to the Credential Store

To grant pdk java code access to the credential store permission :

grantPermission(appStripe=None,principalClass=None,principalName=None,codeBaseURL='file:${domain.home}/servers/WLS_Portal/tmp/_WL_user/-',permClass='oracle.security.jps.service.credstore.CredentialAccessPermission',permTarget='context=SYSTEM,mapName=PDK,keyName=*',permActions='read')

7.2.7.8 HTTPS Communication

Normal communication between Oracle Portal and a provider uses HTTP, a network protocol that transmits data as plain text using TCP as the transport layer. HTTPS uses an extra secured layer (SSL) on top of TCP to secure communication between a client and a server, making it difficult to intercept and read messages.

Each entity (for example, an Oracle Web Cache instance) receiving a communication using SSL has a freely available public key and a private key known only to the entity itself. Any messages sent to an entity are encrypted with its public key. A message encrypted by the public key may only be decrypted by the private key so that, even if a message is intercepted by a felonious third party, it cannot be decrypted.

Certificates used to sign communications ensure that the public key does in fact belong to the correct entity. These are issued by trusted third parties, known as Certification Authorities (CA). They contain an entity's name, public key, and other security credentials and are installed on the server end of an SSL communication to verify the identity of the server. Client certificates may also be installed on the client to verify the identity of a client.

Oracle Wallet Manager manages public key security credentials. It generates public and private key pairs, creates a certificate request to a CA, and installs the certificate on a server.

For more information on this topic, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

Configuration of SSL

When a provider is registered from an Oracle Portal instance, only one URL is entered, which means either HTTP or HTTPS may be used but not both.

Each port on each server that may be used to receive SSL messages must have a server-side certificate installed (that is, an OracleAS Web Cache instance) in front of the Web provider and the server that hosts the provider. The certificate installed on a server port ensures that communication between two points is encrypted but does not authenticate the source of a message. Message authentication should be used as well to fully secure communication between a trusted Oracle Portal instance and a provider.

For more information about SSL configuration for Oracle Portal, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

7.2.7.9 LDAP (Oracle Internet Directory) Security

PDK-Java uses Portlet Security Managers for LDAP (Oracle Internet Directory) security. PDK-Java uses Oracle Internet Directory as a repository of users, groups, and permissions. It retrieves information about the logged-in user and determines whether the user has the required permissions to view the portlet and data within the portlet. By enabling Oracle Internet Directory security, your providers perform the following:

• Secure portlets based on groups.

• Restrict access to the administrative functions of your portlets (using your own security manager).

• Retrieve all of the user property information stored in the Oracle Internet Directory including first name, last name, title, e-mail, telephone number, groups, and photo.

• Create users and groups for Oracle Portal.

By default, Oracle Internet Directory security is disabled. You must make a change in the deployment properties file for a specific provider to enable this feature. Enabling and using Oracle Internet Directory to secure your portlets can be done quickly and easily. To do this, perform the following steps:

1. Enable the Oracle Internet Directory manager in the deployment properties files (provider_name.properties).

   oidManager=true
   oidAdminClass=class_that_extends_oracle.portal.provider.v2.oid.OidInfo
   

2. Provide the connection information for Oracle Internet Directory by extending the simple class called OidInfo.

3. Provide a list of groups that can view your portlet in the provider definition file.

   <group>cn=group1,cn=groups,dc=us,dc=oracle,dc=com</group>
   

   Your provider connects to Oracle Internet Directory using the information provided to the OidInfo class by you. The portlet accesses Oracle Internet Directory using the credentials provided (for example, user name and password) and performs the specified tasks. We recommend that you create an Oracle Internet Directory user specifically for your provider connection with the minimum set of privileges needed to complete the tasks requested by your portlets. For example, if your portlet only checks group information, do not connect to the Oracle Internet Directory as an administrator.

7.2.7.9.1 Implementing Oracle Internet Directory Security

PDK-Java provides a set of default classes specifically for Oracle Internet Directory integration. These classes handle the connection from your portlets to Oracle Internet Directory, enable your portlets to be secured based on Oracle Portal groups, and provide access to user property information from within Oracle Internet Directory. The classes used by your Web provider for Oracle Internet Directory integration are as follows:

• oracle.portal.provider.v2.oid.OidInfo receives the Oracle Internet Directory connection information provided by the developer and connects to Oracle Internet Directory. When building your own portlets, you should extend this class to send secure connection details from the provider to Oracle Internet Directory.

• oracle.portal.sample.v2.devguide.oid.UnsafeOidInfo is an extension of OidInfo and provides an easy way to test portlet security. This class is used by the Oracle Internet Directory samples in PDK-Java and parses the deployment properties file for the Oracle Internet Directory connection information (seen subsequently). This class should be used only for testing and development, it is not safe to use in a production scenario.

• oidManager is set to false by default. It must be set to true in provider_name.properties to enable Oracle Internet Directory. (If you have only one provider in your Web application, ensure that provider_name.properties is identical to _default.properties.) For example:

  serviceClass=oracle.webdb.provider.v2.adapter.soapV1.ProviderAdapter
  loaderClass=oracle.portal.provider.v2.http.DefaultProviderLoader
  showTestPage=true
  definition=providers/lab_provider/provider.xml
  autoReload=true
  oidManager=true
  oidAdminClass=oracle.portal.sample.v2.devguide.oid.UnsafeOidInfo
  oidHost=myhost.mydomain.com
  oidPort=oidPort
  oidUser=oidUser
  oidPasswd=oidPassword
  

• oidAdminClass is set to the class that extends OidInfo. PDK-Java provides UnsafeOidInfo by default, but as the name suggests, this class should not be used in production scenarios.

  • oidHost is the machine where Oracle Internet Directory is hosted.

  • oidPort is the port used by the Oracle Internet Directory.

  • oidUser is the Oracle Internet Directory account.

  • oidPasswd is the Oracle Internet Directory password.

  For example:

  serviceClass=oracle.webdb.provider.v2.adapter.soapV1.ProviderAdapter
  loaderClass=oracle.portal.provider.v2.http.DefaultProviderLoader
  showTestPage=true
  definition=providers/lab_provider/provider.xml
  autoReload=true
  oidManager=true
  oidAdminClass=oracle.portal.sample.v2.devguide.oid.UnsafeOidInfo
  oidHost=myhost.mydomain.com
  oidPort=oidPort
  oidUser=oidUser
  oidPasswd=oidPassword
  

• oracle.portal.provider.v2.security.GroupSecurityManager manages which groups have access to your provider and its portlets. It retrieves this information from the provider definition file and is portlet specific. Each portlet in a provider may have different group settings. There is no limit on the number of groups that can be set using this tag, but, since the Web provider parses and validates each group in turn, listing many groups may degrade performance.

• <group> is the tag in provider.xml that handles group management. It lists the groups allowed to access the portlet. The group information here follows the same case sensitivity as the Oracle Internet Directory.

  Note:

  The following example refers to your portal_instance_id, which is specific to your installation. To find your instance identifier, refer to your Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.

  <securityManager class="oracle.portal.provider.v2.security.
      GroupSecurityManager">
        <group>cn=DBA,cn=portal_instance_id,cn=groups,
               dc=us,dc=oracle,dc=com</group>
  </securityManager>
  

  
  

  For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

  http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
  

The advantages of Oracle Internet Directory security are as follows:

• Offers a simple, powerful way to secure your portlets.

• Secures data within your portlets based on the user's group membership.

• Creates users and groups directly from your portlets exposed as Web providers.

The disadvantages of Oracle Internet Directory security are as follows:

• Slightly degrades performance when authorizing your portlet through Oracle Internet Directory. There is a cost associated with obtaining group information from any LDAP server, but this cost only happens the first time a user accesses a portlet in a session.

• Requires provider access to Oracle Internet Directory.

• Assumes all Oracle Portal instances served by the provider use the same Oracle Internet Directory instance.

For more information on securing your providers using Oracle Internet Directory or to set up the sample portlets secured using Oracle Internet Directory, review the technical note, Installing the Oracle Internet Directory Portlets on OTN.

7.2.7.9.2 Viewing Your Portlets

After you secure your provider with Oracle Internet Directory, you can validate its behavior by following these steps:

1. Ensure you are logged in to an Oracle Portal instance as a user who is a member of the group specified in the <group> tag in provider.xml.

2. Use an existing page or create a new one, ensuring it is visible to PUBLIC.

3. Add your Java portlet to the page.

4. Make a note of the direct URL to your new page.

5. Click Logout.

6. Directly access the page by entering the URL noted in Step 4 in your browser's address bar or login to Oracle Portal using a user that is not part of the group listed in provider.xml.

You will see the page created in Step 2 but not the portlet added in Step 3, as shown in Figure 7-10. When you added the portlet to the page, you were logged in as a user authorized to view the portlet. The PDK runtime detected this and allowed you to add the portlet. When you logged out and viewed the page, you were no longer part of the group allowed to view the portlet and hence the PDK Framework did not allow rendering of the portlet's contents.

Figure 7-10 Page and Portlets for Developer

Description of "Figure 7-10 Page and Portlets for Developer"

If you log in again and view the page, you will see that the portlet is still there (Figure 7-11).

Figure 7-11 Page and Portlets for Developer/Administrator

Description of "Figure 7-11 Page and Portlets for Developer/Administrator"

7.2.7.10 User Input Escape

By accepting user input without escaping it to text, you run the risk of an XSS attack, where an attacker attempts to pass in malicious scripts through user input forms. For example, if a portlet title is customizable, an attacker might attempt to pass scripts or commands to the portlet through the title string. Oracle Portal provides the following features to ensure that you can protect your portlets from such attacks:

• Section 7.2.7.10.1, "Default Container Encoding"

• Section 7.2.7.10.2, "Escape Methods"

7.2.7.10.1 Default Container Encoding

To prevent any script inside a portlet title from being executed, the framework default container renderer class encodes any script characters. This default behavior is controlled through a JNDI variable, escapeStrings. When set to true, the markup tags in portlet titles are rendered as visible tag characters. For example, a title customization of <i>title</i> will be rendered as <i>title</i> not title. This mode is secure, but, if it is not the desired behavior, you can set escapeStrings to false for that provider.

escapeStrings applies to all logical providers within a Web provider. You can set the value of escapeStrings from the WebLogic Server Administration Console as you would any other JNDI variable. Refer to Section 7.2.4.2, "Setting JNDI Variable Values" for more information.

7.2.7.10.2 Escape Methods

If you have code that renders customized values, you need to ensure that you escape those input values appropriately to avoid XSS attacks. This requirement applies to code for rendering pages in any mode. Oracle Portal supplies two new static methods for this purpose. They are in the Java class oracle.portal.provider.v2.url.UrlUtils, and can be described as follows:

• public static escapeString(string_text) escapes any script characters in a given string. For example, less than < becomes &lt. This method is unaffected by the escapeStrings JNDI variable and is the secure, recommended method to use.

• public static escapeStringByFlag(string_text) escapes any script characters in a given string. This method is controlled by the escapeStrings JNDI variable and is therefore less secure and not the recommended method to use.

For example:

title = UrlUtils.escapeString(data.getPortletTitle());

7.2.8 Controlling the Export/Import of Portlet Personalizations

The export/import facility of Oracle Portal is a multi-purpose tool for moving your portal objects, such as portlets, between instances of Oracle Portal. For example, you might use export/import to move objects from a development environment to a stage environment and then, finally, to a production environment. You might also use export/import to move pages and page groups between Oracle Portal instances, or to move Web providers from one machine to another. For more information about export/import in general, please refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

Because portlet default settings can be set by the administrator and then changed by the user, they require some special consideration when you import and export them. To simplify the transport process, Oracle Portal provides default functionality that handles administrator personalization data (that is, data created using Edit Defaults mode) for you. When a portlet is exported, the default personalization data stored using PDK-Java's PreferenceStore mechanism is exported with the portlet by default. Hence, when the portlet is imported into a target instance of Oracle Portal, this data is imported along with it. As a result, the portlet instance's default settings are maintained when the portlet is moved from one portal instance to another.^Foot 1 

The aforementioned behavior is provided to you as a convenience and it requires no action on your part to leverage. You might, however, want to exercise more granular control over the export of personalization data than that provided by the default functionality. To implement your own requirements for export/import, you can make use of the programming interface to augment or override the default handling of personalizations.

If you use the PDK-Java preference store mechanism, the export/import of your Edit Default personalizations is built-in and requires no additional effort on your part. This default export/import of administrator personalizations relies on the PDK-Java preference store. If you have created your own preference store mechanism (for example, a file or database preference storage system), then you also must implement your own export/import support that performs the following functions:

• Exports personalizations. This functionality must at least export administrator personalizations, but it could optionally include user personalizations, too.

• Imports personalizations. Note that this functionality must reflect whatever you implemented for export. For example, if you allow the export of both administrator and user personalizations, then the import functionality must support both as well.

The export/import functionality for personalizations requires that your Oracle Portal instance and provider are on Release 10.1.2. Export/import of personalizations behaves the same regardless of the location of your provider, which can be either of the following:

• in the default Oracle Containers for Java EE of the Oracle Fusion Middleware, where the Oracle Portal instance is different.

• in a separate Oracle Containers for Java EE, where the Oracle Portal instance may be different, and the provider is the same but is not registered on the target Oracle Portal instance.

7.2.8.1 Import/Export Programming Interface

The PDK-Java's preference store mechanism allows data to be persisted by any number of application entities. The following three entities are the ones that persist data for the purposes of export/import:

1. The portlet instance is the portlet on a page with the default personalizations made to it by the administrator. The API for the portlet instance is as follows:

   • oracle.portal.provider.v2.PortletInstance

     • exportData

       public byte[] exportData
           (
               boolean exportUsers,
               String[] userNames,
               TransportLogger logger
           )    throws PortletException
       

     • importData

       public void importData
           (
               byte[] data,
               TransportLogger logger
           )
           throws PortletException
       

2. The portlet definition is the base portlet without any personalizations applied to it. You might think of the portlet definition as the version of the portlet that exists in the Portlet Repository before it is placed on a particular page for use. The API for the portlet definition is as follows:

   • oracle.portal.provider.v2.PortletDefinition

     • exportData

       public byte[] exportData
           (
               ProviderInstance pi,
               boolean exportUsers,
               String[] userNames,
               TransportLogger logger  
           )
           throws PortletException
       

     • importData

       public void importData
           (
               ProviderInstance pi,
               byte[] data,
               TransportLogger logger
           )
           throws PortletException
       

3. The provider instance is the entity that contains and communicates with a set of portlets. The API for the provider instance is as follows:

   • oracle.portal.provider.v2.ProviderInstance

     • exportData

       public byte[] exportData
           (
               boolean exportUsers,
               String[] userNames,
               TransportLogger logger
           )
           throws ProviderException
       

     • importData

       public void importData
           (
               byte[] data,
               TransportLogger logger
           )
           throws ProviderException
       

By default, each of these entities employs an instance of oracle.portal.provider.v2.transport.PrefStoreTransporter to transform the data from an oracle.portal.provider.v2.preference.PreferenceStore to a byte array for transport. For the default export/import behavior, though, only the portlet instance entity's personalization data is exported and imported. If you have persisted data at the portlet definition or provider instance level, you may want to export that data as well. For example, a billing handle that you persisted at the ProviderInstance level may need to be exported.

To change the behavior of PrefStoreTransporter, you can override its default implementation. The example in Section 7.2.8.3.7, "Exporting by Reference Example" illustrates how you can override PrefStoreTransporter.

Logging Interface

To simplify troubleshooting of your export/import transactions, you can send messages to both the calling Oracle Portal instance and the Web provider log. PDK-Java provides a transport logging class that enables you to add events to the log during export and import operations. In this way, you can better keep track of events that occur during the transport of portlet personalizations. The log can be a valuable troubleshooting tool if you encounter unexpected behavior in your portlets during or after transport. For example, you can log events when incompatibilities between PDK-Java versions are found.

You log events using the logger object, an instance of the oracle.portal.provider.v2.transport.TransportLogger class provided for each of the methods mentioned earlier. You log events with the calling portal through the instance provided for each method. You record events in the Web provider log with the normal logging mechanism, oracle.portal.log.LogManager. The log levels for export/import are as follows:

• TransportLogger.SEVERITY_INFO

• TransportLogger.SEVERITY_WARNING

• TransportLogger.SEVERITY_ERROR

7.2.8.2 Exporting Personalizations Example

This example illustrates the most basic case where you build a portlet and accept the default behavior for the export of personalizations. In the examples in Section 7.2.8.3.6, "Encrypting Personalization Data Example" and Section 7.2.8.3.7, "Exporting by Reference Example", you will see how to enhance the security of your personalizations during export and import. To implement the more basic form of exporting personalizations, do the following:

1. Create a stock portlet and implement the Show mode with the following MyStockPortletShowRenderer.java class. Note that this class does not incorporate any special code to enable export/import.

   package oracle.portal.sample.v2.devguide.tx;
   import java.util.StringTokenizer;
   import oracle.portal.provider.v2.PortletException;
   import oracle.portal.provider.v2.personalize.NameValuePersonalizationObject;
   import oracle.portal.provider.v2.render.PortletRenderRequest;
   import oracle.portal.provider.v2.render.PortletRendererUtil;
   import oracle.portal.provider.v2.render.http.BaseManagedRenderer;
   import java.io.PrintWriter;
   import oracle.portal.sample.v2.devguide.webservices.
       NetXmethodsServicesStockquoteStockQuoteServiceStub;
   public class MyStockPortletShowRenderer extends BaseManagedRenderer
   {
       private String pid = null;
       private String userdata;
       private String stockList;
       private String stockCode;
     public void renderBody(PortletRenderRequest request) throws PortletException
     {
       // Use the PrintWriter from the PortletRenderRequest
       PrintWriter out = null;
       NetXmethodsServicesStockquoteStockQuoteServiceStub ns = new
         NetXmethodsServicesStockquoteStockQuoteServiceStub();
       try
       {
         out = request.getWriter();      NameValuePersonalizationObject data = null;
         data = (NameValuePersonalizationObject)PortletRendererUtil.
            getEditDefaultData(request);
         stockList= data.getString("stock");
         if(stockList!=null) {
           StringTokenizer st = new  StringTokenizer(stockList,",");   
           out.println("<table border='0'>");
           out.println("<thead>");
           out.println("<tr>");
           out.println("<th width='20%'>");
           out.println("<p align='left'> Stock Code</p></th><th width='20%'>");
           out.println("<p align='left'> Quote</p>");
           out.println("</th>");
           out.println("</tr>");
           out.println("<thead>");
               while(st.hasMoreElements()) {    
                 stockCode= st.nextElement().toString();
                 out.println("<tr>");
                 out.println("<td width='20%'>");
                 out.println("<p align='left'>"+  stockCode + 
                    "</p></td><td width='20%'>");
                 out.println(ns.getQuote(stockCode));
                 out.println("</td>");
                 out.println("</tr>");
               }
           out.println("</table>");
         }
         else
         {
           out.println("<br> Click <b>Edit Defaults</b> to define stock codes.");     
         }
       }
       catch(Exception ioe)
       {
         throw new PortletException(ioe);
       }         
     }
   }
   

2. Implement the Edit Defaults mode for your stock portlet with the following class, MyStockPortletEditDefaultsRenderer.java. This class enables the administrator to make and store default personalizations, which are then exported according to the default behavior.

   package oracle.portal.sample.v2.devguide.tx;
   import oracle.portal.provider.v2.PortletException;
   import oracle.portal.provider.v2.http.HttpCommonConstants;
   import oracle.portal.provider.v2.render.PortletRenderRequest;
   import oracle.portal.provider.v2.render.http.BaseManagedRenderer;
   import oracle.portal.provider.v2.render.PortletRendererUtil;
   import oracle.portal.provider.v2.personalize.NameValuePersonalizationObject;
   import java.io.PrintWriter;
   import java.io.IOException;
   import oracle.portal.provider.v2.render.http.HttpPortletRendererUtil;
   public class MyStockPortletEditDefaultsRenderer extends BaseManagedRenderer 
   {
     public void renderBody(PortletRenderRequest request) throws PortletException
     {
       PrintWriter out = null;
       try
       {
         out = request.getWriter();
       }
       catch(IOException ioe)
       {
         throw new PortletException(ioe);
       }
       
       // Personalize the portlet title and stock
       String actionParam = PortletRendererUtil.getEditFormParameter(request);
       PortletRenderRequest prr = (PortletRenderRequest)
           request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
       String action = request.getParameter(actionParam);
       String title = prr.getQualifiedParameter("myportlet_title");
       String stock = prr.getQualifiedParameter("myportlet_stock");
       NameValuePersonalizationObject data = null;
       try
       {
         data = (NameValuePersonalizationObject)
                 PortletRendererUtil.getEditDefaultData(request);
       }
       catch(IOException io)
       {
         throw new PortletException(io);
       }
       // Cancel automatically redirects to the page, so
       // will only recieve OK or APPLY
       if (action != null)
       {
         data.setPortletTitle(title);
         data.putString("stock",stock);
         try
         {
           PortletRendererUtil.submitEditData(request, data);
         }
         catch(IOException ioe)
         {
           throw new PortletException(ioe);
         }
         return;
       }
       // Otherwise just render the form
       title = data.getPortletTitle();
       stock = data.getString("stock");
       out.print("<table border='0'> <tr> ");
       out.println("<td width='20%'> <p align='right'>Title:</p></td>
                    <td width='80%'>");
       out.print("<input type='TEXT' name='" + 
                  HttpPortletRendererUtil.portletParameter(prr, "myportlet_title")
                  + "' value='" + title + "'>");
       out.println("</td> </tr>");  
       out.print("<tr> <td width='20%'> <p align='right'>Stock Codes:</p></td>
                  <td width='80%'>");
       out.print("<input type='TEXT' name='" + 
                  HttpPortletRendererUtil.portletParameter(prr, "myportlet_stock")
                  + "' value='" + stock + "'>");
       out.println("<br> For example use US Stock Codes separated by comma: 
                    <i> SUNW,IBM,ORCL</i>");
       out.print("</td> </tr>");
       out.println("</table>");
     }
   }
   

3. Create the following class, NetXmethodsServicesStockquoteStockQuoteServiceStub.java, for your stock portlet:

   package oracle.portal.sample.v2.devguide.webservices;
   import oracle.soap.transport.http.OracleSOAPHTTPConnection;
   import org.apache.soap.encoding.SOAPMappingRegistry;
   import java.net.URL;
   import org.apache.soap.rpc.Call;
   import org.apache.soap.Constants;
   import java.util.Vector;
   import org.apache.soap.rpc.Parameter;
   import org.apache.soap.rpc.Response;
   import org.apache.soap.Fault;
   import org.apache.soap.SOAPException;
   import java.util.Properties;
   public class NetXmethodsServicesStockquoteStockQuoteServiceStub 
   {
     public NetXmethodsServicesStockquoteStockQuoteServiceStub()
     {
       m_httpConnection = new OracleSOAPHTTPConnection();
       m_smr = new SOAPMappingRegistry();
     }
     private String _endpoint = "http://64.124.140.30:9090/soap";
     public String getEndpoint()
     {
       return _endpoint;
     }
     public void setEndpoint(String endpoint)
     {
       _endpoint = endpoint;
     }
     private OracleSOAPHTTPConnection m_httpConnection = null;
     private SOAPMappingRegistry m_smr = null;
     public Float getQuote(String symbol) throws Exception
     {
       Float returnVal = null;
       URL endpointURL = new URL(_endpoint);
       Call call = new Call();
       call.setSOAPTransport(m_httpConnection);
       call.setTargetObjectURI("urn:xmethods-delayed-quotes");
       call.setMethodName("getQuote");
       call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
       Vector params = new Vector();
       params.addElement(new Parameter("symbol", String.class, symbol, null));
       call.setParams(params);
       call.setSOAPMappingRegistry(m_smr);
       Response response = call.invoke(endpointURL,
         "urn:xmethods-delayed-quotes#getQuote");
       if (!response.generatedFault())
       {
         Parameter result = response.getReturnValue();
         returnVal = (Float)result.getValue();
       }
       else
       {
         Fault fault = response.getFault();
         throw new SOAPException(fault.getFaultCode(), fault.getFaultString());
       }
       return returnVal;
     }
     public void setMaintainSession(boolean maintainSession)
     {
       m_httpConnection.setMaintainSession(maintainSession);
     }
     public boolean getMaintainSession()
     {
       return m_httpConnection.getMaintainSession();
     }
     public void setTransportProperties(Properties props)
     {
       m_httpConnection.setProperties(props);
     }
     public Properties getTransportProperties()
     {
       return m_httpConnection.getProperties();
     }
   }
   

4. Create a Web provider through provider.xml for this portlet. Notice the use of the <preferenceStore> element to allow for the storing of personalizations:

   <provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
      <session>false</session>
      <passAllUrlParams>false</passAllUrlParams>
      <preferenceStore class="oracle.portal.provider.
                              v2.preference.FilePreferenceStore">
         <name>prefStore1</name>
         <useHashing>true</useHashing>
      </preferenceStore>
      <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
         <id>1</id>
         <name>MyStockPortlet</name>
         <title>My Stock Portlet</title>
         <description>Simple Stock Portlet to show Export and Import 
                      feature of web providers</description>
         <timeout>80</timeout>
         <showEditToPublic>false</showEditToPublic>
         <hasAbout>false</hasAbout>
         <showEdit>false</showEdit>
         <hasHelp>false</hasHelp>
         <showEditDefault>true</showEditDefault>
         <showDetails>false</showDetails>
         <renderer class="oracle.portal.provider.v2.render.RenderManager">
            <renderContainer>true</renderContainer>
            <renderCustomize>true</renderCustomize>
            <autoRedirect>true</autoRedirect>
            <contentType>text/html</contentType>
            <showPage class="oracle.portal.sample.v2.
                             devguide.tx.MyStockPortletShowRenderer"/>
            <editDefaultsPage class="oracle.portal.sample.v2.devguide.tx.
                                     MyStockPortletEditDefaultsRenderer"/>
         </renderer>
         <personalizationManager class="oracle.portal.provider.v2.personalize.
                                        PrefStorePersonalizationManager">         <dataClass>oracle.portal.provider.v2.personalize.
                       NameValuePersonalizationObject
            </dataClass>
         </personalizationManager>
      </portlet>
   </provider>
   

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

5. Register this export-enabled provider with the source Oracle Portal instance. For more information about registering Web providers, refer to Section 6.5.5, "Registering and Viewing Your Oracle PDK-Java Portlet".

   Note:

   If the Web provider is running in a secured environment, remember to provide the proxy host and port while starting up Oracle WebLogic Server. For example:

   JAVA_OPTIONS=“-Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
   

6. Create two regions on a sample page and add My Stock Portlet to the first region. For information on creating regions and pages, refer to the Oracle Fusion Middleware User's Guide for Oracle Portal.

7. Edit the page and click the Edit Defaults icon for My Stock Portlet. Choose the stock codes SUNW,IBM,ORCL. For more information on how to edit defaults for a portlet on a page, refer to the Oracle Fusion Middleware User's Guide for Oracle Portal.

8. Add My Stock Portlet to a second region and again edit the defaults. Use a different stock code this time, MSFT.

9. Export the page group containing this page. For instructions on how to export a page group, refer to Chapter 10, "Exporting and Importing Content," in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

10. Import the page group into a target Oracle Portal instance. For instructions on how to import a page group, refer to Chapter 10, "Exporting and Importing Content," in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

11. View the page with My Stock Portlet in the target Oracle Portal instance and ensure that the personalizations were maintained.

7.2.8.3 Implementing Security for Export/Import

Transporting personalizations can present a security concern if your portlet stores sensitive data and is not operating in a secured environment. At the provider and portlet level, Oracle Portal provides several ways for you to secure the export and subsequent import of portlet personalizations. To better secure portlets and providers for exportation and importation, you can take the following actions:

• Section 7.2.8.3.1, "Securing Provider Communications". Using Oracle Portal configuration options, you can secure the communications between providers and Oracle Portal. This step in turn makes the export and import of portlets more secure.

• Section 7.2.8.3.2, "Disabling Export/Import of Personalizations". You can disable the export of all portlet personalization data for each Web application. This method provides the greatest security but only at a significant cost in functionality because it prevents administrators from retaining their default personalizations when the portlet is moved.

• Section 7.2.8.3.3, "Obfuscating Data for Transport (Automatic)". By default, Oracle Portal obfuscates but does not encrypt personalization data before transporting it.

• Section 7.2.8.3.4, "Encrypting Personalization Data for Transport". You may want to encrypt personalization data for transport if any of the following are true:

  • Your Web provider connection is not secured using HTTPS.

  • You want to ensure the data is secured during transit.

  • You want the data to remain secure while stored in the Oracle Portal instance.

• Section 7.2.8.3.5, "Exporting by Reference". Instead of including portlet personalization data directly in the transport set, you can include it by reference in the transport set. Because the data itself is not present in the transport set, export by reference is the most secure way of transporting personalizations.

7.2.8.3.1 Securing Provider Communications

If the security of exporting/importing portlets is of concern to you, you should configure Oracle Portal to secure communications with your portlet providers. The chief mechanisms for securing provider communications in Oracle Portal are as follows:

• Message authentication through a Hashed Message Authentication Code (HMAC) algorithm. For more information on message authentication for providers, refer to Section 6.1.7.8, "Message Authentication", in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

• HTTPS between providers and Oracle Portal. For more information on HTTPS for provider communications, refer to Section 6.1.7.9, "HTTPS Communication", in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

  Note:

  You cannot use certificates for the HTTPS communication with providers.

7.2.8.3.2 Disabling Export/Import of Personalizations

The JNDI variable, oracle/portal/provider/global/transportEnabled, controls whether to allow the exportation and importation of personalizations. If you set the variable to true, personalizations are transported as part of export and import. If you set it to false, they are not transported. You can set JNDI variables for PDK-Java through a Deployment Plan set on the PDK-Java web application in the Oracle WebLogic Server. This can be done using the WebLogic Server Administration Console. Deployment Plans allow for easy modification of an application's configuration, without modifying the packaged deployment descriptor files. After setting up the Deployment Plan, you can make manual changes to it for the JNDI variable within the pre-existing WEB-INF/web.xml module descriptor, like the following:

<module-descriptor external="false">
      <root-element>web-app</root-element>
      <uri>WEB-INF/web.xml</uri>
      <variable-assignment>
        <name>provider_transportEnabled</name>        <xpath>/web-app/env-entry/[env-entry-name=&quot;oracle/portal/provider/global/transportEnabled&quot;]/env-entry-value</xpath>
      </variable-assignment>
    </module-descriptor>

The variable definition of this variable assignment is made directly under the <deployment-plan> tag, and will look like:

<variable-definition>
      <variable>
        <name>provider_transportEnabled</name>
        <value>false</value>
      </variable>
    </variable-definition>

This sets oracle/portal/provider/global/transportEnabled to false.

See:

Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server

7.2.8.3.3 Obfuscating Data for Transport (Automatic)

By default, personalization data is encoded (Base64). This encoding ensures that data is obfuscated during transport. You do not need to take any actions to leverage Base64 encoding as it is provided by default. However, if you want greater security, you can encrypt the data. Refer to Section 7.2.8.3.4, "Encrypting Personalization Data for Transport".

7.2.8.3.4 Encrypting Personalization Data for Transport

By implementing the oracle.portal.provider.v2.security.CipherManager class for your provider, you can encrypt the personalization data prior to exporting it. Upon import, the cipher manager is invoked again to decrypt the data. Refer to Section 7.2.8.3.6, "Encrypting Personalization Data Example".

Note:

If you choose to encrypt your Web providers for export using the cipher manager, you must also devise your own key management strategy for the encryption algorithm.

7.2.8.3.5 Exporting by Reference

As mentioned previously, the default behavior for exporting of portlets is to include the actual personalization data in the transport set. For a more secure transport, you can code your portlet such that the personalizations are exported using pointers rather than by including the actual preference data. When the transport set is imported, the target Oracle Portal instance sends the pointer back to the Web provider, which then has the opportunity to reassociate the actual data with the new portlet instance. Refer to Section 7.2.8.3.7, "Exporting by Reference Example".

Note:

When exporting across security zones, exporting by reference may not work effectively. In general, you should only employ export by reference when transporting within the same general security environment.

7.2.8.3.6 Encrypting Personalization Data Example

To encrypt personalization data in your Web provider, you need to create your own cipher manager and associate it with your portlet provider. This example provides a simple, insecure cipher manager for illustrative purposes only. To implement a secure implementation of the cipher manager for your production system, you would need to significantly extend this sample. Some of the issues you would need to consider for a production implementation are as follows:

• Do not hold the key object in memory. Read it from a persistent store as necessary.

• Use the provider's PreferenceStore API supported by a DBPreferenceStore to work in the clustered case.

• On import, if the cipher manager instance obtained from provider.xml matches the class name returned in the SOAP message, that CipherManager instance is used to perform the decryption. Hence, the instance maintained in the portlet/provider definition may be configured using any applicable means (for example, tags in provider.xml or JNDI variable) and that configuration is reused on import.

To encrypt personalization data in your Web provider, do the following:

Note:

The following sample is for illustrative purposes only. You would need to significantly enhance it for use in a production environment.

1. Create a cipher manager class, InsecureCipherManager. This class will be used for encryption and decryption of personalization data exported from or imported to a Web provider. A base64 encoded, hard coded secret key is used with the DES algorithm supplied by the default javax.crypto provider of the underlying Java Runtime Environment. As a result, this particular sample is insecure because the encoded key can be recovered by a malicious party simply by decompiling the byte code.

   Note:

   This sample makes use of the javax.crypto package, which is optional in Java 1.3 and must be installed manually. In Java 1.4, though, this package is present by default.

   package oracle.portal.sample.v2.devguide.tx;
   import java.io.IOException;
   import java.security.GeneralSecurityException;
   import javax.crypto.Cipher;
   import javax.crypto.SecretKey;
   import javax.crypto.SecretKeyFactory;
   import javax.crypto.spec.DESKeySpec;
   import oracle.portal.provider.v2.ProviderException;
   import oracle.portal.provider.v2.security.CipherManager;
   import sun.misc.BASE64Decoder;
   public final class InsecureCipherManager implements CipherManager
   {
       /**
        * Base64 encoded external form of a javax.crypto.SecretKey which was
        * generated for the DES algorithm. This is completely insecure! Anyone
        * can decompile the bytecode and recostitue the key. A more secure
        * implementation would implement a key management policy in a
        * java.security.KeyStore.
        */
       private static final String sEncodedKey = "UTJds807Arw=";
       /**
        * Generated from the (insecure) encoded form in sEncodedKey.
        */
       private SecretKey mKey;
       /**
        * Transforms the input data to a more secure form, in a single operation,
        * using the DES cryptographic algorithm along with a statically defined
        * secret key.
        * @param toEncode the input data.
        * @return an encoded form of the input data.
        * @throws ProviderException if an error occurs during transform.
        */
       public final byte[] encode(byte[] toEncode) throws ProviderException
       {
           try
           {
               Cipher c = Cipher.getInstance("DES");
               c.init(Cipher.ENCRYPT_MODE, getSecretKey());
               return c.doFinal(toEncode);
           }
           catch (GeneralSecurityException gse)
           {
               throw new ProviderException(gse);
           }
           catch (IOException ioe)
           {
               throw new ProviderException(ioe);            
           }
       }
       /**
        * Transforms the input data to its original form, in a single operation,
        * using the DES cryptographic algorithm along with a statically defined
        * secret key.
        * @param toDecode the input data.
        * @return a decoded form of the input data.
        * @throws ProviderException if an error occurs during transform.
        */
       public final byte[] decode(byte[] toDecode) throws ProviderException
       {
           try
           {
               Cipher c = Cipher.getInstance("DES");
               c.init(Cipher.DECRYPT_MODE, getSecretKey());
               return c.doFinal(toDecode);
           }
           catch (GeneralSecurityException gse)
           {
               throw new ProviderException(gse);
           }
           catch (IOException ioe)
           {
               throw new ProviderException(ioe);            
           }
       }
       /**
        * Returns a <code>javax.crypto.SecretKey</code> deserialized from the
        * obuscated form in sEncodedKey. Note, this is highly insecure!!
        */
       private SecretKey getSecretKey()
           throws GeneralSecurityException, IOException
       {
           if (mKey == null)
           {
               DESKeySpec ks = new DESKeySpec((new BASE64Decoder()).decodeBuffer(
                   sEncodedKey));
               SecretKeyFactory skf = SecretKeyFactory.getInstance("DES");
               mKey = skf.generateSecret(ks);
           }
           return mKey;
       }
   }
   

2. Modify your provider.xml to reference the cipher manager:

   <?xml version = '1.0' encoding = 'UTF-8'?>
   <?providerDefinition version="3.1"?>
   <provider class="oracle.portal.provider.v2.DefaultProviderDefinition">  
   <providerInstanceClass>net.mzyg.tx.TxProviderInstance</providerInstanceClass>
      <session>false</session>
      <passAllUrlParams>false</passAllUrlParams>
      <preferenceStore class="oracle.portal.provider.v2.
         preference.DBPreferenceStore">
         <name>prefStore1</name>
         <connection>java:comp/env/jdbc/PortletPrefs</connection>
      </preferenceStore>
   <cipherManager class="oracle.portal.sample.v2.devguide.tx.
      InsecureCipherManager"/>
   

7.2.8.3.7 Exporting by Reference Example

To export by reference rather than exporting the actual personalization, do the following:

1. Override the DefaultPortletInstance with the following ExportByRefDefaultPortletInstance:

   package oracle.portal.sample.v2.devguide.tx;
   import oracle.portal.provider.v2.DefaultPortletInstance;
   import oracle.portal.provider.v2.preference.PreferenceStore;
   import oracle.portal.provider.v2.transport.PrefStoreTransporter;
   public class ExportByRefDefaultPortletInstance extends DefaultPortletInstance
   {
     /**
      * Returns a {@link oracle.portal.provider.v2.transport.PrefStoreTransporter}
      * capable of carrying out transport operations such as export/import on
      * data applicable to {@link oracle.portal.provider.v2.PortletInstance} 
      * persisted in {@link oracle.portal.provider.v2.preference.PreferenceStore}.
      * This implementation returns an {@link ExportByRefPrefStoreTransporter}.
      * @param ps the {@link oracle.portal.provider.v2.preference.PreferenceStore}
      * containing the data to be transported.
      * @return a {@link oracle.portal.provider.v2.transport.PrefStoreTransporter}
      */
     protected PrefStoreTransporter getPrefStoreTransporter(PreferenceStore ps)
     {
         return new ExportByRefPrefStoreTransporter(ps);
     }
   }
   

2. Create the ExportByRefPrefStoreTransporter class referenced in ExportByRefDefaultPortletInstance. This class implements an alternative preference store transporter that does not send preference data during the export operation. Instead, it writes the context path of the source preference to the stream. During the export, it reads the context path and uses that path to look up the preference data and copy it to the new instance. This method of exporting by reference assumes that the source and target providers have access to the same preference store. In fact, the best case for this example would be the situation where the source and target providers are the same.

   package oracle.portal.sample.v2.devguide.tx;
   import java.io.IOException;
   import java.io.InputStream;
   import java.io.OutputStream;
   import java.io.DataInputStream;
   import java.io.DataOutputStream;
   import oracle.portal.provider.v2.transport.PrefStoreTransporter;
   import oracle.portal.provider.v2.transport.TransportLogger;
   import oracle.portal.provider.v2.preference.Preference;
   import oracle.portal.provider.v2.preference.PreferenceStore;
   import oracle.portal.provider.v2.preference.PreferenceStoreException;
   public class ExportByRefPrefStoreTransporter extends PrefStoreTransporter 
   {
       public ExportByRefPrefStoreTransporter(PreferenceStore prefStore)
       {
           super(prefStore);
       }
      /**
        * Exports the context path of the supplied {@link
        * oracle.portal.provider.v2.preference.Preference} from the {@link
        * oracle.portal.provider.v2.preference.PreferenceStore}.
        * @param pref the source {@link
        * oracle.portal.provider.v2.preference.Preference}
        * @param out the <code>java.io.OutputStream</out> to which data will be
        * written.
        * @param logger
        */
      protected void exportPreference(Preference pref, OutputStream out,
           TransportLogger logger) throws PreferenceStoreException, IOException
       {
           // Get the context path of the preference we are exporting.
           String contextPath = pref.getContextPath();
           DataOutputStream dos = new DataOutputStream(out);
           // Write the context path in the export data. The import process
           // will use this context path to lookup this preference in the
           // preference store and copy it to the new context 
           dos.writeUTF(contextPath);
       }
       /**
        * Reads a context path from the stream and copies preference data
        * from that location into the {@link
        * oracle.portal.provider.v2.preference.PreferenceStore}.
        * @param pref the target {@link
        * oracle.portal.provider.v2.preference.Preference}
        * @param in the <code>java.io.InputStream</code> from which to read data.
        * @param logger
        */
       protected void importPreference(Preference pref, InputStream in,
           TransportLogger logger) throws PreferenceStoreException, IOException
       {
           // Read the context path to copy the value for this
           // preference from.
           DataInputStream dis = new DataInputStream(in);
           String contextPath = dis.readUTF();
           // Create preference object to copy from (identical to the 
           // target preference but with a different context path)
           Preference sourcePref = new Preference(contextPath, 
              pref.getName(), pref.getType(), (String)null);
           // Copy across the preference
           getPrefStore().copy(sourcePref, pref, true);
       }
   }
   

3. Update provider.xml to include the following element for your portlet:

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
   ...
   <portletInstanceClass>oracle.portal.sample.v2.devguide.tx.
        ExportByRefDefaultPortletInstance</portletInstanceClass>
   </portlet>
   

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

7.2.9 Enhancing Portlet Performance with Caching

In the previous sections of this chapter, you learned how to write fully-functional Java portlets using the PDK Framework. Once you complete the basic functionality of your portlet, you may want to turn your attention to portlet performance.

Caching is a common technique for enhancing the performance of Web sites that include a great deal of dynamic content. The overhead involved in retrieving data and generating the output for dynamic content can be significantly reduced by proxying requests through a local agent backed by a large, low-latency data store known as a cache. The cache agent responds to a request in one of two ways, as follows:

• If a valid version of the requested content exists in the cache, the agent simply returns the existing cached copy, thus skipping the costly process of content retrieval and generation. This condition is called a cache hit.

• If a valid version of the requested content does not exist in the cache, the agent forwards the request to its destination and awaits the return of the content. The agent returns the content to the requestor and stores a local copy in its cache for reuse if a subsequent request for the same content arises. This condition is called a cache miss.

Web providers generate dynamic content (that is, portlets) and they often reside remotely from the Oracle Portal instance on which they are deployed. As such, caching might improve their performance. The architecture of Oracle Portal lends itself well to caching, since all rendering requests originate from a single page assembling agent, known as the Parallel Page Engine (PPE), which resides on the middle tier. You can make the PPE cache the portlets rendered by your Web provider and reuse the cached copies to handle subsequent requests, minimizing the overhead your Web provider imposes on page assembly.

The Web provider can use any one of three different caching methods, depending upon which one is best suited to the application. The methods differ chiefly in how they determine whether content is still valid. Following are the three caching methods:

1. Expiry-based Caching: When a provider receives a render request, it stamps its response with an expiry time. The rendered response remains in the cache and fills all subsequent requests for the same content until its expiry time passes. This caching scheme is perhaps the simplest and most performant because the test for cache validity requires very little overhead and does not involve any network round trips. Expiry-based caching suits applications where the content has a well-defined life span. For content with a less certain life span, however, expiry-based caching is less effective. Refer to Section 7.2.9.2, "Activating Caching" and Section 7.2.9.3, "Adding Expiry-Based Caching" for more information.

2. Invalidation-based Caching: Invalidation-based caching works essentially the same way as expiry-based caching, except that the contents of the cache can expire or become invalid at any time. Invalidation of cache content is usually triggered by an event.

   For example, if you have a calendar portlet that shows your appointments for the day, the content for the portlet could be generated once, the first time you show the calendar for that day. The content remains cached until something happens to change your schedule for that day, such as the addition of an appointment, the deletion of an existing appointment, or a change of time for an appointment. Each of these change events can trigger an action in the calendar application. When such an event takes place, your calendar application can generate an invalidation request for any cached portlet content affected by the change. The next time you view a page containing your calendar portlet, the cache will not contain an entry. Your Web provider will be contacted to regenerate the new content with the modified schedule.

   This method is a very efficient way to cache content because the originator of the content, that is, your Web provider, is contacted only when new content needs to be generated, but you are not bound to a fixed regeneration schedule. Refer to Section 7.2.9.2, "Activating Caching" and Section 7.2.9.4, "Adding Invalidation Based Caching" for more information.

3. Validation-based Caching: When a provider receives a render request, it stamps its response with a version identifier (or E Tag). The response goes into the cache, but, before the PPE can reuse the cached response, it must determine whether the cached version is still valid. It sends the provider a render request that includes the version identifier of the cached content. The provider determines whether the version identifier remains valid. If the version identifier is still valid, the provider immediately sends a lightweight response to the PPE without any content, which indicates the cached version can be used. Otherwise, the provider generates new content with a new version identifier, which replaces the previously cached version. In this form of caching, the PPE must always confirm with the provider whether the content is up to date. The validity of the cached copy is determined by some logic in the provider. The advantage of this approach is that the provider controls the use of the cached content rather than relying on a fixed period of time. Refer to Section 7.2.9.2, "Activating Caching" and Section 7.2.9.5, "Adding Validation-Based Caching" for more information.

7.2.9.1 Assumptions

To perform the tasks in these sections, we are making the following assumptions:

1. You have followed through and understood Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper".

2. You built a portlet using the wizard and successfully added it to a page.

7.2.9.2 Activating Caching

To use the caching features of Oracle Portal in your Web providers, you must first activate the middle tier cache. This cache is known as the PL/SQL Cache because it is the same cache used by mod_plsql, the Oracle HTTP Server plug-in that calls database procedures, and hence database providers, over HTTP.

Usually, your OracleAS Portal administrator is responsible for the configuration details of caching.

For invalidation-based caching, you need to configure Oracle Web Cache in front of the Web provider. Bear in mind that remote Web providers often do not have Oracle Web Cache installed. For more information about Oracle Web Cache, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Web Cache.

Once you have installed and configured Oracle Web Cache, ensure the following in the Oracle Web Cache Manager:

• It points to the host name and port of the Web provider.

• Caching rules do not cause the caching of provider content. Content should be cached according to the surrogate control headers generated by the provider in its response.

7.2.9.3 Adding Expiry-Based Caching

Expiry-based caching is one of the simplest caching schemes to implement, and can be activated declaratively in your XML provider definition. You can set an expiry time for the output of any ManagedRenderer you utilize by setting its pageExpires property to the number of minutes you want the output to be cached for. For example, suppose you want portlet output to be cached for one minute. To add expiry-based caching, perform the following steps:

1. After you have used the Portlet Wizard to build a portlet as described in Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper", edit the provider.xml file and set the pageExpires property tag of showPage to 1. This will set an expires entry of 1 minute for the portlet.

   By default the wizard generates a standard and compressed tag for showPage. You need to expand the tag to include a subtag of pageExpires:

   <showPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
      <resourcePath>/htdocs/mycacheportlet/MyCachePortletShowPage.jsp
         </resourcePath>
      <pageExpires>1</pageExpires>
   </showPage>
   

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

2. Test that the portlet is cached for 1 minute by adding some JSP code to your show page. You can simply add the current time to your JSP.

   <%@page contentType="text/html; charset=windows-1252"
      import="oracle.portal.provider.v2.render.PortletRenderRequest"
      import="oracle.portal.provider.v2.http.HttpCommonConstants"
      import="java.util.Date"
      import="java.text.DateFormat"
   %>
   
   <%
    PortletRenderRequest pReq = (PortletRenderRequest)
      request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    DateFormat df = DateFormat.getDateTimeInstance(DateFormat.LONG,
      DateFormat.LONG,pReq.getLocale());
    String time = df.format(new Date());
   %>
   
   <P>Hello <%=pReq.getUser().getName() %>.</P>
   <P>This is the <b><i>Edit</i></b> render mode!</P>
   <P>This information is correct as of <%=time%>.</P>
   

   When viewing the portlet, you see that the time (including seconds) is constant for 1 minute. After the time has expired, the portlet displays the most current time and a new cache is set.

7.2.9.4 Adding Invalidation Based Caching

When using Oracle Web Cache, requests for content are sent using HTTP and content is either returned from the cache or the HTTP request is forwarded to the originator of the content. When content is returned to Oracle Web Cache, it is added to the cache before being returned to the requestor. Cache content is invalidated by sending invalidation requests directly to Oracle Web Cache. PDK-Java uses the Java API for Web Cache (JAWC) to generate invalidation requests. This section describes how to configure Oracle Web Cache and use the invalidation-based caching sample that comes with PDK-Java.

Not all requests sent to Oracle Web Cache are cached. In order for the content to be cached, the content must include directives that tell Oracle Web Cache to cache the content. Usually Oracle Web Cache uses the URL associated with the request as the cache key, but you can specify additional keys by setting special HTTP headers, known as surrogate control headers, on the response.

To configure a Java portlet to use invalidation-based caching, you do the following:

• Configuring Oracle Web Cache. Refer to Oracle Fusion Middleware Administrator's Guide for Oracle Web Cache for more information.

• Section 7.2.9.4.1, "Configuring the Provider Servlet"

• Section 7.2.9.4.2, "Defining the Oracle Web Cache Invalidation Port"

• Section 7.2.9.4.3, "Configuring the XML Provider Definition"

• Section 7.2.9.4.4, "Manually Invalidating the Cache"

7.2.9.4.1 Configuring the Provider Servlet

To enable invalidation-based caching, you must switch it on at the provider servlet level. The flag is set in an initialization parameter inside the PDK-Java Web application deployment descriptor, web.xml. For example:

<servlet>
...
    <servlet-class>oracle.webdb.provider.v2.adapter.SOAPServlet</servlet-class>
    <init-param>
      <param-name>invalidation_caching</param-name>
      <param-value>true</param-value>
    </init-param>
</servlet>

If the flag is not defined here, then invalidation-based caching is switched off. The status of this flag can be checked by displaying the provider's test page. If the testPageURI property is not set in the sample.properties file, then the provider code displays the test page in the old default style. The old style test page correctly picks up the invalidation caching flag from the web.xml file. The format of the test page URL is as follows:

http://provider_hostname:port/jpdk/providers/sample

7.2.9.4.2 Defining the Oracle Web Cache Invalidation Port

If you are using an Oracle Fusion Middleware installation type where PDK-Java was automatically pre-installed (for example, an Oracle Portal and Wireless type installation), you should find that Oracle Web Cache invalidation settings have already been preconfigured in MID_TIER_ORACLE_HOME/portal/conf/cache.xml. In this case, you can safely ignore the instructions in this section and proceed to Section 7.2.9.4.3, "Configuring the XML Provider Definition". Otherwise, you will need to configure the invalidation portlet for Oracle Web Cache.

First, you need the user name and password for the invalidation port(s) of the Oracle Web Cache instance(s) associated with your application server. After you obtain those, use the provided oracle.webdb.provider.v2.cache.Obfuscate Java utility to convert the user name and password into an obfuscated string of the format required by the JAWC API. In a default Oracle Fusion Middleware installation, the user name for the invalidation port is usually invalidator and the password is usually the same as the application server administrator's password. For example, suppose you installed Oracle Fusion Middleware in D:\as904, with an invalidation port user name of invalidator and a password of welcome. You would run the following command:

Note:

The command that follows assumes that pdkjava.jar and jawc.jar are present in ORACLE_HOME/j2ee/home/shared-lib/oracle.jpdk/1.0, as required by the PDK-Java installation guide.

If you are using a standalone Oracle Containers for Java EE installation, you need to substitute in the path to the java executable an external Java 2 SDK installation.

D:\as904\jdk\bin\java -classpath D:\as904\j2ee\home\shared-lib\oracle.jpdk\1.0\pdkjava.jar
  oracle.webdb.provider.v2.cache.Obfuscate invalidator:welcome

If successful, the command should print a hexadecimal string like the following:

0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11

Now, use this information to create a JAWC configuration file, cache.xml, which specifies one or more Oracle Web Cache instances and their invalidation ports. For example:

<?xml version="1.0"?> 
<webcache> 
<invalidation
 host="cache.mycompany.com"
 port="4001"
authorization="0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11"/>
</webcache>

JAWC finds this configuration file using the system property file. To set this system property for a Oracle WebLogic Server, simply add an appropriate line to the .product.properties file for the particular instance in which PDK-Java is installed (for example, MW_HOME/wlserver_10.3/.product.properties) and then restart that instance.

Note:

Since the location of the cache configuration file is defined as a system property, only one cache may be defined for each server instance. It is not possible to have two different Web Provider instances behind separate Oracle Web Cache configurations.

7.2.9.4.3 Configuring the XML Provider Definition

Using a combination of tags in provider.xml, you can activate automatic invalidation-based caching for an entire portlet or some of its pages. To turn on automatic invalidation-based caching, you need to declare it as follows either at the level of individual pages or the renderer, to indicate that invalidation-based caching should be activated for all pages:

<useInvalidationCaching>true</useInvalidationCaching>

If your portlet supports personalization (through the Edit or Edit Defaults modes), you may also want to declare <autoInvalidate>true</autoInvalidate> for your renderer. This declaration causes invalidation of all the cached content for the portlet when you click OK or Apply in Edit mode, thus causing new markup to be generated based on the personalized settings.

The maximum time for holding the page in the cache is the minimum of the following:

• Maximum expiry time from Oracle Portal defined in the Cache tab of the Global Settings page.

• Web Provider default (24 hours) if no maximum expiry time is specified by Oracle Portal.

• The time in minutes of the <pageExpires> tag, if present.

The following excerpt from provider.xml specifies that this portlet shall be cached for up to 5 minutes and shall be automatically invalidated upon personalization:

<renderer class="oracle.portal.provider.v2.render.RenderManager">
 <contentType>text/html</contentType>
 <renderContainer>true</renderContainer>
 <autoRedirect>true</autoRedirect>
 <autoInvalidate>true</autoInvalidate>
 <showPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
  <resourcePath>/htdocs/invalidation/invalidation1.jsp</resourcePath>
  <useInvalidationCaching>true</useInvalidationCaching>
  <pageExpires>5</pageExpires>
 </showPage>
 <editPage class="oracle.portal.sample.v2.devguide.invalidation.
   InvalidationEditRenderer"/></renderer>

Note:

The pageExpires tag is also used for normal expiry based caching. These two forms of caching are mutually exclusive. Invalidation-based caching takes place in an Oracle Web Cache instance located in the same place as the Web provider. Pages stored using expiry based caching are cached in the middle tier of Oracle Portal.

For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

7.2.9.4.4 Manually Invalidating the Cache

You may want the cached version of the portlet invalidated when a request is processed or information somewhere has been updated. In these cases, you may want to manually invalidate the cache.

The invalidation-based caching portlet sample included with PDK-Java contains a single portlet that displays the time the content was cached and a link to trigger an invalidation request. The first time a page request is made to the Web provider through the cache, the response is cached. Subsequent requests for the portlet content are fulfilled by returning content from Oracle Web Cache. When you click the link at the bottom of the portlet an invalidation request is generated by the provider that removes the portlet from the cache. The next request for the portlet is forwarded to the provider and the provider generates a new portlet with the current time.

To perform invalidation calls to Oracle Web Cache, first you need to have a handle to a ServletInvalidationContext object. You can get this handle by calling the static getServletInvalidationContext() method of the ServletInvalidationContextFactory class.

Once you have the handle, you need to specify the cache key. In the cache key, you need to specify whether you want to invalidate a particular portlet instance, all the instances of a portlet, or all the portlets managed by a provider. To perform this task, you use the methods of the ServletInvalidationContext class or the methods of its super class, InvalidationContext. This is where you can specify whether the portlet should be cached for this particular user (USER level). If there is no user specified in the cache key, then the cached content is returned to all users, which means you are using SYSTEM level caching.

The following example invalidates a portlet instance and calls the setFullProviderPath() and setPortletReference() methods. When the caching key is set, you call the invalidate() method on the InvalidationContext object that sends the invalidation message to Oracle Web Cache.

ServletInvalidationContext inv = 
  ServletInvalidationContextFactory.getServletInvalidationContext();
inv.setFullProviderPath
  ((ServletPortletRenderRequest)pReq);
inv.setPortletReference
  (pReq.getPortletReference());
int num = inv.invalidate();

Review the Web cache sample provider for more information.

7.2.9.5 Adding Validation-Based Caching

Adding validation-based caching requires slightly more effort, but gives you explicit control over exactly which requests to your provider are cache hits. As an example, you may want to update the cache only when data within the portlet has changed. To implement this algorithm, you need to override the prepareResponse method. The signature of the BaseManagedRenderer.prepareResponse method is:

public boolean prepareResponse(PortletRenderRequest pr)
                        throws PortletException,
                               PortletNotFoundException

In your version of prepareResponse(), you need to do the following:

• Retrieve the cached version identifier set by the PPE in the render request by calling the HttpPortletRendererUtil.getCachedVersion() method:

  public static java.lang.String getCachedVersion
      (PortletRenderRequest request)
  

• If the portlet finds the previously cached version valid, the appropriate header has to be set by calling the HttpPortletRendererUtil.useCachedVersion() method. It also instructs the RenderManager that it won't be necessary to call renderBody() to render the portlet body.

  public static void useCachedVersion(PortletRenderRequest request)
  

  Otherwise, use HttpPortletRendererUtil.setCachedVersion() to generate a new version of the portlet, which will be cached. It also indicates to the PPE that the renderBody() method has to be called to regenerate the portlet content.

  public static void setCachedVersion(PortletRenderRequest request,
                                      java.lang.String version,
                                      int level)
                               throws java.lang.IllegalArgumentException
  

For validation-based caching, you need not update provider.xml. You can view the portlet by refreshing the page or adding the portlet to a page and updating the content. If the content has changed, the portlet shows the new content. If the content has not changed, a cached version of the portlet is displayed.

7.2.10 Enhancing Portlets for Mobile Devices

This section explains how to go about enhancing a PDK-Java portlet for a mobile device. Before proceeding with this section, you should familiarize yourself with the guidelines for building mobile-enabled portlets, Section 6.1.4, "Guidelines for Mobile Portlets", and the methods of building portlets with PDK-Java, Section 7.2, "Enhancing PDK-Java Portlets".

To properly build a portlet for a mobile device, do the following:

1. Create a JSP to generate the OracleAS Wireless XML in response to the show request for the portlet. The portlet's JSPs are managed and controlled by the built in renderer, oracle.portal.provider.v2.render.http.ResourceRenderer.

   With this renderer, you can define distinct resources (JSPs) for each Show mode as well as which JSP to call for each Show mode. Hence, you can define one JSP to handle the Show mode when the requested content is HTML and another when the requested content is OracleAS Wireless XML. For example, this capability enables you to put the lottery portlet's mobile rendition in a separate JSP. In this sample, mlotto.jsp generates the mobile rendition.

   Note the contentType declaration in the first line of the source code. The content type of the JSPs response is set to text/vnd.oracle.mobilexml. This is the MIME type name for OracleAS Wireless XML. All mobile responses must set their content type to this value to work properly.

   <%@ page session="false" contentType="text/vnd.oracle.mobilexml" %>
   <%@ page import="oracle.portal.sample.v2.devguide.lottery.LottoPicker" %>
   <% LottoPicker picker = new LottoPicker();
      picker.setIdentity(request.getRemoteAddr() ); %>
   <SimpleText>
       <SimpleTextItem />
       <SimpleTextItem>Your numbers:</SimpleTextItem>
       <SimpleTextItem />
       <SimpleTextItem HALIGN="CENTER" >
           <%
           int [] picks = picker.getPicks();
           for (int i = 0; i < picks.length; i++) {
               out.print(picks[i] + " ");
           }
           out.println("");
           %>
       </SimpleTextItem>
   </SimpleText>
   

2. Modify provider.xml by adding the acceptContentType tag in the portlet definition to indicate that the portlet can generate OracleAS Wireless XML responses. Each acceptContentType tag defines a distinct content type that the portlet can render. The value is the MIME type of the content. In this case the lottery portlet declares that it can generate HTML (text/html) and OracleAS Wireless XML (text/vnd.oracle.mobilexml).

   <acceptContentType>text/html</acceptContentType>
   <acceptContentType>text/vnd.oracle.mobilexml</acceptContentType>
   

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

3. Declare the mapping of JSP renderers to Show modes in provider.xml.

   You need to define a render handler for the pertinent Show modes by content type. One showPage declaration identifies a JSP that renders the HTML response and another one identifies the JSP that renders the OracleAS Wireless XML response. Note that the class attribute is now required, whereas, in a simpler case, it could allow the class to default. You express the association of a particular JSP to a particular content type through the resourcePath and contentType tags inside the showPage declaration as follows:

   • resourcePath defines the JSP used to render this mode.

   • contentType defines the response type of this JSP.

   When the ResourceRenderer receives a show request for the lottery portlet it invokes lotto.jsp to render the HTML response and mlotto.jsp for OracleAS Wireless XML. The following code illustrates how you express this relationship in provider.xml:

   <renderer class="oracle.portal.provider.v2.render.RenderManager">
      <contentType>text/html</contentType>
      <renderContainer>true</renderContainer>
      <showPage
         class="oracle.portal.provider.v2.render.http.ResourceRenderer">
         <resourcePath>/htdocs/lottery/lotto.jsp</resourcePath>
         <contentType>text/html</contentType>
      </showPage>
      <showPage
         class="oracle.portal.provider.v2.render.http.ResourceRenderer">
         <resourcePath>/htdocs/lottery/mlotto.jsp</resourcePath>
         <contentType>text/vnd.oracle.mobilexml</contentType>
      </showPage>
      ...
   </renderer>
   

   Note:

   The ResourceRenderer (and any portlet) determines the type of request it has received by the request's Accept header. The Accept header is a standard HTTP header that defines the acceptable response types for a given request. It may be a list with multiple values if multiple content types are acceptable. When there are multiple values, they are listed in order from most to least preferred. Oracle Portal controls the values passed to the portlet in the Accept header. In the case of an HTML request, the Accept header is:

   text/html, text/xml, text/vnd.oracle.mobilexml
   

   These values indicate that Oracle Portal prefers an HTML response but also accepts XML and OracleAS Wireless XML.

   For mobile requests, the Accept header is:

   text/vnd.oracle.mobilexml, text/xml
   

   These values indicate that Oracle Portal prefers OracleAS Wireless XML but also accepts general XML that contains a stylesheet reference that transforms to OracleAS Wireless XML.

   The ResourceRenderer maps requested content type to the specific resource renderer by working through the Accept list in preference order. Once it finds a match between an acceptable response type and a registered renderer, it dispatches the request to the resource. For example, for HTML requests the ResourceRenderer will match the first entry, text/html, to the declaration that defines lotto.jsp as the text/html handler. Likewise, when a mobile request is received, the ResourceRenderer matches the first entry, text/vnd.oracle.mobilexml, to the declaration that defines mlotto.jsp as the text/vnd.oracle.mobilexml handler.

4. Declare a short title. A short title is the short form of a portlet's name and is for use where display space is limited. Specifically, Oracle Portal uses it when rendering portlets as menu items in the page menu generated in response to a mobile request. If the portlet has registered a short title, Oracle Portal uses that as the menu item label. Otherwise, it uses the portlet's standard title. To declare a short title, you include the shortTitle tag in the portlet's metadata section in provider.xml:

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>2</id>
      <name>Lottery</name>
      <title>Lottery Portlet</title>
      <shortTitle>Lottery</shortTitle>
      ...
   </portlet>
   

5. Support short title personalization. Because the portlet's short title is presented to the user as the menu item label that references the portlet instance on the page, we recommend that all portlets allow users to personalize the short title. PDK-Java provides a base data class that manages both the short and standard title:

   oracle.portal.provider.v2.personalize.NameValuePersonalizationObject
   

   The NameValuePersonalizationObject manages both the title and short title. It contains methods for getting and setting the values. The personalization code is split into two parts, form display and form submit. The logic first acquires the current data personalization object. Next, it checks to see if this is a form submit. If so, it updates the values in the data personalization object, writes them back to the repository, and returns. PDK-Java subsequently redirects back to this same form but without the parameters that indicate it is a form submit causing the form to redisplay with the new values. In this situation, the JSP responds with the personalization page including the current personalization values.

   We recommend that portlets use this class or subclass to inherit this base support. The only personalization the lottery sample supports is these two titles. Hence, it uses the NameValuePersonalizationObject class directly in custom.jsp:

   <%@ page session="false" import="oracle.portal.provider.v2.*" %>
   <%@ page import="oracle.portal.provider.v2.http.*" %>
   <%@ page import="oracle.portal.provider.v2.render.*" %>
   <%@ page
     import="oracle.portal.provider.v2.personalize.NameValuePersonalizationObject"
   %>
   <%-- This page both displays the personalization form and processes it.
        We display the form if there isn't a submitted title parameter,
        else we apply the changes --%>
   <%
       PortletRenderRequest portletRequest = (PortletRenderRequest)
           request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
       String title = request.getParameter("lotto_title");
       String sTitle = request.getParameter("lotto_short_title");
       String actionParam =
   PortletRendererUtil.getEditFormParameter(portletRequest);
       String action = request.getParameter(actionParam);
       NameValuePersonalizationObject data = (NameValuePersonalizationObject)
           PortletRendererUtil.getEditData(portletRequest);
       // Cancel automatically redirects to the page
       //   -- so will only receive 'OK' or 'APPLY'
       if (action != null) {
           data.setPortletTitle(title);
           data.setPortletShortTitle(sTitle);
           PortletRendererUtil.submitEditData(portletRequest, data);
           return;
       }
       // otherwise just render the form
       title = data.getPortletTitle();
       sTitle = data.getPortletShortTitle();
   %>
   <TABLE BORDER="0">
       <TR>
           <TD WIDTH="20%">
               <P ALIGN="RIGHT">Title:
           </TD>
           <TD WIDTH="80%">
               <INPUT TYPE="TEXT" NAME="lotto_title" 
                      VALUE="<%= title %>" SIZE="20">
           </TD>
       </TR>
       <TR>    
       <TD WIDTH="20%">
           <P ALIGN="RIGHT">Short Title:
       </TD>
       <TD WIDTH="80%">
           <INPUT TYPE="TEXT" NAME="lotto_short_title" VALUE="<%= sTitle %>"
              SIZE="20" MAXLENGTH="20">
       </TD>
       </TR>
   </TABLE>
   

6. Support the rendering of personalized short titles. Once you add short title personalization, a portlet must take responsibility for rendering the portlet as a menu item in the mobile page response. Because of the small screen displays on mobile devices, portlets aren't rendered together. Users are presented with a menu of links to portlets on a given page. The user navigates to each portlet through this menu to see the content. To better support this model, Oracle Portal provides Link mode, where portlets generate Link references to themselves.

   For HTML requests, Link mode generates an anchor tag, a href. For mobile requests, Link mode generates a simpleHref tag. Currently, Oracle Portal only sends a Link mode request when assembling a mobile page response. Hence, you only need to support rendering the text/vnd.oracle.mobilexml content type for Link mode. If your portlet also has an HTML rendition, we recommend you also support HTML Link mode.

   The lottery portlet example implements each Link rendition in a distinct JSP, as follows:

   • milotto.jsp contains the code to generate a text/vnd.oracle.mobilexml Link response.

   • anchorlotto.jsp contains the code to generate a text/html Link response.

   The code for each is almost identical. Since the purpose of supporting Link mode is to render the personalized short title, the code first acquires the short title from the repository. It then generates the appropriate link tag for the requested markup. The acquired short title is rendered as the link's label. Since Oracle Portal is responsible for creating the URL that references any particular usage of a portlet on a page, Oracle Portal creates the URL used in the link and passes it to the portlet, which then uses the URL to create the link. The URL for the link is retrieved from the request's PageURL parameter. The code for milotto.jsp is as follows:

   <%@ page session="false" contentType="text/vnd.oracle.mobilexml" %>
   <%@ page import="oracle.portal.provider.v2.http.HttpCommonConstants" %>
   <%@ page import="oracle.portal.provider.v2.render.*" %>
   <%@ page
     import="oracle.portal.provider.v2.personalize.NameValuePersonalizationObject"
   %>
   <%@ page import="oracle.portal.utils.xml.v2.XMLUtil" %>
   <%
       PortletRenderRequest portletRequest = (PortletRenderRequest)
           request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
       NameValuePersonalizationObject data = (NameValuePersonalizationObject)
           PortletRendererUtil.getEditData(portletRequest);
       String title = data.getPortletShortTitle();
       // if short title is empty then use the title
       if (title == null || title.length() == 0)
           title = data.getPortletTitle();
   %>
   <SimpleHref target="<%= XMLUtil.escapeXMLAttribute(
            portletRequest.getRenderContext().getPageURL()) %>">
      <%= XMLUtil.escapeXMLText(title) %>
   </SimpleHref>
   

   Note:

   The text being output as the URL and the short title label are passed through special XML escape utilities. Because text/vnd.oracle.mobilexml is an XML content type, generated responses must adhere to XML rules, which require the escaping of specific characters. Unless generating static text, we recommend that all text be escaped using the two supplied utilities. The reason for two utility methods is that the set of characters requiring escape varies depending upon whether the text is a tag attribute value or a tag value.

7. Declare support for Link mode. Once you have implemented Link mode, you must update provider.xml to indicate the presence of Link mode. You declare Link mode by adding code similar to the following to provider.xml:

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>2</id>
      <name>Lottery</name>
      ...
      <showLink>true</showLink>
      <showEdit>true</showEdit>
      <showEditToPublic>false</showEditToPublic>
      ...
   </portlet>
   

8. Bind the JSPs to the Link mode. The portlet must declare the mapping between the Show modes and the JSP renderers. The syntax for Link mode is similar to that for Show mode.

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>2</id>
      <name>Lottery</name>
      ...
      <renderer class="oracle.portal.provider.v2.render.RenderManager">
         <contentType>text/html</contentType>
         <renderContainer>true</renderContainer>
         <linkPage
            class="oracle.portal.provider.v2.render.http.ResourceRenderer" >
            <resourcePath>/htdocs/lottery/anchorlotto.jsp</resourcePath>
            <contentType>text/html</contentType>
         </linkPage>
         <linkPage
            class="oracle.portal.provider.v2.render.http.ResourceRenderer" >
            <resourcePath>/htdocs/lottery/milotto.jsp</resourcePath>
            <contentType>text/vnd.oracle.mobilexml</contentType>
         </linkPage>
        ...
      </renderer>
      ...
   </portlet>
   

7.2.10.1 Accessing Configuration, User, and Device Information

To better support mobile devices, Oracle Portal passes extra information to the portlet for use in generating its response. This information falls into three major categories, as follows:

• Section 7.2.10.1.1, "Configuration Data"

• Section 7.2.10.1.2, "User Data"

• Section 7.2.10.1.3, "Device Information"

7.2.10.1.1 Configuration Data

Oracle Portal sends a flag that indicates whether the mobile function is enabled when requesting that the portlet render its personalization or edit pages. Portlets can use this information to exclude or include mobile specific attributes in their personalization pages as appropriate.

The portlet accesses this information using the PortletRenderRequest object:

...
if (portletRequest.getPortalConfig().isMobileEnabled()) {
...
}
...

7.2.10.1.2 User Data

OracleAS Wireless adds the user location to the requests it forwards to Oracle Portal for response. This user location information is determined by the user's actual location, if the user's device has this support, or a profiled location. The user location is exposed by the ProviderUser object, which you can access from the PortletRenderRequest object. Portlets that are location aware can use this information to adjust the content they generate.

...
UserLocation location = portletRequest.getUser().getLocation();
if (location != null) {
   ...
}
...

7.2.10.1.3 Device Information

On each request, Oracle Portal sends characteristics about the requesting device to the portlet. This information is sent for all portlet requests, not just mobile requests. The information classifies the type of device making the request, its layout orientation, the maximum response size the device can handle, and an indication of whether the connection with the device is secure. Table 7-3 describes the available device types.

Table 7-3 Device Classes

Class	Description
voice	Indicates a voice-only device, such as a normal telephone calling a voice access number.
micromessenger	Indicates text messenging devices, such as SMS phones or pagers.
messenger	Indicates general messenging devices, such as e-mail.
microbrowser	Indicates a small size display device, which supports a markup browser, such as a WAP phone.
pdabrowser	Indicates a medium size display device, such as a Palm or PocketPC.
pcbrowser	Indicates a large size display device used with desktop browsers.

Portlets may choose to alter the layout or representation of the content in their response based on the type of device making the request. For example, a portlet may break a wide table into a series of screens that link column groups together for small screen devices.

The maximum response size is a hint that a portlet can use to constrain the amount of data it returns. The size is expressed in bytes. A maximum response size of 0 means the size is unknown.

The portlet accesses this information using the PortletRenderRequest object.

...
DeviceInfo deviceInfo = portletRequest.getDeviceInfo();
switch (deviceInfo.getDeviceClass()) {
    case DeviceInfo.DeviceClass.MICROBROWSER:
        renderMicroBrowser(portletRequest);
        break;
    default:
        renderDefault(portletRequest);
        break;
}
...

7.2.10.2 Modifying Navigation for Mobile Portlets

Much of the information in Section 7.2.3.3.4, "Implementing Navigation within a Portlet" is also relevant to the development of mobile portlets, but some of the utilities referenced are specific to portlets that render HTML. For portlets that render SimpleResult, the equivalent utilities shown in Table 7-4 are available.

Table 7-4 Equivalent HTML and SimpleResult Utilities

HTML Utilities	SimpleResult Utilities
UrlUtils.constructHTMLLink	UrlUtils.constructMXMLLink
UrlUtils.htmlFormHiddenFields	UrlUtils.mxmlFormHiddenFields
UrlUtils.emitHiddenField	UrlUtils.emitMxmlHiddenField

The following example illustrates how to adapt the thesaurus sample for a mobile-enabled portlet. Note that, when deployed as a mobile portlet, both sets of JSPs (HTML and SimpleResult) are deployed. These JSPs complement their HTML counterparts, they do not replace them. Notice also that the JSPs use SimpleResult as their markup and the value of the navigation parameter has changed such that it points to the next mobile JSP rather than the next desktop JSP.

mThesaurusForm.jsp:

<%
    PortletRenderRequest pRequest = (PortletRenderRequest)
        request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String paramNameQ = "q";
    String qualParamNameQ =
        HttpPortletRendererUtil.portletParameter(pRequest, paramNameQ);
%>
<!-- Output the MXML content -->
<SimpleText>
    <SimpleTitle>Thesaurus</SimpleTitle>
    <SimpleTextItem>Enter the word you wish to search for:</SimpleTextItem>
    <SimpleForm 
        method="POST" 
        target="<%= UrlUtils.htmlFormActionLink(pRequest,UrlUtils.PAGE_LINK) %>"> 
        <%=UrlUtils.mxmlFormHiddenFields
           (pRequest.getRenderContext().getPageURL()) %>
        <%= UrlUtils.emitMxmlHiddenField(
                HttpPortletRendererUtil.portletParameter(request, "next_page"),
                "htdocs/path/mThesaurusLink.jsp" ) %>
        <SimpleFormItem type="text" size="20" name="<%= qualParamNameQ %>"
                 value="" />
    </SimpleForm>
</SimpleText>

mThesaurusLink.jsp:

<%
    PortletRenderRequest pRequest = (PortletRenderRequest)
        request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String paramNameQ = "q";
    String paramNameNextPage = "next_page";
    String qualParamNameQ = 
    HttpPortletRendererUtil.portletParameter(pRequest, paramNameQ);
    String qualParamNameNextPage = 
        HttpPortletRendererUtil.portletParameter(pRequest, paramNameNextPage);
    String paramValueQ = pRequest.getQualifiedParameter(paramNameQ);
%>
<!-- Output the MXML content -->
<SimpleText>
    <SimpleTitle>Words similar to <%= paramValueQ %></SimpleTitle>
<%
        Thesaurus t = new Thesaurus();
        String[] relatedWords = t.getRelatedWords(paramValueQ);
        NameValue[] linkParams = new NameValue[2]; 
        linkParams[0] = new NameValue(
            qualParamNameNextPage, "htdocs/path/mThesaurusLink.jsp");
        for (int i=0; i<relatedWords.length; i++)
        {
            linkParams[1] = new NameValue(
                qualParamNameQ, relatedWords[i]);
%>
        <SimpleTextItem>
                <%= relatedWords[i] %>
                <SimpleBreak/>
                <%= UrlUtils.constructMXMLLink(
                    pRequest,
                    pRequest.getRenderContext().getPageURL(),
                    "(words related to " + relatedWords[i] + ")",
                    "",
                    linkParams,
                    true,
                    true)%>
        </SimpleTextItem>
<%
        }
%>
    <SimpleTextItem>
        <SimpleHref target="<%=XMLUtil.escapeXMLAttribute(
            pRequest.getRenderContext().getPageURL())%>">
            Reset Portlet
        </SimpleHref>
    </SimpleTextItem>
</SimpleText>

7.2.11 Writing Multilingual Portlets

This section shows you how to build a Java portlet that can be rendered in different languages. The language used in your portlet will depend upon on the language setting that has been chosen in the portal that is displaying it.

Once you have completed this section you will be able to write portlets that support as many or as few languages as you wish. You will also be able to convert your existing portlets to support multiple languages. Once a portlet is written to support multiple languages, it is easy to plug in new languages. The basic model for multilingual Java portlets is similar to the standard Java Internationalization model. If you already know about Java Internationalization, you should find this process very familiar.

7.2.11.1 Assumptions

To perform the tasks in this section, we are making the following assumptions:

1. You have followed through and understood Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper".

2. You built a portlet using the wizard and successfully added it to a page.

7.2.11.2 Internationalizing Your Portlet

This consists of the following two tasks:

• Section 7.2.11.2.1, "Providing Translations for Portlet Content"

• Section 7.2.11.2.2, "Providing Translation for Portlet Attributes"

7.2.11.2.1 Providing Translations for Portlet Content

In Section 6.5, "Building Oracle PDK-Java Portlets with Oracle JDeveloper", you created a portlet using the Java Portlet Wizard. The basic message created by the wizard is only available in one language and the text displayed is hard-coded in to the portlet's renderer class. To make your portlets available in multiple languages, you have to store such language dependent elements in their own resource bundles.

Creating Resource Bundles

For each language you want your portlet to be available in, you will need a resource bundle. You will also need to create a resource bundle to use when there is no resource bundle corresponding to the language setting chosen in the portal. Perform the following tasks:

• Create a Default Resource Bundle

  Perform the following steps:

  1. In Oracle JDeveloper, create a Java class called MyProviderBundle that extends ListResourceBundle from the java.util.package. The class should contain a multi-dimensional array of objects that holds key-value pairs representing each of the language dependent elements from your JSP show page. This implementation is demonstrated in the following code:

     package mypackage2;
     import java.util.ListResourceBundle;
     public class MyProviderBundle extends ListResourceBundle
     {
     public static String HELLO_MSG = "MyPortletHelloMessage";
     public static String INFO_MSG = "MyPortletInfoMessage";
     public Object[][] getContents()
     {
     return contents;
     }
     static private final Object[][] contents =
     {
     {HELLO_MSG, "Hello"},
     {INFO_MSG, "This is the show page of the portlet and it is being generated in the default language!"}
     };
     }
     

  2. Save MyProviderBundle.

• Creating Resource Bundles for Other Supported Languages

  Now you must create a resource bundle class for each language you want your portlet to support. Each of these classes must be named the same as your default resource bundle class, but with a language code appended to the end. For example, if you want to support the French language, create a Java class named MyProviderBundle_fr. The language code fr is the same as the code that will be used by the locale object in the portal if the language setting is set to French

  
  

  For more information on Locales, search for java.util.Locale in the Javadoc. Refer to the Javadoc on OTN by clicking Java Doc API on the Portlet Development page available at

  http://www.oracle.com/technology/products/ias/portal/portlet_development_10g1014.html
  

  When you change the language setting in Oracle Portal, you change the value of the current locale object and therefore the locale object's language code. These language codes adhere to the ISO:639 codes for representation for names of languages. To create resource bundles for other supported languages, perform the following steps:

  1. To create a French resource bundle, create a Java class named MyProviderBundle_fr, as described earlier.

  2. Using your default resource bundle as a template, replace the English language strings with their French equivalents. An example is as follows:

     package mypackage2;
     
     import java.util.ListResourceBundle;
     public class MyProviderBundle_fr extends
     ListResourceBundle
     {
     public Object[][] getContents()
     {
     return contents;
     }
     static private final Object[][] contents =
     {
     {MyProviderBundle.HELLO_MSG, "Bonjour"},
     {MyProviderBundle.INFO_MSG, "Cette page est le 'show mode' de la portlet
         et est generee dans la langue par defaut."}
     };
     }
     

  3. Save MyProviderBundle_fr.

  4. Repeat steps 1 through 3 for every language that you wish to create a resource bundle for, updating the class name with the appropriate language code and the message strings with their equivalent in the appropriate language.

Updating Your Renderer

To make use of the resource bundles you just created, you need to edit the JSP show page and replace the hard-coded messages with references that will pickup the messages at run time from the resource bundle that corresponds most closely with the locale object of the portal. To update your renderer, perform the following steps:

1. Open the JSP that represents your show page and change the following:

   <%@page contentType="text/html; charset=windows-1252"
      import="oracle.portal.provider.v2.render.PortletRenderRequest"
      import="oracle.portal.provider.v2.http.HttpCommonConstants"
      import="java.util.ResourceBundle"
   %>
   
   <%
    PortletRenderRequest pReq = (PortletRenderRequest)
      request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
   
   <!-- Get a resource bundle object for the current language. -->
   ResourceBundle b = ResourceBundle.getBundle("mypackage2.MyProviderBundle",pReq.getLocale());
   %>
   
   <!--  Pull the message from the appropriate resource bundle. -->
   <P> <%= b.getString(mypackage2.MyProviderBundle.HELLO_MSG) %> 
      <%= pReq.getUser().getName() %>.</P>
   <P> <%= b.getString(mypackage2.MyProviderBundle.INFO_MSG) %></P>
   

2. Save your JSP page.

Now you can refresh your portlet and view the changes (Figure 7-12).

Figure 7-12 Portlet in English

Description of "Figure 7-12 Portlet in English"

To view the French greeting, you set the language in the Set Language portlet to French instead of English (Figure 7-13).

Figure 7-13 Portlet in French

Description of "Figure 7-13 Portlet in French"

Notice that the text inside the portlet has changed, but the portlet title remains in the default language, English. You can also have the portlet set the appropriate portlet attributes (such as portlet name, portlet title, and portlet description) by pointing to a resource bundle from provider.xml, as described in the next section.

7.2.11.2.2 Providing Translation for Portlet Attributes

In your provider's definition file, provider.xml, a number of attributes describing your portlet are defined such as the portlet's name and description, these are used in places, for example in your portlet's title bar in Show mode and so should be translated, too. There are two different ways of providing these translations, which one you choose is up to you. Both of these methods are outlined in the following sections:

• "Method 1: Using Resource Bundles at the Provider Level"

• "Method 2: Creating Resource Bundles at Portlet Level"

Method 1: Using Resource Bundles at the Provider Level

You can provide translations for your portlet attributes in your resource bundle(s), then specify that you want to use these resource bundles in provider.xml, specifying the keys you have used in your resource bundles. Using this method you can use the keys you want to, and as long as you use different keys for each corresponding attribute in your provider's various portlets you can have just one set of resource bundles that all of your provider's portlets can use. This section consists of the following tasks:

• Updating Your Resource Bundles

  Perform the following steps:

  1. Open your default resource bundle, MyProviderBundle.java.

  2. Add additional strings to your resource bundle that represent your portlet attributes and then add text for those strings:

     package mypackage2;
     
     import java.util.ListResourceBundle;
     public class MyProviderBundle extends ListResourceBundle
     {
     public static String HELLO_MSG = "MyPortletHelloMessage";
     public static String INFO_MSG = "MyPortletInfoMessage";
     public static String PORTLET_NAME = "FirstPortletName";
     public static String PORTLET_TITLE = "FirstPortletTitle";
     public static String PORTLET_SHORT_TITLE = "FirstPortletShortTitle";
     public static String PORTLET_DESCRIPTION = "FirstPortletDescription";
     public static String TIMEOUT_MESSAGE = "FirstPortletTimeoutMessage";
     
     public Object[][] getContents()
     {
     return contents;
     }
     static private final Object[][] contents =
     {
     {HELLO_MSG, "Hi"},
     {INFO_MSG, "This is the show page of the portlet and it is being generated
        in the default language!"},
     {PORTLET_NAME, "MyNLSPortlet"},
     {PORTLET_TITLE, "My NLS Portlet"},
     {PORTLET_SHORT_TITLE, "MyNLSPortlet"},
     {PORTLET_DESCRIPTION, "My first ever NLS portlet, using my
        MyPortletShowPage.jsp"},
     {TIMEOUT_MESSAGE, "Timed out waiting for MyNLSPortlet"}
     };
     }
     

  3. Save MyProviderBundle.java.

  4. Open MyProviderBundle_fr.java. Change it so that it contains the French strings that match the strings declared in MyProviderBundle.

     package mypackage2;
     
     import java.util.ListResourceBundle;
     public class MyProviderBundle_fr extends ListResourceBundle
     {
     public Object[][] getContents()
     {
     return contents;
     }
     static private final Object[][] contents =
     {
     {MyProviderBundle.HELLO_MSG, "Bonjour"},
     {MyProviderBundle.INFO_MSG, "Cette page est le 'show mode' de la portlet
        et est generee en francais!"},
     {MyProviderBundle.PORTLET_NAME, "MaPremierePortlet"},
     {MyProviderBundle.PORTLET_TITLE, "Ma Portlet Multi-Langue"},
     {MyProviderBundle.PORTLET_SHORT_TITLE, "Ma NLS Portlet"},
     {MyProviderBundle.PORTLET_DESCRIPTION, "Ma premiere portlet
        multi-langue, utilisant mon renderer"},
     {MyProviderBundle.TIMEOUT_MESSAGE, "Temps d'acces a la portlet 
        demandee expire"}
     };
     }
     

  5. Save MyProviderBundle_fr.java.

• Updating provider.xml

  Perform the following steps:

  1. Open the XML provider definition file and update it to point to the resource bundle instead of using the hard-coded portlet attribute values.

     <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>3</id>
      <resource>mypackage2.MyProviderBundle</resource>
      <nameKey>FirstPortletName</nameKey>
      <titleKey>FirstPortletTitle</titleKey>
      <ShortTitleKey>FirstPortletShortTitle</ShortTitleKey>
      <descriptionKey>FirstPortletDescription</descriptionKey>
     <timeout>10</timeout>
      <timeoutMessageKey>FirstPortletTimeoutMessage</timeoutMessageKey>
      <showEditToPublic>false</showEditToPublic>
      <hasAbout>true</hasAbout>
     

     
     

     For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

     http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
     

Method 2: Creating Resource Bundles at Portlet Level

PDK-Java defines a set of resource bundle keys that you can use for providing translations for your portlet attributes. Making use of these keys means that you don't have to specify the resource bundle keys in your provider.xml file, as we did in "Method 1: Using Resource Bundles at the Provider Level". However, you do have to provide a separate set of resource bundles for each portlet in your provider as the keys you use for each portlet need to be the same, but their values will differ. You must perform the following tasks:

• Updating Your Resource Bundles

  Perform the following steps:

  1. Open your default resource bundle, MyProviderBundle.java.

  2. Remove any changes you made from the previous section, and import oracle.portal.provider.v2.PortletConstants. You can then reference the following constants instead of the strings. You do not have to declare static strings when using PortletConstants:

     {PortletConstants.NAME, "MyNLSPortlet"},
     {PortletConstants.TITLE, "My NLS portlet"},
     {PortletConstants.SHORTTITLE, "MyNLSPortlet"},
     {PortletConstants.DESCRIPTION, "My first ever NLS portlet"},
     {PortletConstants.TIMEOUTMSG, "Timed out waiting for MyNLSPortlet"}
     

  3. Save MyProviderBundle.java.

  4. Open MyProviderBundle_fr.java. Remove the portlet attributes added in the previous section, import oracle.portal.provider.v2.PortletConstants, and reference the constants instead of the strings.

     {PortletConstants.NAME, "MaPremierePortlet"},
     {PortletConstants.TITLE, "Ma Portlet Multi-Langue"},
     {PortletConstants.SHORTTITLE, "Ma NLS Portlet"},
     {PortletConstants.DESCRIPTION, "Ma premiere portlet multi-langue,
        utilisant mon renderer"},
     {PortletConstants.TIMEOUTMSG, "Temps d'acces a la portlet demandee
        expire"}
     

  5. Save MyProviderBundle_fr.java.

• Updating provider.xml

  Perform the following steps:

  1. In provider.xml, you need to use only one tag instead of one tag for each string as you did in "Method 1: Using Resource Bundles at the Provider Level". Delete all translated strings in the file, for example, the <nameKey>, <titleKey>, <ShortTitleKey>, and <descriptionKey> tags. Then add the following tag between the portlet id and the timeout number value:

     <resource>mypackage2.MyProviderBundle</resource>
     

     
     

     For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

     http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
     

  For more information on Java Internationalization see the Internationalization trail of the Java Tutorial.

7.2.11.3 Viewing the Portlet

Once you have updated your provider and deployed it to Oracle Containers for Java EE, refresh the provider and portal page containing your portlet. To see your resource bundles working, add the "Set Language" portlet to your page and try changing the language setting to French. Remember that the default resource bundle is English, and that selecting any other language that doesn't have a corresponding resource bundle will result in the portlet being displayed in English.

7.3 Building Struts Portlets with Oracle JDeveloper

This section describes the framework for building Struts portlets with Oracle JDeveloper for use in Oracle Portal. You will learn how to build a Struts portlet from an existing application by adding the Struts Tag Library from the Oracle Portal Developer Kit (version 9.0.4.0.2 or higher) to Oracle JDeveloper, then use the Oracle PDK Java Portlet wizard to create the Java portlet itself. This sections covers the following tasks:

• Section 7.3.1, "Oracle Portal and the Apache Struts Framework"

• Section 7.3.2, "Creating a Struts Portlet"

7.3.1 Oracle Portal and the Apache Struts Framework

This section discusses the use of the Apache Struts with Oracle Portal. Struts is an implementation of the Model-View-Controller (MVC) design pattern. The following topics are discussed in this section:

• Section 7.3.1.1, "Model View Controller Overview"

• Section 7.3.1.2, "Apache Struts Overview"

• Section 7.3.1.3, "Oracle Portal Integration with Struts"

• Section 7.3.1.4, "Summary"

7.3.1.1 Model View Controller Overview

Enterprise applications undertake several distinct tasks, as follows:

• Data access

• Business logic implementation

• User interface display

• User interaction

• Application (page) Flow

The MVC (Model View Controller) architecture provides a way of compartmentalizing these tasks, based on the premise that activities, such as data presentation, should be separate from data access. This architecture enables you to easily plug a data source into the application without having to rewrite the user interface. MVC allows the logical separation of an application into three distinct layers: the Model, the View, and the Controller.

The Model

The Model is the repository for the application data and business logic. One facet of the Model's purpose is to retrieve data from and persist data to the database. It is also responsible for exposing the data in such a way that the View can access it, and for implementing a business logic layer to validate and consume the data entered through the View. At the application level, the Model acts as the validation and abstraction layer between the user interface and the business data that is displayed. The database server itself is simply a persistence layer for the Model.

The View

The View is responsible for rendering the Model data using JSPs. The View code does not include a hardcoded application or navigation logic, but may contain some logic to carry out tasks like displaying conditional data based on a user role. When an end user executes an action within the HTML page that the View renders, an event is submitted to the Controller. The Controller then determines the next step.

The Controller

The Controller is the linchpin of the MVC pattern. Every user action carried out in the View is submitted through the Controller. The Controller then performs the next action, based on the content of the request from the browser.

The Controller can be driven in several different ways. For example, you can use URL arguments to route the requests to the correct code. The MVC pattern itself determines the function of the Controller, not how it should work.

Benefits

The MVC architecture provides a clear and modular view of the application and its design. By separating the different components and roles of the application logic, it allows developers to design applications as a series of simple and different components: the Model, the View, and the Controller. This pattern should help to create applications that are easier to maintain and evolve. For example, once you create one view, you can easily create another view using the same business logic. Because of the ease and reusability, the MVC pattern is the most widely used pattern in the context of Web-based application development.

Figure 7-14 shows how the MVC pattern applies to a conventional thin-client Web application:

Figure 7-14 The MVC Pattern

Description of "Figure 7-14 The MVC Pattern"

7.3.1.2 Apache Struts Overview

The Apache Struts framework (http://struts.apache.org) is one of the most popular frameworks for building Web applications, and provides an architecture based on the JSP Model 2 approach of the MVC design paradigm. In the Model 2 approach, end user requests are managed by a servlet that controls the flow, and uses components such as JavaBeans or EJBs to access and manipulate the data. It then uses JSPs to render the application content in a Web browser. This model differs from JSP Model 1, where the JSPs managed the browser request and data access.

The Struts framework provides its own HTTP Servlet as a controller component. The Struts framework is driven by an XML configuration file that contains the page flow of the application. Struts does not provide the Model, but allows developers to integrate it to any data access mechanism, for example EJBs, TopLink, or JDBC. The most common technology for writing View components is JSP and Struts provides various tag libraries to help in writing these, although some of these tags have now been superseded by the Java Standard Tag Library (JSTL), which may also be used.

Note: For more information about JSTL and JSF, see the FAQ on the Apache Software Foundation Web site (http://struts.apache.org/kickstart.html).

7.3.1.3 Oracle Portal Integration with Struts

The Oracle Portal Developer Kit contains numerous examples and documents regarding the usage of the Oracle Portal APIs, such as personalization and caching. The integration of the application flow and business logic is not part of the portlet APIs. By using the Struts framework, however, you can leverage the MVC architecture to create and publish applications within your enterprise portal.

Oracle Struts Portlet

To create a portlet using the Struts framework, or to generate a portlet from an existing Struts application, you must deploy all the components in the J2EE container. In the context of Oracle Portal, the Struts application is called by the PPE, and not by the browser as compared to a standalone Struts application. When a portlet show call is made, the page engine sends a request to the Struts portlet renderer, which then forwards the request to the Apache Struts Controller servlet, as shown in Figure 7-15.

Figure 7-15 Integrating Struts Applications with Oracle Portal

Description of "Figure 7-15 Integrating Struts Applications with Oracle Portal"

The following code shows a portion of the provider definition file (provider.xml):

...
<renderContainer>true</renderContainer>
    <renderCustomize>true</renderCustomize>
    <autoRedirect>true</autoRedirect>
    <contentType>text/html</contentType>
    <showPage class="oracle.portal.provider.v2.render.http.StrutsRenderer">
        <defaultAction>showCustomer.do</defaultAction>
    </showPage>
</renderer>
...

For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html

The showPage tag defines the business logic that will be executed in the Show mode of the portlet. The showPage of the Struts portlet contains two important components, which are as follows:

1. The renderer class (oracle.portal.provider.v2.render.http.StrutsRenderer), which receives the portlet request from the PPE and acts as a proxy to forward the request to the Struts Action Servlet.

2. The defaultAction tag, which defines the Struts action that will be used by default when the portlet is called for the first time.

The PDK-Java enables you to easily develop a view (Portal View) of your Struts application. This view enforces a consistent look and feel of your Struts portlet using portal styles, and allows the end user to use the application within the portal.

To create a Struts portlet, you must use the Oracle Portal JSP tags, which are extensions of the default Struts JSP tags. This development process is similar to that of creating a standalone Struts application. To learn how to build a Struts portlet, refer to Section 7.3.2.1, "Creating a Struts Portlet". Also, since the portlet and struts application must also be in the same Servlet Context, you must create a single Web application that contains both elements. To learn how to easily create this Web application in Oracle JDeveloper, refer to the next section, Section 7.3.2.1, "Creating a Struts Portlet".

7.3.1.4 Summary

Apache Struts has become the de facto standard for developing MVC-based J2EE applications, because it offers a clean and simple implementation of the MVC design paradigm. This framework enables you, as the portlet developer, to separate the different components of an application, and to leverage the Struts controller to easily publish an existing Struts application to Oracle Portal without completely changing the existing business logic.

Note:

For more information on the Oracle Portal Developer Kit, see Portal Center (http://www.oracle.com/technology/products/ias/portal/pdk.html)

7.3.2 Creating a Struts Portlet

Oracle PDK contains new extensions to integrate Apache Struts applications. This section explains how to build a portlet from an existing struts application. You can also follow these steps to create a portlet that uses the Model View Controller paradigm. To learn more about the Apache Struts framework, refer to Section 7.3.1, "Oracle Portal and the Apache Struts Framework". The PDK-Java extensions described in this section rely on Apache Struts 1.1.

This section contains the following steps:

• Section 7.3.2.1, "Creating a Struts Portlet"

• Section 7.3.2.2, "Registering the Provider"

• Section 7.3.2.3, "Summary"

7.3.2.1 Creating a Struts Portlet

To publish a part of an existing Struts application as portlet, we recommend that you first create a new view to serve as the Portal View of your application. This view uses existing objects (Actions, ActionForm, and so on) with a new mapping and new JSPs.

Note:

Although we recommend that you create a Portal View of your application, you could alternatively replace your application's struts tags with PDK-Java struts tags. This approach enables your application to run both as a standalone struts application and a portlet.

In this example, you will create a portlet that enables you to add a new entry to a Web Logger (Blog). Figure 7-16 and Figure 7-17 show how you submit a blog and save a blog entry.

Figure 7-16 Submitting a Blog

Description of "Figure 7-16 Submitting a Blog"

Figure 7-17 Saving a Blog Entry

Description of "Figure 7-17 Saving a Blog Entry"

prepareNewBlog is a simple empty action that redirects the request to the enterNewBlog.jsp page. This page shows a form for submitting a new blog.

The corresponding entry in the struts-config.xml is:

<action path="/prepareNewBlog" scope="request"
type="view.PrepareNewBlogAction" >
    <forward name="success" path="/view/enterNewBlog.jsp"/>
</action>
<action path="/saveNewBlog" name="blogForm" scope="request"
    type="view.SaveNewBlogAction" input"/view/enterNewBlog.jsp"  >
    <forward name="success" path="/view/newBlogConfirmation.jsp"/>
</action>

7.3.2.1.1 Create a new flow and view to host the portlet actions

To create a new view, first create a new set of ActionMappings (page flow) that will redirect the various actions and requests to Portal-specific JSPs.

<action path="/portal/prepareNewBlog" scope="request"
    type="view.PrepareNewBlogAction" >
    <forward name="success" path="/view/portal/enterNewBlog.jsp"/>
</action>
<action path="/portal/saveNewBlog" name="blogForm" scope="request" type="view.SaveNewBlogAction" input="/view/enterNewBlog.jsp"  >
    <forward name="success" path="/view/portal/newBlogConfirmation.jsp"/>
</action>

As you can see, only the path attributes are modified. The FormBean Action responsible for the application business logic remains unchanged.

7.3.2.1.2 Creating the new JSPs

As specified in the previous step, the actions forward the request to new JSPs, which are responsible for rendering the portlet content. Your new portlet view JSPs can share the HTML with the standalone view, but be sure that the portlet meets the following criteria:

• Uses Portal styles that enforce a consistent look and feel with the rest of the portal page.

• Contains HTML code that is allowed in HTML table cells (that is, no <html>, <body>, and <frame> tags).

• Renders portal-aware links and forms. This is necessary to ensure that your Struts portlet renders its content inline, thus keeping your users within the context of the portal page by rendering the requested content within the same portlet container.

To achieve inline rendering in your Struts portlet, you must use Oracle PDK tags:

<pdk-struts-html:form action="/portal/saveNewBlog.do">
...
...
</pdk-struts-html:form>

During the rendering of the portlet, one of the JSP tags (for example, the pdk-struts-html:form tag), submits the form to the Parallel Page Engine (PPE), which then sends the parameters to the Struts portlet. The Struts controller executes the logic behind these actions and returns the next JSP to the portlet within the portal page.

The PDK contains all the Struts tags, and extends all the tags that are related to URLs. The following is a list of the PDK extended tags:

• form: creates an HTML form and embeds the portal page context in the form to ensure inline rendering

• text: renders fields on the form.

• link and rewrite: create a link to the portal page, and are required for inline rendering

• img: creates an absolute link that points to the Web provider. If you want to use this tag in the context of Internet Web sites that have firewalls, you must make sure the provider is directly accessible from the Internet. If it is not possible, you can deploy the images to the Oracle Portal middle tier and use the Apache Struts image link to generate a relative link (relative to the portal, not to the application).

  Note:

  You can register the Oracle PDK with Oracle JDeveloper so that you can drop the tags from the Oracle JDeveloper Components Palette. For more information, see the Registering a Custom Tag Library in JDeveloper section in the Oracle JDeveloper online help.

7.3.2.1.3 Creating a Portlet

You can create your Struts portlet either manually or by using the Java Portlet wizard. Although the wizard does not explicitly offer Struts support, you can utilize the wizard to build your Struts portlet.

To create a portlet, perform the following steps:

1. In Oracle JDeveloper, open the Java Portlet Wizard to create an Oracle PDK Java Portlet.

   Note:

   The Java Portlet and Oracle PDK Java Portlet options are used to create JPS-compliant portlets and PDK-Java portlets respectively. Clicking Java Portlet or Oracle PDK Java Portlet opens the Java Portlet Wizard. For more information on opening the wizard, see Section 6.5.1, "Creating an Oracle PDK-Java Portlet and Provider".

2. For the Implementation Style of the show page, select Java Class.

3. For the Package Name, enter oracle.portal.provider.v2.render.http

4. For the Class Name, enter StrutsRenderer. This generates the skeleton of the portlet renderer class, StrutsRenderer.

5. Since the StrutsRenderer is part of the PDK, you do not need this generated file. So, when you finish the wizard, you must delete the file generated by the wizard. To do so, click the file in the System Navigator window, then choose File > Erase from Disk in Oracle JDeveloper.

6. Edit the provider.xml and change the following properties:

   At the provider level, perform the following:

   • If you want users to always return to the same portlet state as when they left the portal page, you can configure the struts renderer to save the struts action in the struts context:

     <actionInSession>true</actionInSession>
     

     If you prefer that users always start from the beginning of the portlet when they return from outside the portal page, then you should not save the struts action:

     <actionInSession>false</actionInSession>
     

   • If the Struts application uses sessions (for example, the form sysnchronizer token mechanism is used or <actionInSession> is set to true), enable session handling:

     <session>true</session>
     

   At the portlet level, perform the following:

   • Specify the first action to raise when the portlet is called. Use the following code:

     <showPage class="oracle.portal.provider.v2.render.http.StrutsRenderer">
     <defaultAction>/portal/prepareNewBlog.do</defaultAction>
     </showPage>
     

   
   

   For more information on the syntax of provider.xml, refer to the provider Javadoc on OTN:

   http://www.oracle.com/technology/products/ias/portal/html/javadoc/xml_tag_reference_v2.html
   

7.3.2.1.4 Extending the portlet to add Portal Business Logic

In your application, you should add code specific to your portal, such as the user's information, personalization, and localization. To do so, you can create a new Action class that is only called in the Portal context, and handles all Portal-specific business logic.

7.3.2.2 Registering the Provider

Now that your portlet is ready to be used by Oracle Portal, you must make it accessible to Oracle Portal by registering it. For information on how to register your PDK-Java portlet, refer to Section 6.5.5, "Registering and Viewing Your Oracle PDK-Java Portlet". If you chose to save the struts action in the session context, <actionInSession>true</actionInSession>, then you must specify the provider login frequency as Once per user session during registration. Setting the login frequency this way ensures the session information is passed to your struts portlet.

7.3.2.3 Summary

Oracle Fusion Middleware enables you to easily create Struts portlets using Oracle JDeveloper and publish existing Struts applications to Oracle Portal. For more information on using the Oracle JDeveloper Java Portlet wizards, refer to the beginning of this chapter. For more information on using Oracle Portal, refer to the Oracle Fusion Middleware User's Guide for Oracle Portal and the Oracle Portal Online Help.

7.3.3 Creating an Oracle Application Development Framework (ADF) Portlet

Similarly to Struts, Oracle ADF relies on the MVC design pattern. Oracle ADF applications leveraging the Struts controller can be turned into portlets and deployed to Oracle Portal the same way as Struts applications. Refer to Section 7.3.2, "Creating a Struts Portlet".

Note:

After creating the Oracle ADF portlet, you may find that the JSP page does not display correctly. This is because the Parallel Page Engine request is sent to a provider through a SOAP request (oracle.webdb.provider.v2.adapter.SOAPServlet), which implies that the portal does not serve the page as a standard .JSP page. To resolve this, create the ADFBindingFilter filter.

To create the ADFBindingFilter filter and filter mappings, include the following in your web.xml file:

<filter>
   <filter-name>ADFBindingFilter</filter-name>
   <filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class>
   <init-param>
     <param-name>encoding</param-name>
     <param-value>windows-1252</param-value>
   </init-param>
 </filter>
 <filter-mapping>
   <filter-name>ADFBindingFilter</filter-name>
   <url-pattern>*.jsp</url-pattern>
 </filter-mapping>
 <filter-mapping>
   <filter-name>ADFBindingFilter</filter-name>
   <url-pattern>*.jspx</url-pattern>
 </filter-mapping>
 <filter-mapping>
   <filter-name>ADFBindingFilter</filter-name>
   <url-pattern>/*</url-pattern>
 </filter-mapping>
 <filter-mapping>
   <filter-name>ADFBindingFilter</filter-name>
   <url-pattern>*</url-pattern>
 </filter-mapping>
 <filter-mapping>
   <filter-name>ADFBindingFilter</filter-name>
   <servlet-name>action</servlet-name>
 </filter-mapping>
 <filter-mapping>
   <filter-name>ADFBindingFilter</filter-name>
   <servlet-name>jsp</servlet-name>
 </filter-mapping>

---

Footnote Legend

Footnote 1: User personalization data for Oracle Portal objects is never exported. This restriction applies to portlets as well as other objects, such as pages.