Oracle® Application Server Portal Developer's Guide 10g Release 2 (10.1.4) B14135-03 |
|
![]() Previous |
![]() Next |
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:
The source code for many of the examples referenced in this chapter is available as part of PDK-Java. You can download PDK-Java from the OracleAS Portal Developer Kit (PDK) page on OTN:
http://www.oracle.com/technology/products/ias/portal/pdk.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
Once you have built your initial portlet in the Portlet Wizard as described in Section 6.4.2, "Building JPS-compliant Portlets", 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 Adding Personalization, which is described in this section.
In this section, you enhance the portlet you created in Section 6.4.2, "Building JPS-compliant Portlets" 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.
In this section, you add some code to My Java Portlet, redeploy the portlet, and then test it in OracleAS Portal.
In Oracle JDeveloper, double-click the view.jsp
file for your JPS-Standard portlet in the Application Navigator.
Add the following code that is indicated in bold:
<%@ 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") %>
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 Visual Designer
Add the following code that is indicated in bold 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%"> <textarea rows="10" cols="60" class="portlet-form-input-field" name="portletContent"><%= prefs.getValue"portletContent"."Portlet Content" %></textarea> </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>
Click the Design tab to see the new form field that you just added.
Open WelcomePortlet.java
in the visual editor and insert the following two lines of code (indicated in bold):
// 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();
Redeploy the portlet. Notice that Oracle JDeveloper automatically saves and compiles the code before deploying the portlet. Refer to Section 6.4.2.3, "Deploying Your Portlet to an Application Server" for a reminder of how to perform this step.
In OracleAS 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.
Click the Customize link. You can see the new form field that you added in Oracle JDeveloper.
Enter the following HTML in the Content field, replacing the words Portlet Content.
<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>
Click Apply and then click Close. The HTML is rendered in the portlet.
Once you have built your initial portlet in the Portlet Wizard as described in Section 6.6.2, "Building PDK-Java Portlets", you may perform the following tasks to enhance it:
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 Creating Java Portlets".
You have already downloaded and installed the Java Portlet Container and have an Oracle Application Server Containers for J2EE 9.0.4 container to which you may deploy your portlets.
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
In the Portlet Wizard, you add Show modes by checking boxes on the wizard pages. Refer to Section 6.6.2, "Building PDK-Java Portlets" 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:
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
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:
In Oracle JDeveloper, open the project that contains your portlets and select the portlet in the Application Navigator to ensure the HTML page is created in the appropriate place.
Open Oracle JDeveloper's visual editor and create your HTML page. For example, the following HTML could serve as a preview page:
<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.
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:
Edit the provider definition file, provider.xml
and add the tag to activate Preview mode:
<showPreview>true</showPreview>
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>
Save the updates to provider.xml
.
Redeploy your portlet. Refer to step 6 in Section 6.6.2.4.2, "Deploying the WAR File".
When you redeploy, Oracle JDeveloper automatically saves and compiles the code before deploying 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:
Copy the HTML file you created in Section 7.2.1.2, "Implementing Extra Show Modes" and provider.xml
to the Oracle Application Server Containers for J2EE instance where you plan to deploy the portlet.
Refresh the provider.
Refresh the portal page containing your portlet.
To view Preview mode, do the following:
Edit a page or create a new page and choose Add Portlet.
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-2
Click the magnifying glass icon next to the portlet and a preview window similar to the one in Figure 7-3 displays.
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 enable 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 OracleAS Portal page, the personalizations made in the Edit and Edit Defaults modes apply only to that instance of the portlet.
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 these 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 OracleAS 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.
|
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.
You have followed through and understood these sections:
You built a portlet using the wizard, with Edit page and Edit Defaults page selected, and successfully added it to a page.
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.
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>
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.
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>
This HTML code 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");
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 OracleAS 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 OracleAS Portal automatically handle the personalization differently depending on the Show mode (Edit or Edit Defaults).
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. These lines include the following:
Adding import statements.
Declaring the NameValuePersonalizationObject
.
Retrieving the personalization data.
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" %>
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); %>
Get the string information from the personalization framework:
String greeting = data.getString("myportlet_greeting");
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.
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 OracleAS Portal (for example, you are running in a load balanced, multi-node cluster of Oracle Application Server Containers for J2EE 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 Application Server Portal Configuration Guide.
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
To view the personalization changes you made in the preceding sections, you need to deploy the portlet to your application server or Oracle Application Server Containers for J2EE and refresh the page containing your portlet. For more information on deploying your portlet, refer to Section 6.6.2.4, "Deploying 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.
OracleAS 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:
You have followed through and understood Section 6.6.2, "Building PDK-Java Portlets".
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 in a portlet, or give them lengthy names and descriptions. |
Using the wizard in Section 6.6.2, "Building PDK-Java Portlets", 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.6.2, "Building PDK-Java Portlets".
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.
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.
Create a page parameter called MyParameter
with a default value of My Default Value
.
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
.
Go back to the page. Notice that, in the portlet, a value of My Default Value
appears.
View the page and enter the parameter and a value at the end of the URL:
&MyParameter=This%20portlet%20works
Figure 7-4 is an example of 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>
Intraportlet links refer to the OracleAS Portal page on which the portlet resides, and that portlet is most likely running remotely from OracleAS Portal. Hence, you must consider how the portlet can render a link to the correct page without some knowledge of the OracleAS 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 OracleAS Portal requests that a portlet render itself, OracleAS 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 OracleAS Portal.
OracleAS 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 OracleAS Portal page that represents the portlet's personalization page. In OracleAS 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. OracleAS 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, 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 OracleAS 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 OracleAS Portal entry point to the event manager. This URL is useful to both desktop and mobile portlets.
URL parameters are used in classic Web applications to pass information from links or forms in the browser back to the server. The server in turn takes actions and returns the appropriate content. For example, if the user of a dictionary Web site asks for information about hedgehogs, the URL submitted to the server might look something like the following:
http://dictionary.reference.com/search?q=Hedgehog
If the server is responsible for rendering the whole page and the client communicates directly with the server, this form of URL works well. In the OracleAS Portal case, the client does not communicate directly with portlets. Instead, OracleAS Portal mediates between the client and the portlet. Moreover, because most pages have multiple portlets, OracleAS Portal communicates with multiple portlets.
For example, suppose a page contains two portlets, a thesaurus portlet and a dictionary portlet. Both portlets use q
as a parameter to record the search queries made by the user. If the user queries the thesaurus portlet, the URL used to re-request the page with the updated thesaurus portlet must contain the thesaurus portlet's parameter, q
. The thesaurus parameter must also be distinguished from dictionary portlet parameter 1, which performs the same function for that portlet. An example URL with the properly qualified thesaurus parameter might look something like the following:
http://host/portal/page?_pageid=33,1&_dad=portal&_schema=PORTAL
&_piref33_38279_33_1_1.q=Hedgehog
Notice the fully qualified parameter name, _piref33_38279_33_1_1.q
. It identifies the parameter and distinguishes it from other parameters on the page. Further, notice that the URL contains some parameters unrelated to any portlet. These parameters are untouched by the portlet because it does not own them.
The portlet developer must ensure that the portlet:
Properly qualifies its own parameters when they are built into links and forms.
Leaves unchanged any parameters that do not belong to it.
The following API call transforms an unqualified parameter name into a qualified parameter name:
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 other aspect of a portlet's responsibilities with respect to URL parameters is to not disturb the parameters on the URL that it does not own. The utilities you may use to ensure adherence to this rule are discussed in Section 7.2.3.3.3, "Building Links with the Portlet URL Types" and Section 7.2.3.3.4, "Building Forms 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.4, "Building Forms with the Portlet URL Types" to see the initial submission form that sets the value of q
.
Note: When rendering attributes inSimpleResult (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 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>
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.3, "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.3, "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>
You can implement navigation within a portlet in one of the following three ways:
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.3, "Building Links with the Portlet URL Types" and Section 7.2.3.3.4, "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 later.
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.5.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 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
You should also note that 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.
<%@ 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>
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 Parameters to Your Portlets".
Creating an Events Portlet
To create an events portlet, perform the following steps:
Create a new portlet called MyEventsPortlet
in the same provider you used for the parameter portlet in Section 7.2.3.2, "Adding Parameters to Your Portlets"by invoking the Portlet Wizard. Go through the wizard as normal. In step 5 of the wizard, create a parameter. In step 6 of the wizard (see Figure 7-5), 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-5 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
Import the following classes:
oracle.portal.provider.v2.event.EventUtils
oracle.portal.utils.NameValue
oracle.portal.provider.v2.url.UrlUtils
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. |
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
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-6.
MyParameter = Event Output MyParameter
Figure 7-6 Portlet Events in the Edit Page
Click OK to view the page. Your Event portlet (see Figure 7-7) should have a link that displays the value received from the page.
Figure 7-7 My Event Portlet Before Parameter Change
You can append a parameter value to the URL and the portlet displays the value in the link.
&MyParameter=20
When you click the link, that value is passed to the Parameter portlet on its page (see Figure 7-8).
Figure 7-8 My Event Portlet After Parameter Change
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:
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.
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.
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 theEnvLookup 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.
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 in one of the following two ways:
If you are using Oracle Enterprise Manager 10g, you can set the variables from there.
If you are using a standalone instance of Oracle Application Server Containers for J2EE, then you need to manually change the variable values in the PDK-Java's orion-web.xml
file.
To set variable values in Oracle Enterprise Manager 10g, do the following:
In Oracle Enterprise Manager 10g, click the instance where you have deployed PDK-Java.
Click the name representing this deployment.
Under the Web modules heading, find and click jpdk
.
In the Administration section at the bottom of the page, click Environment.
Under the Environment Entries section, all of the environment variables are listed. The default value, if it exists, is listed under the value heading. To update a value for a particular variable, enter the new value in the text box in that variable's row.
When you have updated all of the variable values that you want, click Apply.
To set variable values manually, do the following:
Open the orion-web.xml
file in a text editor. If the file does not exist, then you must create it. For a full Oracle Application Server installation, you can locate this file in:
ORACLE_HOME\j2ee\OC4J_instance\application-deployments\jpdk\jpdk
For a standalone instance of Oracle Application Server Containers for J2EE, you can locate it in:
ORACLE_HOME\j2ee\home\application-deployments\jpdk\jpdk
For each deployment property you want to set, add the following entry:
<env-entry-mapping name="jndi_var_name">value</env-entry-mapping>
Save and close the file. When complete, your file should look something like the following:
<?xml version = '1.0'?><!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Orion Web Application 2.3//EN" "http://xmlns.oracle.com/ias/dtds/orion-web.dtd"> <orion-web-app deployment-version="9.0.3.0.0" jsp-cache-directory="./persistence" temporary-directory="./temp" servlet-webdir="/servlet/"> <env-entry-mapping name="oracle/portal/sample/rootDirectory"> D:\prefs</env-entry-mapping> <env-entry-mapping name="oracle/portal/sample/definition"> D:\definitions\def.xml</env-entry-mapping> </orion-web-app>
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 here 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 Application Server Portal Configuration Guide 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.7.3.2, "Disabling Export/Import of Personalizations" for more information. |
When a user accesses any portal page, OracleAS Portal initiates a public unauthenticated session and maintains a cookie to track information about the session across requests. If the user logs in to OracleAS Portal, this session becomes an authenticated session of the logged-in user. This portal session terminates when:
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, OracleAS 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 OracleAS 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:
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).
Note: If you need to replicate session state across middle tiers, you must mark the Web application as distributable and create a cluster island for your OC4J servers. For more information, refer to Oracle Application Server Containers for J2EE Servlet Developer's Guide. |
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.
Furthermore, while using the session store with Web providers, you create a stateful application that needs to track state information in memory. Similarly, you create a stateful application if you use the file-system implementation of preference store.
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 OracleAS Portal configuration. Even though you may deploy multiple middle-tiers accessing the same OracleAS 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.
You have followed through and understood Section 6.6.2, "Building PDK-Java Portlets".
You built a portlet using the wizard and successfully added it to a page.
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 OracleAS 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.
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" %>
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. <% } %>
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
Register the provider in OracleAS 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.6.2.5, "Registering and Viewing Your 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.
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
You have followed through and understood Section 6.6.2, "Building PDK-Java Portlets".
You built a portlet using the wizard and successfully added it to a page.
This section introduces the major features that are available to secure your portlet providers.
When a user first logs in to an OracleAS Portal instance, they must enter their password to verify their identity and obtain access. This authentication is performed by OracleAS Single Sign-On server. Refer to Section 7.2.6.3, "Single Sign-On" for more information.
Once the user is authenticated to OracleAS Portal, 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();
When using this user identity for sensitive operations, it is important to ensure that you have configured your OracleAS Portal and this provider to use basic message authentication to secure the integrity of the identity assertion.
You also have the option of configuring the OC4J containing the JPDK provider to use JAZN-LDAP and then use J2EE security, in which case you can obtain the user's identity with the following method, again through the HttpServletRequest
object:
String userName = request.getRemoteUser();
And if you need the user Principal
, you can also use:
Principal userPrincipal = request.getUserPrincipal();
When configuring the provider's OC4J container in this manner, make sure to configure your OracleAS Portal and this provider to use enhanced message authentication to secure the integrity of this form of identity assertion.
Refer to Oracle Application Server Portal Configuration Guide for more information.
Authorization determines if a particular user may view or interact with a portlet. OracleAS Portal provides the following three types of authorization checking:
Portal Access Control Lists (ACLs): After a user is authenticated by OracleAS Single Sign-On, OracleAS 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, OracleAS Portal prevents that user from performing the actions associated with that privilege. Refer to Section 7.2.6.4, "OracleAS 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.6.5, "Portlet Security Managers" for more information.
J2EE Security Roles: You can use J2EE programmatic security in your provider code. To leverage this capability, you must configure your provider for enhanced authentication to protect the integrity of the asserted identity. From within your portlet code, you can use request.isUserInRole("securityrole")
, where request
is the HttpServletRequest
request and securityrole
is a declared J2EE security role. Refer to the Oracle Application Server Portal Configuration Guide for more information.
To this point, we have covered user authentication and authorization, which do not check the authenticity of messages received by a provider. To completely secure your providers, secure the communication between OracleAS Portal and a Web provider. (These methods do not apply to database providers, which execute within the OracleAS Portal database.) If the communication is not secured, it is possible for someone to imitate an OracleAS Portal instance and fool the Web provider into returning sensitive information. There are three types of communication security:
OracleAS 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.6.6, "OracleAS Portal Server Security" for more information.
Message Authentication appends a checksum based on a shared key to provider messages. When a message is received by the provider, the authenticity of the message is confirmed by calculating the expected value of the checksum and comparing it with the actual value received. If the values are the same, the message is accepted. If they are different, the message is rejected without further processing. The checksum includes a time stamp to reduce the chance of a message being illegally recorded in transit and resent later. Refer to Section 7.2.6.7, "Message Authentication" for more information.
Message Encryption relies on the use of the HTTPS protocol for communication between OracleAS Portal and providers. Messages are strongly encrypted to protect the data therein. Encryption provides a high level of security, but it incurs a performance penalty due to the additional processing required for each message. Refer to Section 7.2.6.8, "HTTPS Communication" for more information.
For more information about communication security, refer to the Oracle Application Server Portal Configuration Guide.
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. The following are the possible application authentication methods:
Partner Application. In this case, the application user is the same authenticated user used by OracleAS Portal.
External Application. In this case, the OracleAS Portal user is different from the application user, but the application user name and password are managed by the OracleAS Portal user.
No Application Authentication. In this case, the communication between provider and OracleAS Portal is not protected at all.
For more information about Single Sign-On, refer to the Oracle Application Server Portal Configuration Guide.
A partner application is an application that shares the same OracleAS Single Sign-On as OracleAS Portal for its authentication. Thus, when a user is already logged in to OracleAS 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. When a user attempts to access a partner application, the partner application delegates the authentication of the user to OracleAS Single Sign-On. 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 instance. OracleAS Single Sign-On 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 OracleAS 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 OracleAS Portal and the provider.
The disadvantages of a partner application implementation are as follows:
The application must share the same user repository as OracleAS Portal even though the application's user community may be a subset of the OracleAS 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 instances if they share the same user repository.
The application must be written such that it delegates authentication to OracleAS Single Sign-On.
You must have access to the application source code.
An external application uses a different authentication server than OracleAS Portal. The application may use a different instance of OracleAS Single Sign-On than that used by OracleAS Portal or some other authentication method. However OracleAS Single Sign-On does store the user name and password of the external application for that user. This means that when a user is already logged into OracleAS 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 if the administrator registers them as external applications. When a user who was previously authenticated by OracleAS Single Sign-On accesses an external application for the first time, OracleAS Single Sign-On 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 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 maps the new user name and password to the user's OracleAS 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.
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.
The provider trusts the OracleAS 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 OracleAS Portal.
When users log in to an OracleAS Portal instance, they are authenticated by an OracleAS Single Sign-On instance. Having verified their identity, OracleAS Portal uses ACLs to determine whether they are authorized to access particular portlets and add them to pages from the Portlet Repository.
OracleAS 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.
OracleAS Portal users and their privileges are granted from the Administer tab of the Builder.
OracleAS Portal user groups are administered from the Administer tab of OracleAS 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 OracleAS 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 OracleAS 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 OracleAS Portal, refer to the Oracle Application Server Portal Configuration Guide.
The advantages of ACLs are as follows:
ACLs offer a simple, yet powerful, mechanism to secure OracleAS 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.
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:
Get a list of portlets.
Verify the accessibility of the portlet.
Portlets have access to the OracleAS 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 in the current OracleAS 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 OracleAS 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 OracleAS 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 above 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 OracleAS Portal instance.
After you add a security manager to a portlet, you can validate it by following these steps:
Ensure you are logged in to an OracleAS Portal instance with privileges to create pages and add portlets to a page.
Create a new portal page, ensuring it is visible to PUBLIC.
Add your Java portlet to the page.
Make a note of the direct URL to your new Portal page.
Now log out of the Portal instance by clicking the Logout link.
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.
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.
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 Application Server, 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:
OracleAS Web Cache does not have IP address checking capability. If OracleAS Web Cache sits in front of a provider, you have no protection from a client on any host sending show requests to OracleAS 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 Application Server Portal Configuration Guide.
PDK-Java supports message authentication so that access may be limited to a specified provider instance or group of provider instances. A provider is registered with a secret shared key known only to OracleAS Portal and provider administrators.
OracleAS 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.
OracleAS Portal calculates a signature based on user information, a shared key and a time stamp. The signature and time stamp are then sent as part of the SOAP message. The time stamp is based on UTC (coordinated universal time, the scientific name for Greenwich Mean Time) so that timestamps can be used in messages between computers in different time zones.
When the provider receives this message it generates its own copy of the signature. If the signatures agree, it will then compare the message time stamp with the current time. If the difference between the two is within an acceptable value, the message is considered authentic and is processed accordingly.
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 OracleAS 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 OracleAS Web Cache in front of it, this use of the same signature cookie over the lifetime of a provider session implies a tradeoff 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 OracleAS Web Cache to cache show request responses, you have a similar tradeoff. 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 illegal show requests.
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 OracleAS 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 Application Server Portal Configuration Guide.
Normal communication between OracleAS 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 OracleAS 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 Application Server Portal Configuration Guide.
Configuration of SSL
When a provider is registered from an OracleAS 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 OracleAS Portal instance and a provider.
For more information about SSL configuration for OracleAS Portal, refer to the Oracle Application Server Portal Configuration Guide.
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 can:
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 OracleAS 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:
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
Provide the connection information for Oracle Internet Directory by extending the simple class called OidInfo
.
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.
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 OracleAS 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 yourportal_instance_id , which is specific to your installation. To find your instance identifier, refer to your Oracle Internet Directory Administrator's Guide. |
<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 OracleAS 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.
After you secure your provider with Oracle Internet Directory, you can validate its behavior by following these steps:
Ensure you are logged in to an OracleAS Portal instance as a user who is a member of the group specified in the <group>
tag in provider.xml
.
Use an existing page or create a new one, ensuring it is visible to PUBLIC.
Add your Java portlet to the page.
Make a note of the direct URL to your new page.
Click Logout.
Directly access the page by entering the URL noted in Step 4 in your browser's address bar or login to OracleAS Portal using a user that is not part of the group listed in provider.xml
.
You will see the page created in Step 2 (see Figure 7-9) but not the portlet added in Step 3. 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-9 Page and Portlets for Developer
If you log in again and view the page, you will see that the portlet is still there (see Figure 7-10).
Figure 7-10 Page and Portlets for Developer/Administrator
The export/import facility of OracleAS Portal is a multi-purpose tool for moving your portal objects, such as portlets, between instances of OracleAS 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 OracleAS 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 Application Server Portal Configuration Guide.
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, OracleAS 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 OracleAS 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 OracleAS Portal instance and provider are on Release 10.1.2. Export/import of personalizations behaves the same regardless of the location of your provider:
In the default Oracle Application Server Containers for J2EE of the Oracle Application Server, where the OracleAS Portal instance is different.
In a separate Oracle Application Server Containers for J2EE, where the OracleAS Portal instance may be different, and the provider is the same but is not registered on the target OracleAS Portal instance.
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:
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:
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:
The provider instance is the entity that contains and communicates with a set of portlets. The API for the provider instance is:
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.7.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 OracleAS 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 previously. 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
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.7.3.6, "Encrypting Personalization Data Example" and Section 7.2.7.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:
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); } } }
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>"); } }
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(); } }
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
Register this export-enabled provider with the source OracleAS Portal instance. For more information about registering Web providers, refer to Section 6.6.2.5, "Registering and Viewing Your Portlet".
Note: If the Web provider is running in a secured environment, remember to provide the proxy host and port while starting up Oracle Application Server Containers for J2EE. For example:java -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80 -jar oc4j.jar |
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 Application Server Portal User's Guide.
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 Application Server Portal User's Guide.
Add My Stock Portlet to a second region and again edit the defaults. Use a different stock code this time, MSFT
.
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 Application Server Portal Configuration Guide.
Import the page group into a target OracleAS Portal instance. For instructions on how to import a page group, refer to Chapter 10, "Exporting and Importing Content," in the Oracle Application Server Portal Configuration Guide.
View the page with My Stock Portlet in the target OracleAS Portal instance and ensure that the personalizations were maintained.
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, OracleAS 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:
Securing Provider Communications. Using OracleAS Portal configuration options, you can secure the communications between providers and OracleAS Portal. This step in turn makes the export and import of portlets more secure.
Disabling Export/Import of Personalizations. You can disable the export of all portlet personalization data on an each Web application basis. 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.
Obfuscating Data for Transport (Automatic). By default, OracleAS Portal obfuscates but does not encrypt personalization data before transporting it.
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 through HTTPS.
You want to ensure the data is secured during transit.
You want the data to remain secure while stored in the OracleAS Portal instance.
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.
If the security of exporting/importing portlets is of concern to you, you should configure OracleAS Portal to secure communications with your portlet providers. The chief mechanisms for securing provider communications in OracleAS 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 Application Server Portal Configuration Guide.
HTTPS between providers and OracleAS Portal. For more information on HTTPS for provider communications, refer to Section 6.1.7.9, "HTTPS Communication", in the Oracle Application Server Portal Configuration Guide.
Note: You cannot use certificates for the HTTPS communication with providers. |
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 Oracle Enterprise Manager 10g. If for some reason Oracle Enterprise Manager 10g is not available for the instance, you can set the values manually in orion-web.xml
. For a full Oracle Application Server installation, this file is located in:
ORACLE_HOME/j2ee/OC4J_instance/application-deployments/jpdk/jpdk
For a standalone OC4J installation, this file is located in:
ORACLE_HOME/j2ee/home/application-deployments/jpdk/jpdk
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.7.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.7.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. |
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 pointer rather than by including the actual preference data. When the transport set is imported, the target OracleAS 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.7.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. |
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 sample provided next is for illustrative purposes only. You would need to significantly enhance it for use in a production environment. |
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 thejavax.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; } }
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"/>
To export by reference rather than exporting the actual personalization, do the following:
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);
}
}
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); } }
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
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 the following two ways:
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 OracleAS Portal instance on which they are deployed. As such, caching might improve their performance. The architecture of OracleAS 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:
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.8.2, "Activating Caching" and Section 7.2.8.3, "Adding Expiry-Based Caching" for more information.
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.8.2, "Activating Caching" and Section 7.2.8.4, "Adding Invalidation Based Caching" for more information.
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.8.2, "Activating Caching" and Section 7.2.8.5, "Adding Validation-Based Caching" for more information.
You have followed through and understood Section 6.6.2, "Building PDK-Java Portlets".
You built a portlet using the wizard and successfully added it to a page.
To use the caching features of OracleAS 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 OracleAS Web Cache in front of the Web provider. Bear in mind that remote Web providers often do not have OracleAS Web Cache installed. For more information about OracleAS Web Cache, refer to the Oracle Application Server Web Cache Administrator's Guide.
Once you have installed and configured OracleAS Web Cache, ensure the following in the OracleAS 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.
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.
After you have used the Portlet Wizard to build a portlet as described in Section 6.6.2, "Building PDK-Java Portlets", 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
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.
When using OracleAS Web Cache, requests for content are sent through 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 OracleAS Web Cache, it is added to the cache before being returned to the requestor. Cache content is invalidated by sending invalidation requests directly to OracleAS Web Cache. PDK-Java uses the Java API for Web Cache (JAWC) to generate invalidation requests. This section describes how to configure OracleAS Web Cache and use the invalidation-based caching sample that comes with PDK-Java.
Not all requests sent to OracleAS Web Cache are cached. In order for the content to be cached, the content must include directives that tell OracleAS Web Cache to cache the content. Usually OracleAS 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 OracleAS Web Cache. Refer to Oracle Application Server Web Cache Administrator's Guide for more information.
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
If you are using an Oracle Application Server installation type where PDK-Java was automatically pre-installed (for example, an OracleAS Portal and Wireless type installation), you should find that OracleAS 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.8.4.3, "Configuring the XML Provider Definition". Otherwise, you will need to configure the invalidation portlet for OracleAS Web Cache.
First, you need the user name and password for the invalidation port(s) of the OracleAS 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 Application Server 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 Application Server 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 thatpdkjava.jar is present in ORACLE_HOME/portal/jlib and jawc.jar is present in ORACLE_HOME/webcache/jlib , as required by the PDK-Java installation guide.
If you are using a standalone Oracle Application Server Containers for J2EE 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\portal\jlib\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 OracleAS 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 oracle.http.configfile
. To set this system property for an Oracle Application Server Containers for J2EE instance within an Oracle Application Server installation, simply add an appropriate line to the oc4j.properties
file for the particular instance in which PDK-Java is installed (for example, MID_TIER_ORACLE_HOME/j2ee/OC4Jinstance/config/oc4j.properties
) and then restart that instance. For example:
oracle.http.configfile=fully_qualified_filename
If you are running Oracle Application Server Containers for J2EE standalone, you can specify the option in the command line you use to start it.
java -Doracle.http.configfile=<fully_qualified_filename> -jar oc4j.jar
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 OracleAS Web Cache configurations. |
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 (using 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 OracleAS Portal defined in the Cache tab of the Global Settings page.
Web Provider default (24 hours) if no maximum expiry time is specified by OracleAS 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: ThepageExpires tag is also used for normal expiry based caching. These two forms of caching are mutually exclusive. Invalidation-based caching takes place in an OracleAS 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 OracleAS 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
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 OracleAS 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 OracleAS 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 OracleAS 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.
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.
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.3, "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:
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>
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
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:
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: TheResourceRenderer (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. OracleAS 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 OracleAS 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 OracleAS Portal prefers OracleAS Wireless XML but also accepts general XML that contains a stylesheet reference that transforms to OracleAS Wireless XML. The |
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, OracleAS 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, OracleAS 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>
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>
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 using this menu to see the content. To better support this model, OracleAS 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, OracleAS 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:
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 OracleAS Portal is responsible for creating the URL that references any particular usage of a portlet on a page, OracleAS 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. Becausetext/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. |
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>
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>
To better support mobile devices, OracleAS Portal passes extra information to the portlet for use in generating its response. This information falls into the following three major categories:
OracleAS 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()) {
...
}
...
OracleAS Wireless adds the user location to the requests it forwards to OracleAS 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) { ... } ...
On each request, OracleAS 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; } ...
Much of the information in Section 7.2.3.3.5, "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>
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.
You have followed through and understood Section 6.6.2, "Building PDK-Java Portlets".
You built a portlet using the wizard and successfully added it to a page.
In Section 6.6.2, "Building PDK-Java Portlets", 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.
Create a Default Resource Bundle
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!"} }; }
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, see the JavaDoc for java.util.Locale
. 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 OracleAS 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 a French resource bundle, create a Java class named MyProviderBundle_fr
, as described earlier.
Using your default resource bundle as a template, replace the English language strings with their French equivalents. See the following example:
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."} }; }
Save MyProviderBundle_fr
.
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.
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>
Save your JSP page.
Now you can refresh your portlet and view the changes (see Figure 7-11).
To view the French greeting (see Figure 7-12), you set the language in the Set Language portlet to French instead of English.
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.
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 as follows:
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.
Updating Your Resource Bundles
Open your default resource bundle, MyProviderBundle.java
.
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"} }; }
Save MyProviderBundle.java
.
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"} }; }
Save MyProviderBundle_fr.java
.
Updating provider.xml
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.
Updating Your Resource Bundles
Open your default resource bundle, MyProviderBundle.java
.
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"}
Save MyProviderBundle.java
.
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"}
Save MyProviderBundle_fr.java
.
Updating provider.xml
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.
Once you have updated your provider and deployed it to Oracle Application Server Containers for J2EE, 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.
This section describes the framework for building Struts portlets with Oracle JDeveloper for use in OracleAS Portal. You will learn how to build a Struts portlet from an existing application by adding the Struts Tag Library from the Oracle Application Server 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 section discusses the use of the Apache Struts with OracleAS Portal. Struts is an implementation of the Model-View-Controller (MVC) design pattern.
Enterprise applications undertake the following distinct tasks:
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-13 shows how the MVC pattern applies to a conventional thin-client Web application:
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://jakarta.apache.org/kickstart.html ). |
The Oracle Application Server Portal Developer Kit contains numerous examples and documents regarding the usage of the OracleAS 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 (see Figure 7-14), or to generate a portlet from an existing Struts application, you must deploy all the components in the J2EE container. In the context of OracleAS 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.
Figure 7-14 Integrating Struts Applications with OracleAS 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:
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.
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 OracleAS 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".
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 OracleAS Portal without completely changing the existing business logic.
Note: For more information on the Oracle Application Server Portal Developer Kit, see Portal Center (http://www.oracle.com/technology/products/ias/portal/pdk.html ) |
OracleAS 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, "OracleAS 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:
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 (see Figure 7-15 and Figure 7-16), you will create a portlet that enables you to add a new entry to a Web Logger (Blog).
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>
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.
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:
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 OracleAS 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 OracleAS 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 OracleAS 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. |
You can create your Struts portlet either manually or by using the Oracle PDK Java Portlet option in Oracle JDeveloper. Although the Oracle PDK Java Portlet option does not explicitly offer Struts support, you can utilize this to build your Struts portlet.
To create a portlet:
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.6.2.1, "Creating a Portlet and Provider". |
For the Implementation Style of the show page, select Java Class.
For the Package Name, enter oracle.portal.provider.v2.render.http
For the Class Name, enter StrutsRenderer
. This generates the skeleton of the portlet renderer class, StrutsRenderer
.
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.
Edit the provider.xml
and change the following properties:
At the provider level:
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:
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
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.
Now that your portlet is ready to be used by OracleAS Portal, you must make it accessible to OracleAS Portal by registering it. For information on how to register your PDK-Java portlet, refer to Section 6.6.2.5, "Registering and Viewing Your 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.
Oracle Application Server enables you to easily create Struts portlets using Oracle JDeveloper and publish existing Struts applications to OracleAS Portal. For more information on using the Oracle JDeveloper Java Portlet wizards, refer to the beginning of this chapter. For more information on using OracleAS Portal, refer to the Oracle Application Server Portal User's Guide and the OracleAS Portal Online Help.
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 OracleAS 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 OracleAS Portal objects is never exported. This restriction applies to portlets as well as other objects, such as pages.