5 Configuring Remote Portlets

This chapter discusses ways you can modify and configure remote portlets within Oracle Enterprise Pack for Eclipse.

This chapter includes the following sections:

Section 5.1, "Applying a Look and Feel to a Remote Portlet"
Section 5.2, "Modifying Modes and States in a Remote Portlet"
Section 5.3, "Handling Errors in Remote Portlets"
Section 5.4, "Setting Preferences on a Remote Portlet"
Section 5.5, "Using Backing Files with Remote Portlets"
Section 5.6, "Setting a Timeout Value on a Remote Portlet"
Section 5.7, "Modifying WSRP Markup and Messages"
Section 5.8, "Remote Portlet Properties"

5.1 Applying a Look and Feel to a Remote Portlet

The look and feel of a portlet determines the appearance of a portlet on the portal desktop. A remote portlet's look and feel is not linked to a producer, giving you the option of modifying the portlet's appearance on the consumer. This capability allows you to match the appearance of the consumer portal in which the proxy portlet resides.

Specific procedures for applying a look and feel to a portlet are documented elsewhere. Please refer to the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal for detailed information on these topics:

Creating Look and Feels
Look and Feel Architecture
The Portal User Interface Framework
How Look and Feel Determines Rendering
Style Sheet Class Reference
Creating Skins and Skin Themes
Creating Skeletons and Skeleton Themes

5.2 Modifying Modes and States in a Remote Portlet

This section explains how to modify a remote portlet's modes and states and includes these topics:

Section 5.2.1, "What are Modes and States?"
Section 5.2.2, "Modes and States in Remote Portlets"
Section 5.2.3, "Changing Modes and States in Remote Portlets"

5.2.1 What are Modes and States?

A portlet's title bar can contain up to six buttons. These buttons provide convenient functions called modes and states.

Figure 5-1 shows an example portlet with all of the modes and states enabled.

Figure 5-1 Portlet with Modes and States

Description of "Figure 5-1 Portlet with Modes and States "

The modes include:

Edit – Activates a custom file that lets you modify the portlet's content.
Help – Activates a help file.

The states include:

Minimize – Minimizes the portlet.
Maximize – Maximizes the portlet.
Delete – Removes the portlet from the portal.
Float – Displays the portlet in a separate window.

For more detailed information on modes and states, how they work, and how to add and configure them in portlets, refer to the Portlet User Guide.

5.2.2 Modes and States in Remote Portlets

Table 5-4 describes how states are transferred by default from a portlet deployed on a producer to its remote proxy in a consumer application. The table also indicates whether or not the state is editable in the remote portlet.

Table 5-1 Default Behavior of States in Remote Portlets

State of Producer Portlet	Default State of Proxy Portlet	Is the Proxy Portlets's State Editable?
Delete = `true`	Delete = `true`	No
Delete = `false`	Delete = `false`	No
Maximize = `true`	Maximize = `true`	No
Maximize = `false`	Maximize = `false`	No
Minimize = `true`	Minimize = `true`	No
Minimize = `false`	Minimize = `false`	No
Float = `true`	Float = `true`	No
Float = `false`	Float = `false`	No

Table 5-4 describe how modes are transferred by default from a portlet deployed on a producer to its remote proxy in a consumer application. The table also indicates whether or not the mode is editable in the remote portlet. For instance, if the Help mode is set in the portlet deployed on the producer, it is also set in the remote proxy; however, you cannot remove it from the remote proxy. On the other hand, if Help is not set in the portlet deployed on the producer, you are free to add it to the remote portlet.

Table 5-2 Default Behavior of Modes in Remote Portlets

Mode of Producer Portlet	Default Mode of Proxy Portlet	Is the Proxy Portlets's Mode Editable?
Help = `true`	Help = `true`	No
Help = `false`	Help = `false`	Yes
Edit = `true`	Edit = `true`	No
Edit = `false`	Edit = `false`	Yes

Note:

Both the help and the edit mode each reference a file that provides appropriate content for those actions. For example, the help mode references a help file. For these modes to work in a proxy portlet, the files they reference must exist on the consumer in the same relative location as they exist on the producer system.

5.2.3 Changing Modes and States in Remote Portlets

All of the modes and states that are available in local portlets are available in their remote proxies. Note, however, that when you create a remote portlet, it is not possible to edit (add or remove) all of the modes and states in the remote portlet. In addition, the Float state is always turned off in a remote portlet by default; however, you are free to add it to the remote portlet in the consumer application if you wish.

The procedure for changing the default mode and state settings in a remote portlet is the same as with a local portlet.

Double-click the portlet file in the Package Explorer view to open it in the editor.
Click in the header portion of the portlet in the editor, as shown in Figure 5-2. This opens the Portlet Titlebar properties in the Properties view, as shown in Figure 5-3

Figure 5-2 Click in the Header of the Portlet

Description of "Figure 5-2 Click in the Header of the Portlet"
Click on the Portlet Titlebar values to change them.

Figure 5-3 Header Properties View

Description of "Figure 5-3 Header Properties View"

5.3 Handling Errors in Remote Portlets

Under some circumstances, a remote portlet may be unable to access its producer. In this case, the consumer throws an exception. This section explains how to handle this exception by displaying an error page.

There are two ways to configure an error page for a remote portlet to be displayed if the remote portlet is unable to connect to its producer. You can configure the page in Oracle Enterprise Pack for Eclipse or in the remote portlet's XML file.

Tip:

For finer control of error handling, consider using interceptors. The interceptor framework is described in Chapter 9, "The Interceptor Framework."

This section includes these topics:

Section 5.3.1, "Configuring an Error Page in Oracle Enterprise Pack for Eclipse"
Section 5.3.2, "Configuring an Error Page in the .portlet File"

5.3.1 Configuring an Error Page in Oracle Enterprise Pack for Eclipse

To configure an error page for a remote portlet using Oracle Enterprise Pack for Eclipse:

In Oracle Enterprise Pack for Eclipse, display the Outline view for the remote portlet. To do this, select Window > Show View > Other. In the Show View dialog, select Basic > Outline.
In the Outline View, click Proxy Content, as shown in Figure 5-4.

Figure 5-4 Selecting the Proxy Content Node

Description of "Figure 5-4 Selecting the Proxy Content Node"
Click the Properties tab to display the Properties view for the Proxy Content. This view contains one property, Error URI, as shown in Figure 5-5.

Figure 5-5 Entering the Error Filename

Description of "Figure 5-5 Entering the Error Filename"
In the Error URI field, enter (or browse to) the name of the error file you want to associate with the portlet. The portlet displays this page in the event of an error.

The Error URI specifies a file path that is relative to the project in which the remote portlet is located.

5.3.2 Configuring an Error Page in the .portlet File

You can also configure an Error URI in a remote portlet's .portlet file. To do this, open the .portlet file and add the following element, where the value of the errorUri attribute is the name of the error file to be displayed:

<netuix:proxyPortletContent errorUri="errorFileName.jsp"/>

The errorURI attribute specifies a file path that is relative to the project in which the remote portlet is located.

Example 5-1 shows the complete XML file for a remote portlet, with an example <netuix:proxyPortletContent> element highlighted in bold.

Example 5-1 Remote Portlet XML File

<?xml version="1.0" encoding="UTF-8"?>
<portal:root
    xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
    xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0 portal-support-1_0_0.xsd">

    <netuix:proxyPortlet
        cacheExpires="300" definitionLabel="portlet_5_1" description=""
        doesUrlTemplateProcessing="true" forkRender="false"
        forkable="false" groupId="Consumer" portletHandle="portlet_5"
        producerHandle="consumerProducer" renderCacheable="true"
        templatesStoredInSession="true" title="Remote Preferences">
        <netuix:titlebar><netuix:maximize/><netuix:minimize/></netuix:titlebar>
        <netuix:proxyPortletContent errorUri="error.jsp"/>
    </netuix:proxyPortlet>
</portal:root>

5.4 Setting Preferences on a Remote Portlet

Portlet preferences function in remote portlets in much the same way as they do in local portlets. Just as with local portlets, remote portlets can take advantage of portlet preferences to allow users to customize the presentation of the portlet.

This section discusses the use of portlet preferences in remote portlets and includes these topics:

Section 5.4.1, "What is a Portlet Preference?"
Section 5.4.2, "Portlet Preferences and Remote Portlets"
Section 5.4.3, "Managing Portlet Instances through Registration"

Note:

This section assumes that you are familiar with the concept of a portlet preference and how to create and configure portlet preferences. If you are unfamiliar with portlet preferences, see the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.

5.4.1 What is a Portlet Preference?

Portlet preferences allow portlets to modify, store, and access pre-defined String values. When these preference values are retrieved by a portlet, they typically affect the way the portlet is displayed for a given user. For example, a stock portfolio portlet might allow users to specify which stocks they want to view. Through a user interface, users select or enter which stocks they want to view in the portlet. The list of stocks is then passed to the server and stored in the database for that particular user. As long as a portlet preference is modifiable, and an interface is provided for editing preferences, every user of a portlet can configure his or her own personal view of the portlet.

A clearly defined API exists for setting and retrieving preferences. Developers can create preferences in Oracle Enterprise Pack for Eclipse, and administrators can create and edit preferences using the WebLogic Portal Administration Console.

5.4.2 Portlet Preferences and Remote Portlets

In a federated configuration, the producer stores and manages portlet preferences. When you view or modify the preferences in a remote portlet (on a consumer), the consumer must fetch the preferences from the producer, and modifications must be sent back to the producer where they are stored.

Note:

Portlet preferences are included in the WebLogic Portal implementation of WSRP producers. Other WSRP producer implementations may not support portlet preferences.

5.4.2.1 Viewing and Modifying Preferences

You can view and modify the portlet preferences for a remote portlet using the WebLogic Portal Administration Console. The Administration Console uses the Portlet Management interface of WSRP to retrieve preferences from the producer and modify them.

Note:

It is not possible to create or modify portlet preferences in a remote portlet using Oracle Enterprise Pack for Eclipse.

Figure 5-6 shows the interface for creating a portlet preference in the WebLogic Portal Administration Console. A similar interface exists for editing a preference. For instance, you can change the default value for a preference, or make it read-only.

Figure 5-6 Creating a Portlet Preference in the WebLogic Portal Administration Console

Description of "Figure 5-6 Creating a Portlet Preference in the WebLogic Portal Administration Console"

Tip:

Changes you make to a portlet preference in the Administration Console are scoped either at the Library level or the instance level. If you modify a portlet preference in the Library, all subsequent instances of that portlet will include the change. If you modify an instance (in the Portals folder) only that instance is affected. In other words, if the same portlet is used in several desktops, a new instance of the portlet is generated for each use. When you modify an instance of a portlet, only that instance is modified. Note that the first time a user updates a portlet preference, a new instance of the portlet is created, and the updated preferences are associated with the new instance. The WSRP registration interface provides a way for producers to keep track of new portlet instances created for remote portlets. See Section 5.4.3, "Managing Portlet Instances through Registration" for more information.

5.4.2.2 Working with Preferences Programatically

Portlets can also create, retrieve, and modify preferences programatically by obtaining a javax.portlet.PortletPreferences object. For instance, a page flow portlet can retrieve an instance of this object from the PortletBackingContext object in an action method. For example, the page flow action method shown in Example 5-2 retrieves from a FormData object a preference set by a user, sets the preferences in a PortletPreferences object, and stores the preferences in the database using the store() method.

Note:

Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.

Example 5-2 Setting Portlet Preferences in an Action Method

/**
 * @jpf:action
 * @jpf:forward name="success" path="index.jsp"
 */
 protected Forward setColor(ColorForm form) {

 //-- Retrieve a preferences object from the context.
    PortletBackingContext context =
    PortletBackingContext.getPortletBackingContext(getRequest()); 
    PortletPreferences prefs = context.getPreferences(getRequest());
 
 //-- Set the user's preference.
 try {
  prefs.setValue("color", (String)form.getColor()[0]);
 } catch (ReadOnlyException e) {
      e.printStackTrace();
    }

    //-- Store the user's preference.
    try {
       prefs.store();
    } catch (ValidatorException io) {
       io.printStackTrace();
    } catch (IOException ioe) {
       ioe.printStackTrace();
    }

    return new Forward("success");
 }

As noted previously, for a remote portlet, preferences are hosted and managed on the producer. No preference information is ever stored on the consumer.

5.4.2.3 Additional Usage Notes and Restrictions

This section lists additional information about using portlet preferences in remote portlets.

You cannot add portlet preferences to remote portlets consumed from a simple producer or from producers that have portal management disabled in the wsrp-producer-config.xml file.
Portlets are not allowed to make persistent state changes during rendering. The store() method in javax.portlet.PortletPreferences throws an IllegalStateException if a portlet calls the store() method during the render phase of a portlet (that is, during the execution of the getMarkup operation).
Portlets, whether remote or not, cannot be customized in any way, including the modification of portlet preferences, in either of these two cases: (a) the portlet is in a file-based portal (that is, rendered from a .portal file or (b) the user accessing the portlet is anonymous (not authenticated). Consumer portlets communicate this to the producer by sending a value of readOnly for the portletStateChange element in the performBlockingInteraction request.
If the instance of a remote portlet is shared among several users, WebLogic Portal consumer sends a value of cloneBeforeWrite for the portletStateChange element. This value indicates to the producer that it must clone the portlet before making changes to preferences. If a portlet does indeed modify preferences, the producer returns a new portletHandle to the consumer. This new portletHandle replaces the original portletHandle.
On subsequent requests, the consumer sends a value of readWrite indicating that the producer can allow portlets to modify preferences.

5.4.3 Managing Portlet Instances through Registration

As discussed previously, whenever a user customizes a portlet by modifying portlet preferences, a new instance of the portlet is created. In the case of a remote portlet, the new instance is created on the producer, and the handle for that instance is returned to the consumer. Of course, as the number of users increases, the number of unique portlet instances can grow large in the producer space. If the consumer decides not to use the producer anymore, the producer needs to have a way of learning this and subsequently removing the portlet instances that are no longer needed. Portlet registration accomplishes this goal.

WebLogic Portal producers support registration by default for complex producers. If registration is enabled, consumers must register with a producer before accessing any of the producer's portlets. Once registered, the producer returns a registrationHandle to the consumer. The consumer must supply this handle on all future requests until the consumer is deregistered. When a consumer deregisters a portlet, the producer removes all of the portlet instances that were created for that consumer.

5.5 Using Backing Files with Remote Portlets

Backing files let you programatically add functionality to a portlet by implementing (or extending) a Java class, which enables preprocessing (for example, authentication) prior to rendering the portal controls. You can attach a backing file to a portlet using the Backing File property in the Properties View in Oracle Enterprise Pack for Eclipse.

Backing files let you implement business logic at certain points of a portlet's lifecycle. In a local portlet, backing file methods are called in the following order:

init()
handlePostbackData()
preRender()
dispose()

A producer, however, executes backing file methods in an order that reflects the type of consumer request, as shown in Table 5-4.

Table 5-3 Order of Backing File Method Execution in a Producer

Consumer Request	Order of Backing File Methods Called on the Producer
getMarkup()	`init()`, `preRender()`, `dispose()`
performBlockingAction()	`init()`, `handlePostbackData()`, `dispose()`
handleEvents()	`init()`, any event handler method, `dispose()`

For detailed information about backing files, see the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal. For an example that uses backing files with remote portlets, see Chapter 12, "Transferring Custom Data." See also Section 3.5, "Life Cycle of a Remote Portlet".

5.6 Setting a Timeout Value on a Remote Portlet

Occasionally, a producer is slow to respond to a request from a remote portlet. In this case, the portal application in which the remote portlet is located remains unresponsive until the remote portlet's response is received. This section explains how to set timeout values for remote portlets.

This section includes these topics:

Section 5.6.1, "Overview"
Section 5.6.2, "Setting Default Timeout Values"
Section 5.6.3, "Setting Timeouts for Individual Remote Portlets"

5.6.1 Overview

WebLogic Portal provides two timeout settings for remote portlets:

Connection Establishment Timeout – The amount of time a remote portlet will wait for a connection response from a producer.
Connection Timeout – The amount of time the remote portlet will wait for a response from a producer to which it is already connected.

You can set a default timeout limit for all remote portlets and a timeout limit for an individual remote portlet. The timeout set on an individual portlet takes precedence over the default.

The remote portlet connection timeout only works when a consumer is continually connected to a producer. The timeout is effective only for cases where the producer is slow to respond to a consumer, not for cases where the producer is physically unavailable (the connection is broken), or where a new connection is made. In these cases, the operating system's TCP timeout takes effect.

5.6.2 Setting Default Timeout Values

To set default timeout values for all remote portlets in a web application, edit one or both of the elements shown in Example 5-3. These elements appear in the configuration file wsrp-producer-registry.xml located in the WEB-INF directory of each portal web application.

Example 5-3 Connection Timeout Elements

<connection-establishment-timeout-msecs>-1</connection-establishment-timeout-msecs>
<connection-timeout-msecs>120000</connection-timeout-msecs>

Note:

Timeout values are in milliseconds.

5.6.3 Setting Timeouts for Individual Remote Portlets

To set a connection establishment and/or a connection timeout for an individual remote portlet, open the Properties view for the portlet in Oracle Enterprise Pack for Eclipse and set values for the Connection Establishment Timeout and Connection Timeout properties, as shown in Figure 5-7. The timeout values are in milliseconds.

Figure 5-7 Setting Timeout Properties

Description of "Figure 5-7 Setting Timeout Properties"

5.7 Modifying WSRP Markup and Messages

The Interceptor Framework is a consumer-side framework that lets you programatically intercept and modify markup and user interaction-related WSRP messages sent to and received from producers. The framework exposes a set of interfaces that you can implement. These interfaces let you examine the content of a WSRP message and take specific action based on that content. For example, if a producer sends a registration error back to the consumer, an interceptor can detect that error and display an informative message to the user or, perhaps, automatically return the information required to complete the registration.

For more information on creating interceptors, see Chapter 9, "The Interceptor Framework."

5.8 Remote Portlet Properties

This section lists and describes the set of Proxy Portlet Properties and other portlet properties that of interest to federated portal developers. This section includes these topics:

Section 5.8.1, "Proxy Portlet Properties"
Section 5.8.2, "Other Portlet Properties"

5.8.1 Proxy Portlet Properties

Table 5-4 lists the Proxy Portlet Properties. These properties appear in the Properties list for remote (proxy) portlets.

Table 5-4 Proxy Portlet Properties

Property	Value
Connection Establishment Timeout	Optional. The number of milliseconds after which this portlet will time out when establishing an initial connection with its producer.
Connection Timeout	Optional. The number of milliseconds after which this portlet will time out when communicating with its producer. If not specified here, the default value contained in the file `WEB-INF/wsrp-producer-registry.xml` is used.
Group ID	Read-only (assigned by the producer). If the producer associates this portlet within a group, the producer-assigned string appears here. Portlets with the same group ID from the same producer can share sessions.
Invoke Render Dependencies	Read-only (assigned by the producer). This boolean property allows the consumer to obtain render dependencies from the producer during the pre-render life cycle of a proxy portlet. When a portlet on a producer has a `lafDependenciesUri` value, the producer exposes the `invokeRenderDependencies` boolean in the portlet description. The value defaults to `false` if the attribute is not included in the `.portlet` file. The value is read-only, and is initialized from the producer whenever a proxy portlet is generated from the portlet wizard.
Portlet Handle	Read-only (assigned by the producer). The producer's unique identifier for the portlet that this proxy references.
Producer Handle	Required. The producer's unique identifier.
Required User Property Mode	Optional. Possible values are `none`, `all`, or `specified`. If the value is `specified`, then you must enter a list of property names in the field Required User Properties Names field.
Required User Property Names	Optional. Use this field if you entered a value of `specified` in the Required User Properties Mode field; enter a comma-delimited list of property names.
Templates Stored in Session	Read-only (assigned by the producer). Indicates whether the producer stores URL templates in the user's session on the producer side. This boolean is meaningful only when URL Template Processing boolean is set to `true`.
URL Template Processing	Read-only (assigned by the producer). Indicates whether the producer uses URL templates to create URLs. If true, the consumer supplies URL templates. If false, the producer rewrites URLs using special rewrite tokens.
User Context Stored In Session	Read-only (assigned by the producer). This boolean value defaults to `false` if the attribute is not included in the `.portlet` file. This value is initialized from the producer whenever a proxy portlet is generated from the portlet wizard.

5.8.2 Other Portlet Properties

Remote portlets also include properties that are common to other types of portlets. For a complete list and descriptions of all portlet properties, see "Portlet Properties" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.