7 Enhancing Java Portlets

7.1.2.2.1 Reviewing the Generated Code

The wizard creates the following code for you by default:

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

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

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

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

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

7.1.2.2.2 Modifying the Generated Code

The JSP contains an input field for the portlet title. This field represents the Personalize page of the portlet where users can update the portlet title.

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

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

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

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

3. Generating an Edit page from the wizard automatically includes access to the personalization framework in the page code. At the top of the Edit page, you see the NameValuePersonalizationObject declared. This form of personalization in 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).

7.1.3.3.1 Portlet URL Types

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.

7.1.3.3.2 URL Parameters

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:

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.1.3.3.3, "Building Links with the Portlet URL Types" and Section 7.1.3.3.4, "Building Forms with the Portlet URL Types".

7.1.3.3.3 Building Links with the Portlet URL Types

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

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

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

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

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

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

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

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

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

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

7.1.3.3.4 Building Forms with the Portlet URL Types

Use of portlet parameters in forms is little different from links. The 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.1.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).

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

7.1.3.3.5 Implementing Navigation within a Portlet

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

• Pass navigation information in rendered URLs via 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.1.3.3.3, "Building Links with the Portlet URL Types" and Section 7.1.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 below.

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

ThesaurusForm.jsp:

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

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

ThesaurusLink.jsp:

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

7.1.3.4.1 Creating an Events Portlet

To create an events portlet, perform the following steps:

1. Create a new portlet called MyEventsPortlet in the same provider you used for the parameter portlet in Section 7.1.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, 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-4 Public Portlet Events Page of Portlet Wizard

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

   The wizard generates the following code in provider.xml:

   
   

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

   
   

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

   
   

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

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

2. Import the necessary classes:

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

   • oracle.portal.utils.NameValue

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

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

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

   
   

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

   
   

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

   My Parameter = Page Parameter MyParameter
   
   

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

   MyParameter = Event Output MyParameter 
   
   

   Figure 7-5 Portlet Events in the Edit Page

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

6. Click OK to view the page. Your Event portlet should have a link that displays the value received from the page.

   Figure 7-6 My Event Portlet Before Parameter Change

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

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

   &MyParameter=20
   
   

8. When you click on the link, that value is passed to the Parameter portlet on its page.

   Figure 7-7 My Event Portlet After Parameter Change

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

7.1.4.1.1 Variable Types

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

• java.lang.Boolean

• java.lang.String

• java.lang.Integer

• java.lang.Double

• java.lang.Float

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

7.1.4.1.2 Variable Naming Conventions

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

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:

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.1.4.3, "Retrieving JNDI Variables" for more information on retrieving JNDI variables.

7.1.4.1.3 Examples

The following examples illustrate provider variable names:

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

The following example illustrates non-provider variable names:

oracle/portal/myOtherProperty

7.1.4.2.1 Setting Values in Oracle Enterprise Manager 10g

To set variable values in Oracle Enterprise Manager 10g, do the following:

1. In Oracle Enterprise Manager 10g, click on the instance where you have deployed PDK-Java.

2. Click on the name representing this deployment.

3. Under the Web modules heading, find jpdk and click on it.

4. In the Administration section at the bottom of the page, click on Environment.

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

6. When you have updated all of the variable values that you want, click on Apply.

7.1.4.2.2 Setting Values Manually

To set variable values manually, do the following:

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

2. For each deployment property you want to set, add the following entry:

   <env-entry-mapping name="jndi_var_name">value</env-entry-mapping>
   
   

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

7.1.6.2.1 Authentication

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.1.6.3, "Single Sign-On" for more information.

7.1.6.2.2 Authorization

Authorization determines if a particular user may view or interact with a portlet. OracleAS Portal provides two 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.1.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.1.6.5, "Portlet Security Managers" for more information.

7.1.6.2.3 Communication Security

To this point, we have covered user authentication and authorization, which do not check the authenticity of messages received by a provider. 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.1.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.1.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.1.6.8, "HTTPS Communication" for more information.

For more information about communication security, refer to the Oracle Application Server Portal Configuration Guide.

7.1.6.3.1 Partner Application

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

7.1.6.3.2 External Application

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.

7.1.6.3.3 No Application Authentication

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.

7.1.6.5.1 Viewing the Portlet

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

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

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

3. Add your Java portlet to the page.

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

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

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

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

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

7.1.6.5.2 Implementing Your Own Security Manager

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

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

7.1.6.9.1 Implementing Oracle Internet Directory Security

PDK-Java provides a set of default classes specifically for Oracle Internet Directory integration. These classes handle the connection from your portlets to Oracle Internet Directory, enable your portlets to be secured based on 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 below). This class should be used only for testing and development, it is not safe to use in a production scenario.

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

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

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

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

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

  • oidUser is the Oracle Internet Directory account.

  • oidPasswd is the Oracle Internet Directory password.

  For example:

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

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

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

  
  

  Note: The following example refers to your portal_instance_id, which is specific to your installation. To find your instance identifier, refer to your Oracle 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.

7.1.6.9.2 Viewing Your Portlets

After you add the security manager to your Java portlet, you can demonstrate its behavior by following these steps:

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

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

3. Add your Java portlet to the page.

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

5. Click Logout.

6. Directly access the page by entering the URL noted in Step 4 in your browser's address bar or login to 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 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-8 Page and Portlets for Developer

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

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

Figure 7-9 Page and Portlets for Developer/Administrator

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

7.1.7.1.1 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 above. You log events with the calling portal through the instance provided for each method. You record events in the Web provider log with the normal logging mechanism, oracle.portal.log.LogManager. The log levels for export/import are as follows:

• TransportLogger.SEVERITY_INFO

• TransportLogger.SEVERITY_WARNING

• TransportLogger.SEVERITY_ERROR

7.1.7.3.1 Securing Provider Communications

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:

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

  
  

7.1.7.3.2 Disabling Export/Import of Personalizations

The JNDI variable, oracle/portal/provider/global/transportEnabled, controls whether to allow the exportation and importation of personalizations. If you set the variable to true, personalizations are transported as part of export and import. If you set it to false, they are not transported. You can set JNDI variables for PDK-Java through 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

7.1.7.3.3 Obfuscating Data for Transport (Automatic)

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

7.1.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.1.7.3.6, "Encrypting Personalization Data Example".

7.1.7.3.5 Exporting by Reference

As mentioned previously, the default behavior for exporting of portlets is to include the actual personalization data in the transport set. For a more secure transport, you can code your portlet such that the personalizations are exported via 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.1.7.3.7, "Exporting by Reference Example".

7.1.7.3.6 Encrypting Personalization Data Example

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

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

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

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

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

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

   
   

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

   
   

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

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

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

7.1.7.3.7 Exporting by Reference Example

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

1. Override the DefaultPortletInstance with the following ExportByRefDefaultPortletInstance:

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

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

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

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

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

   
   

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

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

7.1.8.4.1 Configuring the Provider Servlet

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

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

If the flag is not defined here, then invalidation-based caching is switched off. The status of this flag can easily be checked by displaying the provider's test page. For example:

http://<provider_hostname>:<port>/jpdk/providers/webcache/MyWebPRovider

7.1.8.4.2 Defining the OracleAS Web Cache Invalidation Port

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

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

7.1.8.4.3 Configuring the XML Provider Definition

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

<useInvalidationCaching>true</useInvalidationCaching>

If your portlet supports personalization (via 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>

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

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

7.1.8.4.4 Manually Invalidating the Cache

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

The invalidation-based caching portlet sample included with PDK-Java contains a single portlet that displays the time the content was cached and a link to trigger an invalidation request. The first time a page request is made to the Web provider via 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 example below 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.

7.1.9.1.1 Configuration Data

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 via the PortletRenderRequest object:

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

7.1.9.1.2 User Data

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) {
   ...
}
...

7.1.9.1.3 Device Information

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.

voice

micromessenger

messenger

microbrowser

pdabrowser

pcbrowser

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 via the PortletRenderRequest object.

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

7.1.10.2.1 Providing Translations for Portlet Content

In Section 6.3.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

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

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

  2. Save MyProviderBundle.

• Creating Resource Bundles for Other Supported Languages

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

  
  

  For more information on Locales, see the JavaDoc for java.util.Locale:

  http://portalstudio.oracle.com/pls/ops/docs/FOLDER/COMMUNITY/PDK/jpdk/v2/apidoc/index.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.

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

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

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

  3. Save MyProviderBundle_fr.

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

Updating Your Renderer

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

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

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

2. Save your JSP page.

Now you can refresh your portlet and view the changes.

Figure 7-10 Portlet in English

Description of "Figure 7-10 Portlet in English"

To view the French greeting, you set the language in the Set Language portlet to French instead of English.

Figure 7-11 Portlet in French

Description of "Figure 7-11 Portlet in French"

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

7.1.10.2.2 Providing Translation for Portlet Attributes

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

• Method 1: Using Resource Bundles at the Provider Level

• Method 2: Creating Resource Bundles at Portlet Level

Method 1: Using Resource Bundles at the Provider Level

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

• Updating Your Resource Bundles

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

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

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

  3. Save MyProviderBundle.java.

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

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

  5. Save MyProviderBundle_fr.java.

• Updating provider.xml

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

     <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>3</id>
      <resource>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

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

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

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

  3. Save MyProviderBundle.java.

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

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

  5. Save MyProviderBundle_fr.java.

• Updating provider.xml

  1. In provider.xml, you need to use only one tag instead of one tag for each string as you did in Method 1: Using Resource Bundles at the Provider Level. Add the tag between the portlet id and the timeout number value.

     <resource>mypackage2.MyProviderBundle</resource>
     
     

     
     

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

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

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

7.3.1.3.1 Oracle Struts Portlet

To create a portlet using the Struts framework, or to generate a portlet from an existing Struts application, you must deploy all the components in the J2EE container. In the context of 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

Description of "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:

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

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

The PDK-Java allows 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".

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

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

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

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

7.3.2.1.2 Creating the new JSPs

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

• 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 (i.e., 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.

  
  

7.3.2.1.3 Creating a Portlet

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

To create a portlet:

1. In Oracle JDeveloper, open the OracleAS PDK Java Portlet Wizard.

   
   

   Note: For more information on opening the wizard, see Section 6.3.2.1, "Creating a Portlet and Provider".

   
   

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

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

4. For the Class Name, enter StrutsRenderer.

5. The Java Portlet Wizard generates the skeleton of the portlet renderer class, StrutsRenderer, for you. 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 on the file in the System Navigator window, then choose File > Erase from Disk in Oracle JDeveloper.

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

   At the provider level:

   • 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
   

7.3.2.1.4 Extending the portlet to add Portal Business Logic

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