Oracle9iAS Portal Developer Kit
Understanding the Parameter Passing JSP Sample

Oracle9iAS Portal provides functionality for passing parameters between your portlets. This functionality permits Java portlets to communicate with each other.

PDK-Java comes with a JSP sample that illustrates parameter passing. This sample consists of two different portlets, the Parameter Passing portlet and the Parameter Receiving portlet, that illustrate how a parameter can be passed from one JSP portlet to another. 

This article describes how parameter passing is implemented in this sample. It also provides a guideline for passing parameters in your Java portlets.

Assumptions

How to Pass Parameters

The section 'How to Pass Parameters in Java Portlets' in the article An Overview of Parameters and Events explains how to do this.

The general model for passing parameters in Java portlets can be described as follows:

  1. Identify the parameters you need for your portlets to communicate.
  2. Identify the scope of each of your parameters. Use portlet instance level scoping for those parameters that need only be passed to the same portlet instance, i.e. itself. Such qualified parameters are available only to that instance of the portlet. Use page level scoping for parameters that need to be passed to other portlets. Such portlets need to share parameter names. Think of this as analogous to using global variables.
  3. Use the HttpPortletRendererUtil.portletParameter API to create your parameter names that are scoped by portlet instance. The PDK-Java API HttpPortletRendererUtil.portletParameter is used to automatically generate such qualified parameter names.
  4. Use constant strings to create your parameter names for those that are scoped at page level. However, while creating these names, it is recommended that you use a common application name or functionality reference as a prefix to scope the parameter. For example: betaHRApps.customerName where the prefix betaHRApps is understood by the portlet programmers as a common reference for naming your shared parameter names. Remember that no PDK-Java API is provided for this purpose and choosing a good parameter reference is part of good programming practice.
  5. Use request.getParameter() to access the passed parameter values in your portlets. The name passed to this API will either be a qualified generated parameter name, or an unqualified constant string that you've chosen to share between your portlets.

SAMPLE FUNCTIONALITY

This section describes the functionality of the two parameter passing samples.

Passing Parameters between Portlets Sample

This sample consists of two portlets, the Parameter Passing portlet and the Parameter Receiving portlet. Here's a screenshot of what you would see when you add these portlets to your page.

In the text box provided, enter some text. The example above shows that the user has entered "JPDK User" to the text box in the Parameter Passing portlet. Choose "Display in other portlet" and the name you entered is passed as a parameter to the Parameter Receiving portlet as shown in the screenshot below.

Note: If you choose "Display in this portlet", the parameter would be read by this portlet only. To understand how this works, read the section Understanding Passing Parameters Between Portlets Sample below.

UNDERSTANDING PASSING PARAMETERS SAMPLES

This section describes how parameter passing is accomplished in the PDK-Java samples.  Under the JPDK directory, the Parameter Passing samples are created using the following three JSP files located within the /htdocs/parameters directory - parampass.jsp, and  paramrecv.jsp. Please review the source code for more information on creating the Parameter Passing Portlets.

Passing Parameters Between Portlets Sample

  1. From the downloaded PDK-Java samples, review the parampass.jsp file in the parameters directory. An excerpt is provided below. This creates the Parameters Passing portlet.
  2. The parameter that needs to be scoped to the portlet instance level only, is created using the HttpPortletRendererUtil.portletParameter API. This code segment is highlighted below. This means that while using these names, they actually refer to parameter names that include the Provider ID, portlet ID and the portlet instance reference path. For example: 11075281.17.175_PARAMETERPASS_11075281.myParamSubmitThis.
    <%@ page import="oracle.portal.provider.v1.*,oracle.portal.provider.v1.http.*" session="false" %>

    <%

        // The form submit URL refers to the current Portal page. All portlets

        // on this page share this URL. This means that the per portlet parameters

        // are in the same request. Portlets must ensure that its parameters don't

        // collide either with other portlets or other instances of itself. This

        // is generally accomplished by using "fully-qualified" parameter names. A

        // fully-qualified parameter name prepends the (unique) portlet reference to

        // the parameter. The JPDK provides a utility to accomplish this.

        // Since we dont need other portlets to read this parameter, we can qualify

        // it so the page knows that this parameter belongs to only this portlet

        // instance.

        String pSubmitThis = HttpPortletRendererUtil.portletParameter(request, "myParamSubmitThis");

    %>

    <!-- Output the HTML content -->

    ...

  3. Scroll the file to the section that contains the HTML content. Observe that the portlet creates a form that sets the action URL using the JPDK API htmlFormActionLink. After this it creates a hidden field using the htmlFormHiddenFields API. If the hidden field is not created, you will get a java.lang.NullPointerException.
    ...

    <!-- Output the HTML content -->

    <BODY>

    This Parameter Passing portlet can talk to the Parameter Receiving portlet by using shared parameter names. Please ensure that you've added the Parameter Receiving portlet to the same page too. <p>

    <p>

    <center>

    <form name="parameters" method= "POST"action="<%= HttpPortletRendererUtil.htmlFormActionLink(request,PortletRendererUtil.PAGE_LINK) %>" >

     

    <%= HttpPortletRendererUtil.htmlFormHiddenFields(request,PortletRendererUtil.PAGE_LINK) %>

     

    Welcome to the <p>

    ...

  4. Scroll to the section that displays the Welcome message. Here the request.getParameter API is used to first find out whether the user pressed the "Display in this portlet" button by checking the qualified parameter name pSubmitThis. Then, the same API is used to retrieve and display the name that is sent from the text box, using the unqualified parameter name. Observe how this parameter is qualified by a user-defined reference and is called "sampleParams.unqualifiedParamName". This is to minimize unintentional usage of this parameter by some other portlet you did not develop.
    ...

    Welcome to the <p>

    <b>

    <%

        // Check to see if the button for displaying parameter in THIS

        // portlet only has been pressed.

        // If so print the value of the parameter that gets passed

        // automatically with the query string of the URL.

        if (request.getParameter(pSubmitThis) != null )

        {

    %>

            <%= request.getParameter("sampleParams.unqualifiedParamName") %>

    <%

        }

    %>

    </b>

     

    portlet <p>

    ...

  5. Additionally the portlet creates the form elements for the text box and the two buttons as illustrated below. As two of these element values needed to be used by other portlets we gave them unqualified parameter names, while the third is only used by the same portlet and hence is given a qualified parameter name, that was created in Step 2.

    ...

    portlet <p>

    <b>Write your name below:</b> <br>

    <!-- Provide unqualified name as parameter to be read by other portlet -->

    <input type="text" size="20" name="sampleParams.unqualifiedParamName" value="" > <Br>

    <!-- Provide qualified name as parameter need not be read by other portlet -->

    <input type= submitname="<%= pSubmitThis %>" value="Display in this portlet" >

    <!-- Provide unqualified name as parameter to be read by other portlet -->

    <input type=submit name="sampleParams.unqualifiedSubmitAll" value="Display in other portlet" >

    </form>

     

    </center>

    </BODY>

    <!-- End output the HTML content -->

  6. Now review the paramrecv.jsp file in the parameters directory. An excerpt is provided below. This creates the Parameters Receiving portlet.
  7. Here the request.getParameter API is used to first find out whether user pressed the "Display in other portlet" button by checking the unqualified parameter name "sampleParams.unqualifiedSubmitAll". Then the same API is used to retrieve and display the name that is sent from the text box, using the unqualified parameter name. Again, observe how these parameter are qualified by a user-defined reference that is shared by the two communicating portlets to minimize unintentional usage of this parameter by some other portlet you did not develop.

    <%@ Page import="oracle.portal.provider.v1.*,oracle.portal.provider.v1.http.*" Session="false" %>

     

    This Parameter Receiving portlet can display the parameter from the Parameter Passing portlet by using shared parameter names. Please ensure that you've added the Parameter Passing portlet to the same page too. <p>

    <p>

    <center>

    Hello

    <b>

    <%

        if (request.getParameter("sampleParams.unqualifiedSubmitAll") != null )

        {

    %>

            <%= request.getParameter("sampleParams.unqualifiedParamName") %>

    <%

        }

    %>

    </b>

    !!

    </center>
This sample shows you what you need to do when passing parameters using HTML forms.

VIEWING PORTLET FUNCTIONALITY

  1. Create an Oracle Portal page and then add both the Parameter Passing portlet and Parameter Receiving portlet to your page. 
  2. Notice how parameters are being communicated from one portlet to another.

Revision History