9
Running in a Portal Framework

To make the Employee Benefit sample application run within a portal framework, you have to make some changes to the application. The changes that you have to make are in the controller and the action handler objects. You also have to edit the links in the JSP files to make them work. The model layer (that is, the Employee and Benefit EJBs) remains the same.

Topics in this chapter:

• Section 9.1, "How Portal Processes Requests"

• Section 9.2, "Screenshots of the Application in a Portal"

• Section 9.3, "Changes You Need to Make to the Application"

• Section 9.4, "Update the Links Between Pages Within a Portlet"

• Section 9.5, "Use include instead of the forward Method"

• Section 9.6, "Protect Parameter Names"

• Section 9.7, "Make All Paths Absolute"

9.1 How Portal Processes Requests

The following figure shows how portal handles requests. This is important in understanding why you have to use APIs in the Java Portal Developer's Kit to code your links and parameters.

Figure 9-1 How portal processes requests

Text description of the illustration da_port6.gif

1. A client sends a request to Oracle9iAS for a portal page.

2. Portal handles the request. It queries the repository to get a list of portal providers that need to supply data to render the portal page.

3. Portal sends the request to each provider.

4. The providers process the request and return the appropriate data to portal.

5. Portal assembles the data into a page and returns the page to the client.

9.2 Screenshots of the Application in a Portal

The screens for the application in a portal look the same as if the application were running outside of a portal. The only difference is that the portal pages contain tabs and icons as defined by users and administrators. Users and administrators can set up portals with different looks; see the portal documentation for details.

Figure 9-2 to Figure 9-5 show the pages of the application in a portal. You can compare these portal pages with the non-portal pages in Figure 2-1 and Figure 2-2.

Figure 9-2 ID page in a portal

Text description of the illustration port_id.jpg

Figure 9-3 Info page in a portal

Text description of the illustration port_inf.jpg

Figure 9-4 Add Benefits and Remove Benefits pages in a portal

Text description of the illustration da_port4.gif

Figure 9-5 Success page in a portal

Text description of the illustration port_suc.jpg

9.3 Changes You Need to Make to the Application

Before you can run the sample application in a portal, you have to set up a few things outside the application as well as make some changes to the application itself.

9.3.1 Set up a Provider and a Portal Page

You need to have a portal environment in which to run the application:

• Set up a provider, and register the sample application with the provider.

• Set up a portal page and define one of the regions on the page to display the sample application.

The following figure shows a sample portal page that contains the Employee Benefit application. The tabs at the top of the page take you to different pages in the portal. You can have different tabs in your portal page.

Figure 9-6 A portal page containing the sample application

Text description of the illustration portal_e.jpg

9.3.2 Edit the Application

You need to add some calls to the JPDK API to make your application run in a portal environment.

• Update the links where you want to display another page within the portlet. If the file that contains the URL is an HTML page, you have to change it to a JSP page because you need to determine the URL dynamically.

  See Section 9.4, "Update the Links Between Pages Within a Portlet".

• Invoke the include method instead of forward. You have to use include because the portal needs to add data from other portlets. If you use forward, the portal does not have a chance to gather data from the other portlets.

  See Section 9.5, "Use include instead of the forward Method".

• Use the portletParameter method in the HttpPortletRendererUtil class to ensure that request parameters have unique names. This ensures that applications on the portal page read only their parameters and not parameters for other applications. This also enables applications to use the same parameter name; the method prefixes parameter names with a unique string for each application.

  See Section 9.6, "Protect Parameter Names".

• Make all URL paths absolute paths using the absoluteLink or the htmlFormActionLink method in the HttpPortalRendererUtil class, depending on the HTML tag.

  See Section 9.7, "Make All Paths Absolute".

9.4 Update the Links Between Pages Within a Portlet

When you need to link from one page in your application to another page within a portlet, you cannot simply specify the target page's URL in the href attribute of an <a> tag. Instead you have to do the following:

• Use the parameterizeLink method in the HttpPortletRendererUtil class. See Section 9.4.1, "The parameterizeLink Method".

• Add the next_page parameter to the request's query string to specify the target page or object. See Section 9.4.2, "The next_page Parameter".

9.4.1 The parameterizeLink Method

The parameterizeLink method enables you to add a query string to the link. (If you do not have a query string in your link, you can just use the absoluteLink method. See Section 9.7, "Make All Paths Absolute".)

In the Employee Benefit application, some of the places where you have to use the parameterizeLink method are:

• to navigate from the ID page to the Info page

• to navigate from the Info page to the Add Benefit or the Remove Benefit pages

The following files are affected: addBenefitToEmployee.jsp, removeBenefitFromEmployee.jsp, queryEmployee.jsp, error.jsp, and success.jsp.

The following example shows a link with two parameters in the query string.

• Running outside a portal environment:

  // from addBenefitsToEmployees.jsp
  <a href="/empbft/controller?action=queryEmployee&amp;empID=<%=empId%>">Query
        the same employee</a>
  
  

• Running within a portal environment:

  // from addBenefitsToEmployees.jsp
  <%
    String fAction = HttpPortletRendererUtil.portletParameter(request,
                           SessionHelper.ACTION_PARAMETER);
    String fEmpId  = HttpPortletRendererUtil.portletParameter(request,
                           SessionHelper.EMP_ID_PARAMETER);
  %>
  ...
  <a href="<%=HttpPortletRendererUtil.parameterizeLink(request,
      PortletRendererUtil.PAGE_LINK,
      HttpPortletRendererUtil.portletParameter(request, "next_page") +
                "=controller" + "&amp;" +
                fAction + "=queryEmployee" + "&amp;" +
                fEmpId + "=" + empId)%>">Query the same employee</a>
  

9.4.2 The next_page Parameter

In the example above, you may have noticed that the target of the link, which is the controller, is specified as the value of the next_page parameter. The reason for this is that requests in a portal environment are always directed to the portal. The portal then forwards the requests to providers (see Section 9.1, "How Portal Processes Requests"). For the provider to send the request to a specific target, you specify the target in the next_page parameter.

The name of the next_page parameter is specified in the provider.xml file (in the WEB-INF/providers/empbft directory in the webapp.war file). You can define the name of the parameter to be anything you want: it is the value of the pageParameterName tag.

In URLs for the application, the query string contains the next_page parameter. Portal sends the query string to the provider, which does the following:

1. The provider sees next_page as a special parameter.

2. The provider sends the request to the value of the parameter (controller).

3. The controller and other objects in the application process the request as normal.

   // provider.xml
   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <?providerDefinition version="3.1"?>
   
   <provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
      <session>false</session>
      <useOldStyleHeaders>false</useOldStyleHeaders>
   
      <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
         <id>1</id>
         <name>EmployeeBenefit</name>
         <title>Employee Benefit Portlet</title>
         <description>This portlet provides access to Employee Benefit 
   Application.</description>
         <timeout>10000</timeout>
         <timeoutMessage>Employee Benefit Portlet timed out</timeoutMessage>
         <showEdit>false</showEdit>
         <showEditDefault>false</showEditDefault>
         <showPreview>false</showPreview>
         <showDetails>false</showDetails>
         <hasHelp>false</hasHelp>
         <hasAbout>false</hasAbout>
         <acceptContentType>text/html</acceptContentType>
         <renderer class="oracle.portal.provider.v2.render.RenderManager">
            <renderContainer>true</renderContainer>
            <contentType>text/html</contentType>
            <showPage>index.jsp</showPage>
            <pageParameterName>next_page</pageParameterName>
         </renderer>
      </portlet>
   
   </provider>
   

9.4.3 Linking to the ID Page

This is a special case to link to the ID page of the application. You can use this link as the first link to the application.

To create a link to the ID page and display it in the portal page, you need to use the following URL:

<%@ page import="oracle.portal.provider.v2.render.http.HttpPortletRendererUtil" %>
<%@ page import="oracle.portal.provider.v2.render.PortletRendererUtil" %>
...
<a href="<%=HttpPortletRendererUtil.parameterizeLink(request,
     PortletRendererUtil.PAGE_LINK,
     HttpPortletRendererUtil.portletParameter(request, "next_page") + "=controller")%>">

Note that the <a> tag uses JSP scriptlets. This means that this link has to be in a JSP file; it cannot be in an HTML file.

The href attribute uses JPDK APIs to ensure that the portal processes the link correctly, and that the Employee Benefit application sends the request to the controller object. This chapter explains why you have to express the link in this fashion.

After Oracle9iAS runs the JSP scriptlet, you end up with a link that looks something like:

http://<host>/servlet/page?_pageid=58,60&_dad=portal30&_schema=PORTAL30&
                     _pirefnull.next_page=controller

9.5 Use include instead of the forward Method

Call the include method instead of forward. You have to use include because the portal needs to add data from other providers. If you use forward, the portal does not have a chance to gather data from the other providers. See Figure 9-1.

• Running outside a portal environment:

  RequestDispatcher rq = req.getRequestDispatcher(forward);
  rq.forward(req, res);
  

• Running within a portal environment:

  RequestDispatcher rq = req.getRequestDispatcher(forward);
  rq.include(req, res);
  

The only class that calls forward is the AbstractActionHandler abstract class.

9.6 Protect Parameter Names

Ensure that parameter names on your page do not conflict with parameter names from other pages in the portal. To protect your parameters, call the portletParameter method in the HttpPortletRendererUtil class to ensure that your parameters have unique names. The method prefixes parameter names with a unique string for each application; this enables applications to use the same parameter name safely.

By using the method, you ensure that your applications on the portal page read only their parameters and not parameters from other applications.

You have to use the method to protect all your field names in your HTML forms. You have to do this when retrieving and setting values for the fields.

The following files are affected: AddBenefitToEmployee.java, Controller.java, QueryEmployee.java, RemoveBenefitFromEmployee.java, addBenefitToEmployee.jsp, removeBenefitFromEmployee.jsp, queryEmployee.jsp, error.jsp, and success.jsp.

When you use the methods to protect the parameters, the links look something like the following:

• For add benefit actions:

  http://<host>/servlet/page?_pageid=58%2C60&_dad=portal30&_schema=PORTAL30&
  _pirefnull.action=addBenefitToEmployee&_pirefnull.next_page=controller&
  _pirefnull.empID=125
  

• For remove benefit actions:

  http://<host>/servlet/page?_pageid=58%2C60&_dad=portal30&_schema=PORTAL30&
  _pirefnull.action=removeBenefitFromEmployee&
  _pirefnull.next_page=controller&_pirefnull.empID=125
  

• For query employee actions:

  http://<host>/servlet/page?_pageid=58%2C60&_dad=portal30&_schema=PORTAL30&
  _pirefnull.action=queryEmployee&_pirefnull.next_page=controller&
  _pirefnull.empID=125
  

The parameters used by the application are prefixed with _pirefnull. The other parameters in the URL are required by portal. Note also that the URL does not point to the controller directly. Instead it uses the _pirefnull.next_page parameter to indicate that the controller should handle the request. See Section 9.4.2, "The next_page Parameter" for details.

9.6.1 Retrieving Values

The following example retrieves the values of two parameters.

• Running outside a portal environment:

  // from AddBenefitToEmployee.java
  String benefits[] = req.getParameterValues(SessionHelper.BENEFIT_PARAMETER);
  String client = req.getParameter(SessionHelper.CLIENT_TYPE_PARAMETER);
  

• Running within a portal environment:

  // from AddBenefitToEmployee.java
  import oracle.portal.provider.v2.render.http.HttpPortletRendererUtil;
  ...
  String fBenefits = HttpPortletRendererUtil.portletParameter(req,
                     SessionHelper.BENEFIT_PARAMETER);
  String benefits[] = req.getParameterValues(fBenefits);
  String fClient = HttpPortletRendererUtil.portletParameter(req,
                   SessionHelper.CLIENT_TYPE_PARAMETER);
  String client = req.getParameter(fClient);
  

9.6.2 Setting Values

If your parameter is a form element (for example, a checkbox or a hidden element), you have to call the portletParameter method to protect the name before you can use it. The following example shows how to set the BENEFIT_PARAMETER in a form:

// from addBenefitsToEmployees.jsp
String fBenefits = HttpPortletRendererUtil.portletParameter(
                       request, SessionHelper.BENEFIT_PARAMETER);
<form ... >
...
<input type="checkbox" name="<%=fBenefits%>" value="<%=b.getId()%>">

9.7 Make All Paths Absolute

Make all URL paths absolute paths using the absoluteLink or the htmlFormActionLink method in the HttpPortalRendererUtil class, depending on the HTML tag.

You cannot use paths relative to the current page because Oracle9iAS sends requests to portal first, and portal sends requests to providers. See Figure 9-1. When providers get the requests, the current path is the portal, not to the current page. By using absolute paths, you ensure that the provider can find the proper object.

The following files are affected: addBenefitToEmployee.jsp, removeBenefitFromEmployee.jsp, queryEmployee.jsp, error.jsp, and success.jsp.

9.7.1 <a> and <link> Tags

Use the absoluteLink method to qualify paths in <a> and <link> tags.

• Running outside a portal environment:

  // from addBenefitToEmployee.jsp
  <link rel="stylesheet" type="text/css" href="css/blaf.css">
  

• Running within a portal environment:

  // from addBenefitToEmployee.jsp
  <link rel="stylesheet" type="text/css"
    href="<%= HttpPortletRendererUtil.absoluteLink(request,
                         "./css/blaf.css")%>"
  >
  

9.7.2 <form> Tag

Use the htmlFormActionLink method to qualify paths in the <form> tag.

• Running outside a portal environment:

  // from addBenefitToEmployee.jsp
  <form method="GET" action="/empbft/controller">
  

• Running within a portal environment:

  // from addBenefitToEmployee.jsp
  <form method="GET"
    action="<%=HttpPortletRendererUtil.htmlFormActionLink(request,
                              PortletRendererUtil.PAGE_LINK)%>">
  <%=HttpPortletRendererUtil.htmlFormHiddenFields(request,
                              PortletRendererUtil.PAGE_LINK)%>
  <input type="hidden"
    name="<%=HttpPortletRendererUtil.portletParameter(request, "next_page")%>"
    value="controller">
  

Note that in the portal version the action attribute does not point to the controller. Instead, it points to the portal. The actual target for the form is specified in a hidden field called next_page. The value of the hidden field specifies the target. See Section 9.4.2, "The next_page Parameter" for details.

When you use forms, you need to include additional parameters such as _dad and _schema. These parameters are needed by portal. To include these parameters, you can use the htmlFormHiddenFields method.