Table 13-1 lists the container runtime options supported by the WebCenter Portal portlet container.

For more information about the JSR 286 container runtime options, see the JSR 286 specification at:

http://jcp.org/en/jsr/detail?id=286

Setting container runtime options at the application level affects all the portlets in the application.

To set application-level container runtime options:

You can set container runtime options at the individual portlet level to override the application-wide settings.

To set portlet-level container runtime options:

For a public render parameter to be available to a portlet, it must first be declared in the application section of the portlet deployment descriptor file (portlet.xml).

To define a public render parameter at the application level:

1. Open the Overview Editor for the portlet.xml file.

   For more information, see How to Edit the Portlet Deployment Descriptor File.

2. Click the Parameters tab.

3. Click the Add icon to create a new public render parameter.

4. From the drop-down list, select whether you are specifying a fully qualified name (QName) for the parameter, or just the local part of the name.

   • Qualified Name—A QName uniquely identifies the public render parameter across applications by specifying a namespace for the parameter as well as a local name. Within the portlet code, a public render parameter is accessed by its identifier, which identifies the parameter uniquely within the application. However, a page typically contains multiple portlets which may come from different applications. Using QNames ensures that public render parameters from one portlet do not unintentionally interfere with the other portlets on a page regardless of where those portlets come from.

   • Unqualified Name—If the namespace for the parameter is the same as the application default namespace, you can omit the namespace when defining the parameter by specifying an unqualified name. If the application default namespace has not been defined, a parameter with an unqualified name uses the XML default namespace.

     Tip:

     To check whether an application default namespace has been defined, click the Application tab and see if a value has been entered in the Default Namespace field.

5. Enter a name for the parameter.

   • If you selected Qualified Name—in the Namespace field, enter the namespace for the parameter and in the Name field, enter the local part of the parameter name.

   • If you selected Unqualified Name—in the Name field, enter the local part of the parameter name. The parameter uses the application default namespace as the namespace for the parameter (or the XML default namespace if no default namespace is defined for the application).

6. In the Identifier field, enter a name to identify the public render parameter within the application.

   The identifier must be unique within the application and is used to identify the parameters used by a portlet and in the portlet code to access the parameter. Using the identifier means that portlet developers do not need to be aware of the parameter's fully qualified name; they simply need to know the simpler application-specific identifier.

7. In the Description field, enter a description for the public render parameter. The description should provide enough information so that portlet developers can determine how to use this parameter in their portlets.

8. (Optional) In the Aliases panel, you can provide a list of aliases so that the parameter can accept values from other public render parameters even if they have different QNames.

   1. Click the Create icon to create a new alias for the parameter.

   2. In the Namespace field, enter the namespace of the parameter to use for the alias.

   3. In the Name field, enter the local part of the parameter to use for the alias.

   Tip:

   When creating aliases for public render parameters, it is a good idea to set up reciprocal aliases. So if a parameter in portlet A has an alias to a parameter in portlet B, you should also, if possible, create an alias for the parameter in portlet B to the parameter in portlet A.

9. The public render parameter is added to the application definition section of the portlet.xml file, as shown below.

   <public-render-parameter>
    <description>Parameter for zip code</description>
    <identifier>Zip</identifier>
    <qname xmlns:x="http://example.com/params">x:Zip</qname>
    <alias xmlns:x="http://example.com/params">x:ZipCode</alias>
   </public-render-parameter>
   

10. Save the portlet.xml file.

If you want a portlet to support a public render parameter, add it to the portlet.

To add a public render parameter to a portlet:

The following example shows how to use public parameters to link the behavior of two portlets using parameters with different names. In the example, we take a generic Parameter Form portlet that allows us to update public render parameters, and show how that can be linked to a Stock Price portlet that renders stock prices, taking the stock symbol from a public render parameter. The generic name of the parameter from the Parameter Form portlet (parameter1) does not match the name of the parameter in the Stock Price portlet (stocksymbol), so the developer of the Stock Price portlet uses an alias to provide a link between the two parameters.

The example below shows an excerpt from the portlet.xml file for the portlet producer application that contains the Parameter Form portlet. The portlet producer application defines a public render parameter (parameter1) that is supported by the Parameter Form portlet.

<portlet-app ...>
 <portlet id="1234567890">
 ...
 <supported-public-render-parameter>
 parameter1
 </supported-public-render-parameter>
 ...
 </portlet>
 ...
 <public-render-parameter>
 <description xml:lang="en">First parameter set by portlet</description>
 <identifier>parameter1</identifier>
 <qname xmlns:op="http://xmlns.oracle.com/portlet/oracle-portlet-app">
 op:parameter1
 </qname>
 </public-render-parameter>
 ...
</portlet-app>

The code for the Parameter Form portlet sets the value of the parameter1 portlet when a value is entered in the portlet:

public void processAction(ActionRequest request,
 ActionResponse actionResponse)
 throws PortletException, IOException
{
 //
//Read the new parameter value posted in the portlet form
 //
String param1 =actionResponse.getParameter("form_param1");

 //
//Set the new parameter values. These will be intepreted by the
 //container as public render parameters as the names match the names
 //of the declared parameters.
 //
actionResponse.setRenderParameter("parameter1", param1);
}

The following example shows an excerpt from the portlet.xml file for the portlet producer application that contains the Stock Price portlet. This portlet producer application also defines a public render parameter (stocksymbol) that is supported by the Stock Price portlet. For the stocksymbol parameter to link to the Parameter Form portlet's parameter, an alias for parameter1 is added.

<portlet-app ...>
 <portlet>
 ...
 <supported-public-render-parameter>
 stocksymbol
 </supported-public-render-parameter>
 ...
 </portlet>
 ...
 <public-render-parameter>
 <description xml:lang="en">The stock symbol</description>
 <identifier>stocksymbol</identifier>
 <qname xmlns:s="http://www.oracle.com/stocks">s:stocksymbol</qname>
 <!-- Alias matches the Parameter Form portlet's first parameter name -->
 <alias xmlns:op="http://xmlns.oracle.com/portlet/oracle-portlet-app">
 op:parameter1
 </alias>
 </public-render-parameter>
 ...
</portlet-app>

The code for the Stock Price portlet reads the value of the public render parameter posted by the Parameter Form portlet:

public void doView(RenderRequest request, RenderResponse response)
 throws PortletException, IOException
{
 response.setContentType("text/html; charset=UTF-8");
 PrintWriter out =response.getWriter();
 
//Retrieve any values for the public render parameter.
 //The parameter is looked up in the request using its identifier in portlet.xml
 //(not it's name or alias).
 String symbol =request.getParameter("stocksymbol");
 ...
}

When these two portlets are dropped onto the same page, they are automatically linked together. Entering a value in the first parameter field of the Parameter Form portlet causes the Stock Price portlet to be updated with the new value.

For a portlet event to be available to a portlet, it must first be declared in the application section of the portlet deployment descriptor file (portlet.xml).

To define a portlet event at the application level:

1. Open the Overview Editor for the portlet.xml file.

   For more information, see How to Edit the Portlet Deployment Descriptor File.

2. Click the Events tab.

3. Click the Add icon to create a new portlet event.

4. From the drop-down list, select whether you are specifying a fully qualified name (QName) for the portlet event, or just the local part of the name.

   • Qualified Name—A QName uniquely identifies the portlet event across applications by specifying a namespace for the event as well as a local name. A page typically contains multiple portlets which may come from different applications. Using QNames ensures that portlet events from one portlet do not unintentionally interfere with the other portlets on a page regardless of where those portlets come from.

   • Unqualified Name—If the namespace for the portlet event is the same as the application default namespace, you can omit the namespace when defining the event by specifying an unqualified name. If the application default namespace has not been defined, a portlet event with an unqualified name uses the XML default namespace.

     Tip:

     To check whether an application default namespace has been defined, click the Application tab and see if a value has been entered in the Default Namespace field.

5. Enter a name for the portlet event.

   • If you selected Qualified Name—In the Namespace field, enter the namespace for the portlet event and in the Name field, enter the local part of the event name.

   • If you selected Unqualified Name—In the Name field, enter the local part of the portlet event name. The event uses the application default namespace as the namespace for the event (or the XML default namespace if no default namespace is defined for the application).

6. In the Payload Type field, enter or browse for the data type of the payload provided by the portlet event.

7. In the Description field, enter a description for the portlet event.

8. (Optional) In the Aliases panel, you can provide a list of aliases so that a portlet event can be recognized by the portlet even if it has a different QName from the one defined by the portlet.

   1. Click the Create icon to create a new alias for the portlet event.

   2. In the Namespace field, enter the namespace of the portlet event to use for the alias.

   3. In the Name field, enter the local part of the portlet event to use for the alias.

9. The portlet event is added to the application definition section of the portlet.xml file, as shown below.

   <event-definition id="latLong">
    <qname xmlns:x="http://xmlns.oracle.com/portlet/EventSample">
    x:latLong
    </qname>
    <value-type>portlet.LatLong</value-type>
   </event-definition>
   

10. Save the portlet.xml file.

If you want a portlet to listen for a particular portlet event, define it as a processing event.

To add a processing event to a portlet:

If you want a portlet to trigger a particular portlet event, define it as a publishing event.

To add a publishing event to a portlet:

The following example shows how to use portlet events to use the actions in one portlet to affect another portlet on the same page. In the example, we have a portlet, the Department Locations portlet, that lists the geographical locations of a company's various offices. The example shows how that portlet can be linked to another portlet, the Map portlet, which displays a Google map of the location selected in the Department Locations portlet.

The example below shows an excerpt from the portlet.xml file for the portlet producer application that contains the two portlets. The portlet producer application defines a portlet event (latLong) that is supported by the two portlets. The payload of the event is an object that encapsulates the latitude and longitude of a location.

<event-definition id="latLong">
 <qname xmlns:x="http://xmlns.oracle.com/portlet/EventSample">x:latLong</qname>
 <value-type>portlet.LatLong</value-type>
</event-definition>

The next example shows that the Department Locations portlet uses the latLong event as a publishing event. That is, it raises the event under particular circumstances.

<portlet id="locations">
 ...
 <supported-publishing-event>
 <qname xmlns:x="http://xmlns.oracle.com/portlet/EventSample">x:latLong<qname>
 </supported-publishing-event>
 ...
</portlet>

The Department Locations portlet raises the latLong event in its processAction method if a location is selected in the portlet (see example below). It also sets the payload of the event to the latitude and longitude of the selected location.

public void processAction(ActionRequest request, ActionResponse response)
 throws PortletException
 {
String locationId =request.getParameter("locationId");
 Location location =getLocation(Integer.parseInt(locationId));

 if (location != null)
 {
//QName matches the event declared as a supported-publishing-event in
 //portlet.xml for this portlet.

 //LatLong event used by the Map portlet.
 response.setEvent(new QName("http://xmlns.oracle.com/portlet/EventSample", "latLong"),
 new LatLong(location.getLatitude(), location.getLongitude()));

 }
}

The example below shows another portlet, the Map portlet, that also uses the latLong event, but this time as a processing event. That is, it listens out for the event and takes a particular action if the event is raised elsewhere on the page.

<portlet id="map">
 ...
 <supported-processing-event id="latLong">
 <qname xmlns:x="http://xmlns.oracle.com/portlet/EventSample">x:latLong</qname>
 </supported-processing-event>
 ...
</portlet>

The processEvent method for the Map portlet receives the latLong event and uses the payload from that event to set the LAT_LONG_PARAMETER render parameter, which the portlet uses during rendering to determine the location to display in the Google map:

@Override
 public void processEvent(EventRequest request,
 EventResponse response)
 throws PortletException, IOException
 {
response.setRenderParameters(request);
 
Event event =request.getEvent();
 if (event.getName().equals("latLong"))
 {
response.setRenderParameter(LAT_LONG_PARAMETER, event.getValue().toString());
 }
}

<event-definition id="geolocation"> <qname xmlns:x="http://xmlns.oracle.com/portlet/Map">
 x:geolocation
 </qname> <alias xmlns:x="http://xmlns.oracle.com/portlet/EventSample">
 x:latLong
 </alias>
 <value-type>portlet.LatLong</value-type>
</event-definition>

To enable users to modify portlet behavior or content at runtime, you must create portlet preferences for those attributes of the portlet that you want users to be able to modify.

To add a portlet preference to a portlet:

The following example provides a simple illustration of how you can enable personalization in portlets.

To add simple personalization to a portlet:

For a portlet to be able to use a portlet filter, the filter must first be defined within the application.

To add a portlet filter to an application:

1. Open the Overview Editor for the portlet.xml file.

   For more information, see How to Edit the Portlet Deployment Descriptor File.

2. Click the Filters tab.

3. Click the Add icon to create a new portlet filter.

4. In the Create Portlet Filter dialog you can either create a new portlet filter, or select a previously created portlet filter:

   • To create a new portlet filter:

     1. Select New Portlet Filter.

     2. In the Name field, enter a name for the portlet filter.

        The name must be unique within the application and use only letters, numbers, and the underscore character.

     3. In the Package field, enter or browse for the package to contain the new filter class.

     4. Select one or more of the Lifecycle Phase check boxes to specify which of the javax.portlet.filter interfaces the filter class implements:

        Action—The filter class implements the ActionFilter interface

        Event—The filter class implements the EventFilter interface.

        Render—The filter class implements the RenderFilter interface.

        Resource—The filter class implements the ResourceFilter interface.

        Tip:

        When you create a new filter class using the Create Portlet Filter dialog, you can specify which of the filter interfaces the filter class implements. After the filter class has been created, you cannot add or remove filter interfaces through the Overview Editor. Instead, you must edit the source of the filter class directly to manually add or remove the interfaces and the doFilter methods defined for those interfaces.

   • To select an existing portlet filter:

     1. Select Choose from Existing Class.

     2. Enter or browse for the filter class.

5. Click OK.

6. In the Display Name field, enter a more user-friendly name for the portlet filter.

7. In the Description field, enter a description for the portlet filter.

8. In the Initialization Parameters panel, you can specify initialization parameters that pass values to the init() method of the filter class.

   1. Click the Add icon to specify an initialization parameter for the portlet filter.

   2. In the Name field, enter the name of the initialization parameter.

   3. In the Value field, enter the value to pass to the initialization parameter.

   4. In the Description field, enter a description of the initialization parameter.

   The portlet filter is added to the application definition section of the portlet.xml file, as shown below.

   <filter>
    <display-name>Test Filter</display-name>
    <filter-name>filter_1</filter-name>
    <filter-class>javaportlets.MyFilter</filter-class>
    <lifecycle>ACTION_PHASE</lifecycle>
    <lifecycle>RENDER_PHASE</lifecycle>
   </filter>
   

9. Save the portlet.xml file.

After the portlet filter has been defined in the application, you can then apply it to one or more portlets within the application. You can also specify the order in which portlet filters are applied to portlets.

To apply a portlet filter to a portlet:

You can choose to implement expiry-based caching when you first create a portlet using the Create JSR 286 Portlet Wizard. However, during the initial development of a portlet, you may prefer to turn portlet caching off and implement it later in the development cycle when the portlet content becomes more stable. You may also want to edit the expiration period, or change the cache scope.

To implement expiry-based caching:

Implementation of validation-based caching takes place after the initial portlet creation and requires hand coding.

The example below shows how a GenericPortlet would typically implement its doView() method such that the consumer caches the markup using validation-based caching. The example also shows how expiry-based caching can be defined programmatically (using the CacheControl.setExpirationTime() method) and used in conjunction with validation-based caching to further reduce the load on the producer. This would work equally well for serveResource().

protected void doView (RenderRequest request, RenderResponse response)
 throws PortletException, IOException 
{
CacheControl cacheControl =response.getCacheControl();
 String eTag =request.getETag();
 if (isMarkupStillValid(eTag)) 
{
//Wait 30 seconds before checking ETag again
 cacheControl.setExpirationTime(30); 
//Tell consumer to use its cached content
 cacheControl.setUseCachedContent(true);
 return;
 }
//ETag not valid so set a new one ...
 //Define a new ETag
 cacheControl.setETag(generateETag(...));
 //Wait 60 seconds before checking ETag again
 cacheControl.setExpirationTime(60);
 //... and generate fresh portlet markup
 createMarkup(request, response);
}
private boolean isMarkupStillValid(String eTag)
{
 if (eTag ==null)
 {
return false; //No ETag was supplied
 }
//Perform portlet specific checks for the consumer's cached 
//copy of the markup still being valid based on the given ETag
 ...
}
private String generateETag(...)
{
 //Portlet specific code to generate an ETag, for example, a hash 
//of the data on which the portlet's markup is based
 ...
 return eTag;
}

For more information about validation-based caching in JSR 286 portlets, see the JSR 286 specification at:

http://jcp.org/en/jsr/detail?id=286

Table 13-2 lists and describes the JNDI variables used to specify the persistence store for WSRP producers.

WSRP portlet producers use a JNDI variable (persistentStore) to determine which type of persistence store to use. When you create a portlet for the first time in an application, by default this variable is set to Consumer. You can change the value of this variable in the web.xml file of the portlet producer application.

If you use a File persistence store, you must also use the fileStoreRoot JNDI variable to specify the path to the root directory to be used by the persistence store. See JNDI Variables for WSRP Producer Persistence Store.

To set up the persistence store for a WSRP portlet producer:

If you do not want all users to be able to see the WSRP test page, you can protect it so that only administrators can see it.

To hide the WSRP test page:

You can remove the WSRP test page completely.

To remove the WSRP test page, you must edit an element that is injected into the web.xml file at packaging time, so you must edit the web.xml file in the resulting EAR file.

To remove the WSRP test page: