Other Topics and Best Practices

This chapter focuses on best practices for developing portlets in a producer. By following the practices described in this chapter, you will help to ensure that remote portlets created in consumers function properly. We recommend that you review Federated Portal Architecture before using this chapter.

Support for WSRP Versions

WebLogic Portal supports the core features of WSRP 2.0, primarily to enable and assist with WSRP propagation. For details on WSRP propagation, see the section “WSRP Propagation” in the Production Operations Guide.

By default, WSRP 2.0 support is disabled for consumers. This section explains how to enable WSRP 2.0 support for WebLogic Portal consumers and discusses the supported WSRP 2.0 features.

Enabling WSRP 2.0 Support for Consumers

By default, WebLogic Portal consumers only support WSRP 1.0 features that are implemented by producers. If the producer offers any WSRP 2.0 features, WebLogic Portal consumers ignore them by default. To change this default, so that WebLogic Portal consumers can process WSRP 2.0 messages from producers, you can pass the following system property to the WebLogic Server Java startup command for the server on which the consumer is running:

If You Enable WSRP 2.0 Features for Consumers

This section describes the WSRP 2.0 features that are and are not supported by WebLogic Portal consumers if you choose to enable WSRP 2.0 support, as described in the previous section “Enabling WSRP 2.0 Support for Consumers.”

Only basic WSRP 2.0 features are supported.
Optional WSRP 2.0 features, such as events, shared render parameters, copy portlets, and resource serving are not currently supported.
As noted previously, if you enable WSRP 2.0 for consumers, features such as inter-portlet communication and SOAP with attachments are not available.
Leasing is not supported.
Import and export of portlets is supported whether or not WSRP 2.0 is enabled for consumers. Import and export support the propagation of federated (WSRP) portals. For details on WSRP propagation, see the section “WSRP Propagation” in the Production Operations Guide.

Decouple Rendering from Interaction

As explained in Life Cycle of a Remote Portlet, the rendering and interaction phases of a remote portlet’s life cycle are decoupled. As a result, you cannot expect a portlet to receive the same HTTP response or request for the render phase as it receives for an interaction.

A portlet that is being rendered must not expect to receive form data in the request object. This is because the request may have been submitted some time ago and is being rendered now, and you may not have the same data.

If you want to maintain data between requests, you need to store that data locally, typically in the session. For instance, if you are processing and order ID, you can store that ID locally.

If you are using page flows, data is automatically passed forward. However, if you are using backing files with a remote portlet, you need to make sure that data is stored in the session, because you won’t get back the same request object.

Portlets will not get the same servlet request for the interaction and render phases, even after the first rendering after an interaction.
Decouple rendering from interaction processing. A portlet should be able to render itself as many times as necessary without depending on the user’s interaction directly. Store interaction changes for future rendering. Note that WebLogic Portal stores state automatically for page flows.
Use JSP tags with render parameters.
Use HTTP session for backing files.

Avoid Interportlet Dependencies

Rather than create explicit dependencies between portlets, use events to communicate between portlets. For example, suppose that on a portal page, there is a portlet for collecting orders and a portlet for displaying the status of all orders. When an order is taken, data is stored in the database, and the data is then displayed in the order status portlet, as shown in Figure 14-1.

In this scenario, a strong dependency is created between the collect order and the order status portlets. The Collect Order portlet needs to somehow communicate some information (the order ID) to the Order Status portlet. Storing the ID in the session or other common state between the portlets creates a strong dependency between the Collect Order and Order Status portlets. Depending on the implementation of the portlets, if one of them is changed or replaced, the changes will necessarily affect the other portlet.

To avoid this dependency, use events to communicate between portlets. In this example, if an event is used to communicate order information to the order status portlet, the order status portlet does not have to care about where the order came from. The order status portlet just handles an event, retrieving, for example, an order ID from the event’s payload.

Avoid Portal Layout Dependencies

Some portals are built with inherent portal layout dependencies. For example, a login portlet might be designed to function differently if it is on a human resources page versus a finance page. In other words, when an interaction takes place, the portlet tries to find out what page it is on before taking action. This practice closely couples the portlet to the Portal Framework elements, such as pages, books, or desktops on the consumer.

This scenario does not work in a federated portal, because the producer does not know what page layouts exist on the consumer. Avoid this scenario when possible. If it is required, deploy those portlets locally on the consumer, or use shared components where possible and create alternative layouts that are offered through separate portlets.

Avoid Coupling by URL

If you embed URLs in your portlets, such as in links, you may find that your portlets work as expected when they are running locally. However, when you move those portals to a federated environment, the links no longer work. For example, in the following code fragment, a developer is invoking the action of a page flow portlet on the same portal using string manipulation. In a federated portal, this sort of construction will not work. Typically, this sort of programming arises because of reverse engineering, where a developer looks at and copies how links are created.

Likewise, the following resource URL will not work in a federated portal because it includes an explicitly specified link to a document. Because the document doesn’t exist on the consumer, the consumer doesn’t know what to do with it:

Common URL problems found in federated portals include the following. These problems stem from the fact that remote portlets do not follow the same URL structure as portlets in a local environment.

It is important that you let the WebLogic Portal Framework create URLs for you using the proper set of JSP tag libraries and utility classes. Use the following tags and classes:

All of these tags go through the WebLogic Portal URL rewriters and will work properly in a federated environment.

It is important to realize that there are inherent differences between remote portlets and local portlets. Developers must not expect that all correctly functioning local portlets will function properly as remote portlets, although in many cases they do.

Avoid Accessing Request Parameters in Rendering Code

When you deploy a local portlet, the portlet can access the request parameters from the portal’s request and the request attributes set by other portlets on the same page. If you implement a portlet to depend on such request parameters and attributes, the portlet will not function correctly in a WSRP environment. In a WSRP environment, remote portlets are running on remote systems; the HTTP request received by a remote portlet on a producer is not the same as the one that is received by the consumer portal.

Avoid Moving Producers

When you add producers and create remote portlets, the producer registry (WEB-INF/wsrp-producer-registry.xml) and the portal framework database tables contain specific information about the producer, such as its WSDL address and the addresses of ports described in the WSDL. If you move the producer from one environment to another, this data becomes invalid. In this case, consumers whose proxy portlets reference the producer’s portlets will no longer be able to find them.

If you must move a producer from one environment to another (such as a staging to a production environment) WebLogic Portal supports two mechanisms for achieving this.

The first mechanism, shared registration, is only recommended for WebLogic Portal producers older than version 10.0. With shared registration, the staging and production environments share the same producer registration handle. This model has a number of serious drawbacks. Only use this model when the producer is a version of WebLogic Portal prior to 10.0. For more information on shared registration and propagating WSRP producers in this case, see the Production Operations Guide.

The second mechanism is recommended for producers, such as WebLogic Portal versions 10.0 and higher, that support WSRP 2.0 exportPortlet and importPortlet operations. When producers are propagated using these operations, producer registration handles do not need to be shared. The propagation tool in WebLogic Portal versions 10.0 and higher handles these operations automatically. See the Production Operations Guide for details.

You can also update the database entries for a producer programmatically. The following class provides methods to get and update producer information:

WebLogic Server Producers

In some cases, you may want to expose portlets with WSRP from a producer environment that does not include any WebLogic Portal components. For example, you may be running a Struts Web application in a Basic WebLogic Server Domain, or a Java Page Flow application in a Basic WebLogic Workshop Domain. In either case, WebLogic Portal is not part of the server configuration. For detailed information on using a non-portal server domain to host remote portlets, see Configuring a WebLogic Server Producer.

If you are using a Portal Web application as your producer, all the portal artifacts are available in the web application; however, for any WSRP producer that is not a Portal Web application, you cannot use portal features such as property sets. If you need to access portal features in your producer, use a Portal Web application.

Security for Remote Portlets

To secure messages, implement SSL on any port through which the producer will be offered. For detailed information on configuring single sign-on security for federated portals, see:

Error Handling

This section gives an overview of error handling techniques for federated portals.

On the Producer

To prevent stack traces from appearing, handle errors on the producer side and provide a suitable business message.

On the Consumer

Click the portlet in the editor to display the Properties view.
Enter a path for the error page (JSP or HTML page).

Interceptors

You can use interceptors to handle errors returned from a producer. For instance, if a specific producer is not registered, you can trap the registration error and handle it as you wish. For detailed information on using interceptors, see The Interceptor Framework.

Portlet Programming Guidelines and Best Practices

This section discusses guidelines and best practices for developing remote portlets.

Requests and Sessions

If two or more remote portlets share session data, host them on the same producer. You cannot assume that session information will be shared by portlets hosted on different systems.

Look and Feel

Let portlets use standard style attributes and specify those attributes on the portal skins. For information on look and feel, see the Portal Development Guide.

Backing Files

You can use backing files on the consumer side (remote-portlet) to take some action based on session / request objects or property sets. For information on backing files, see the Portlet Development Guide.

Caching WSRP Portlets

Producer – Use <wl:cache> or p13nCache wherever possible.
Consumer (remote-portlet) – Use the RenderCacheable attribute if you want to cache the remote portlet’s rendered HTML. However, this is a session scoped cache and is not configurable.

For more information on caching, see the “Portlet Caching” section of the Portlet Development Guide.

Designing for Performance

To ensure optimal performance of your producers and consumers, we recommend the following performance tuning guidelines on the producer and the consumer.

Performance Guidelines for Producers

This section lists several ways to improve the performance of producer applications.

Reorder Authentication Providers

One way to improve performance on the producer is to make sure the SAML Authentication Provider is deployed in front of other authentication providers. To reorder the providers:

Log in to the WebLogic Server Administration Console.
Select Security Realms in the Domain Structure tree.
In the Realms table, select the active security realm used by the producer application.
In the Settings page, select the Providers tab.
In the Change center, click Lock & Edit.
Below the Authentication Providers table, click Reorder.
In the list of providers, use the arrow buttons to move SAMLAuthenticator to the top of the list, and click OK.
In the Change center, click Activate Changes.

Enable Attachment Support

Enable attachment support by adding <markup transport="attachment"/> to WEB-INF/wsrp-producer-config.xml, as shown in Listing 14-1.

    <service-config>
        <registration required="false" secure="true"/>
        <service-description secure="true"/>
        <markup secure="true" rewrite-urls="true" transport="attachment"/>
        <portlet-management required="false" secure="true"/>
    </service-config>

Other Techniques

Performance Guidelines for Consumers

Accept the default behavior to enable caching for remote portlets.
Enable forked rendering for remote portlets.
Set connection timeout. See Setting a Timeout Value on a Remote Portlet for detailed information on setting timeouts.
Disable logging by undeploying MessageMonitor servlet from WEB-INF/web.xml.

Using Local Proxy Mode

Local proxy support allows co-located producer and consumer web applications to short-circuit network I/O and “SOAP over HTTP” overhead. When you enable this feature, the consumer tries to determine if the producer is deployed on the same server and, if it discovers that the producer is so deployed, it uses a local proxy to send requests to the producer. If the producer is not deployed on the same server, the consumer uses the default remote proxy. Remote producers can still be invoked as usual even when the local proxy support is enabled.

This section describes how to implement local proxy support. It includes information on the following subjects:

Why Use Local Proxy Mode?

Local proxy mode provides a number of advantages over the default remote proxy when you are working with co-located consumers and producers. Among the most significant advantages of local proxy mode are:

Additionally, by enabling local proxies, customers can take advantage of the decoupling benefits of WSRP without incurring its performance overhead.

Deployment Configuration

Deploy the producer and consumer web applications on the same server. These applications could be in the same enterprise application or across different enterprise applications.
Enable local proxy support by setting <enable-local-proxy> to true in WEB-INF/wsrp-producer-registry.xml in the consumer web application, as shown in Listing 14-2:

Listing 14-2 Setting <enable-local-proxy> to ”true”

<wsrp-producer-registry
   xmlns="http://www.bea.com/servers/weblogic/wsrp-producer-registry/8.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://www.bea.com/servers/weblogic/wsrp-producer-
      registry/8.0 wsrp-producer-registry.xsd">

   <!-- Upload limit (in bytes) -->
   <upload-read-limit>1048576</upload-read-limit>

   <!-- Timeout (in milli seconds) -->
   <connection-timeout-secs>120000</connection-timeout-secs>

   <!-- Enable local proxy -->
   <enable-local-proxy>true</enable-local-proxy>

...
</wsrp-producer-registry>

You can also enable local proxy support by setting a system property com.bea.wsrp.proxy.LocalProxy.enabled = true. If this system property is set to true, it will override the <enable-local-proxy> setting in WEB-INF/wsrp-producer-registry.xml.

How Local Proxy Mode Works

Figure 14-2 compares the layers of operations involved when local proxy support is enabled (top flow diagram) and when it is not (bottom flow diagram). In the local proxy case, there is no network or SOAP related overhead and the servlet API is used for communication.

Table 14-1 summarizes the evolution of the WebLogic Portal local proxy architecture.

Table 14-1 Evolution of Local Proxy Architecture for WebLogic Portal
Version	Local Proxy Architecture
WLP 8.1x	Exchange XmlBeans between consumer and producer.
WLP 9.2	Convert POJOs into XmlBeans while sending data from the consumer to the producer.
WLP 10.0	Exchange POJOs between the consumer and the producer.

When to Use and Not Use

As powerful a tool as local proxy support is, you should only use it when it will benefit your application. The most common reasons for using local proxy support are:

When portlets are deployed in self-contained web applications on the same server. The local proxy support provides isolated portlet deployment. In this mode, each portlet web application can be deployed as a WSRP producer. Portlets can therefore be loaded by separate class loaders and have their own servlet context and session. Portlet web applications can be deployed/undeployed without affecting the portal web application.
When you don’t need advanced monitoring software between the producer and consumer.

On the other hand, you should not use local proxy support when interoperating with non-BEA producers and consumers.

Monitoring and Logging

You can monitor activity between producers and consumers by using the message monitor servlet installed with WorkSpace Studio. You can also create custom logs to display specific information about WSRP sessions. These features can help you debug problems with remote portlets.

Using the Monitor Servlet

To monitor the response and request headers, as well as the action SOAP messages that are passed between producers and consumers:

Ensure that the producer and consumer applications whose communication you want to monitor are running.
Open a new browser and enter the following URL:

host:port/webProject_name/monitor

host:port is the host and port you want to monitor. This can be the host and port of either the producer or consumer server.
webProject_name is the web project you want to monitor.

The monitor appears in the browser. Click Enable to start monitoring. Click Refresh to see the latest transactions. Click Clear to remove all messages from the browser window.

Each time the remote portlet communicates with the producer, a request and response message headers appear on the monitor screen, as shown in Figure 14-4.

By clicking Show, you can display the content of the request or the response, as shown in Figure 14-5. Click Hide to close the message content.

Creating Custom Logs

To create custom logs, we recommend that you use the Interceptor Framework described in The Interceptor Framework.

You can also create custom logs that display particular information about a WSRP session by using Logger and Handler objects instantiated by WebLogic Server. You can use these objects to create your own message handlers and subscribe them to loggers. For example, if you want the remote portlet to listen for the messages that the producer generates, you can create a handler and subscribe it to a logger in the producer. For detailed information on using Logger and Handler objects, see the WebLogic Server topic, “ Filtering WebLogic Server Log Messages.”

Configuring Session Cookies

This section describes two techniques for preventing the loss of the consumer session when resource requests are made to a remote portlet. These techniques include:

Using Different Cookie Names

If you have a remote portlet that contains images, WebLogic Portal sends cookies and other headers from the producer to the browser when an image resource is requested. Note that when resource requests are made to a portlet in a producer, it is possible for the user’s browser to drop or lose the consumer session. This situation occurs when the producer and consumer are configured to include only the default path (“/”) in the session cookies, which causes the browser to replace the Set-Cookie header set by the consumer with the Set-Cookie header set by the producer.

To prevent this potential loss of the consumer session, open weblogic.xml, and configure your web applications to include the domain name and web application path for session cookies. This technique prevents the cookie names from overlapping. Please refer to session-descriptor in the WebLogic Server document “weblogic.xml Deployment Descriptor Elements” for details on how to set the domain name and path.

Using a System Property

In most cases, using different cookie names solves the problem of lost consumer sessions following resource requests. In some cases, however, this solution does not work. One such use case is when single sign-on is used with the producer and consumer running in the same domain. In this case, identical cookie names are required. For cases where using different cookie names does not work, set the following system property:

By enabling this system property, WebLogic Portal prevents a Set-Cookie header from being sent back to the user’s browser. This property prevents the consumer’s cookie from being overwritten by the producer’s cookie on the browser when a resource is returned. Using this technique, you can keep the cookie names the same for both the producer and consumer applications, which is required for single sign-on.

Blocking Cookies

To block cookies to the browser, set <resource-cookies> to block-all in WEB-INF/wsrp-producer-registry.xml in the consumer web application, as shown in Listing 14-3. When this element is set to block-all, the resource proxy servlet does not transfer any cookies from the producer resource to the browser. Cookies are not blocked by default. The default setting is block-none.

User Sessions on CWEB Applications

User sessions on CWEB applications might be lost if session cookies between producers and consumers overlap. To prevent this, open weblogic.xml, configure your web applications to include the domain name and web application path for session cookies. Please refer to session-descriptor in the WebLogic Server document “weblogic.xml Deployment Descriptor Elements for details on how to set the domain name and path.

Using Multiple Views with Remote Portlets

Whenever multiple views of a remote portlet are created, links in the portlets can be inconsistent and not work properly. Typically, multiple views occur when a remote portlet uses the popup mechanism in a page flow, or when a user floats a remote portlet using the portlet Float button.

If a WebLogic Portal producer is set up to use consumer-supplied URL templates, the producer caches those templates in a session created on the producer. However, when multiple views of a portlet are created either through the page flow popup mechanism, or through a Float button, the cached templates may not be valid for the current view.

Disabling the caching of templates for your remote portlets. To do this, in the .portlet file for each remote portlet that is affected, change the value of the templatesStoredInSession element to false.
Configure the producer to require consumer rewriting. To do this, set the rewrite-urls element to FALSE in the wsrp-producer-config.xml file.

Handling User Identity Changes

If the user’s identity changes while a request generated from the portal is in progress, remote portlets can behave inconsistently. Typically, this occurs when the portal desktop includes a portlet or other mechanism for logging in and logging out a user. If the user identity changes, any user-specific data loaded by the portal can become invalid. In the case of remote portlets, such data includes their persistent state. When user identity changes, the consumer portal can send incorrect persistent state data to producers.

To avoid this problem, be sure to always use a browser redirect call immediately after a login or logout. The browser redirect ensures that data loaded by the portal is valid for the request.

Storing Registration Properties

This section discusses the Store Registration Properties feature and why enabling it is generally recommended.

When you register a producer either using WorkSpace Studio or the WebLogic Portal Administration Console, you have the option of storing registration property sets on the consumer. Registration properties are values that are passed from the consumer to the producer when the producer is registered. These values can be used to allow producers to control which portlets are offered to specific consumers.

This section explains why storing registration properties is the recommended procedure for storing registration properties using both WorkSpace Studio and the Administration Console. This section includes these topics:

Why Store Registration Properties?

It is recommended that you choose to store registration properties when you register a producer. This option provides these advantages:

If the producer is unable to provide registration properties, they are still available to your portal application. The producer may be unable to provide registration properties if:

The producer is not a WebLogic Portal 10.2 or later version. The WSRP extension for providing registration properties from the producer does not work with WebLogic Portal 10.0 or older versions or with third-party producers.
The producer is configured not to offer support for the WSRP registration property extension. Typically, the a producer is configured in this way to prevent sending registration property values back from the producer as a security measure. In this case, you might consider it to be acceptable to store the registration property values on the consumer and retain the benefits of registration property storage.
The producer is temporarily unavailable.

If you choose to modify the registration properties for a producer, the Modify Registration Properties dialog box will always be filled in with the currently used registration properties. The procedure for modifying registration properties is described in Modifying Producer Registration Properties.

Using the Administration Console

The Store Registration Properties check box is provided in the Enter Producer Properties dialog of the Add Producer Wizard, as shown in Figure 14-6. (The complete procedure for registering producers is discussed in detail in Adding Remote Resources to the Library.)

You can change the value of the Store Registration Properties check box in the WebLogic Portal Administration Console. Go to the Summary tab of the producer and click Producer Properties to bring up the Update Producer Url dialog. This dialog lets you change the setting.

Using WorkSpace Studio

The Store registration properties in local registry check box is provided in the Register dialog of the Remote Portlet Wizard, as shown in Figure 14-7.

When Store registration properties in local registry is checked, the wsrp-producer-registry.xml file is updated with the stored registration information. A sample is shown in Listing 14-4. To provide flexibility, this option is always selected by default even if there are no properties defined. If the checkbox is selected during registration you can add registration properties later.

You can only edit the registration properties using the IDE dialog when initially registering or re-registering a producer. To change the properties after the producer is registered, you need to edit the XML file directly using an XML editor.

...
<registration-properties>
      <stringProperty name="{urn:bea:wlp:prop:reg:propset-1}Selection">
        <value>OK</value>
      </stringProperty>
      <stringProperty name="{urn:bea:wlp:prop:reg:propset-1}Choices">
        <value>Electronics</value>
      </stringProperty>
    </registration-properties>
    <store-registration-properties>true</store-registration-properties>
...

Editing the WSRP WSDL Template File

You can customize the producer-generated WSDL. For example, you might want the WSDL to point to a proxy server other than the default one. To customize the default WSDL, you can edit the WEB-INF/beehive-url-template-config.xml file. The easiest way to edit this file is to copy it to your workspace in WorkSpace Studio. To do this, locate the file in the Merged Projects view in WorkSpace Studio. Right-click the file and select Copy to Workspace. The template file uses URL templates. See Javadoc for the GenericURL class for information on configuring URL templates.

Configuring a Custom JAX-RPC Handler

This section explains how to configure custom JAX-RPC handlers on the WSRP consumer or producer. Custom handlers can be used to intercept and process the outbound SOAP requests and inbound SOAP responses. For example, handlers can inspect the incoming and outgoing messages, change the messages before they make it to the end point, log information, and so on. This section only explains how to configure and register a handler, not how to write a handler class.

Configuring a Handler on the Consumer

Edit the file WEB-INF/wsrp-consumer-handler-config.xml to add a custom handler the consumer. The easiest way to edit this file is to copy it to your workspace in WorkSpace Studio. To do this, locate the file in the Merged Projects view in WorkSpace Studio. Right-click the file and select Copy to Workspace.

<wsrp-consumer-handler-config 
xmlns="http://www.bea.com/ns/portal/90/wsrp-consumer-handler-config">
    <description>Description goes here</description>

    <soap-handler>
        <name>ProducerHandlesFilter</name>
        <description>Producer Handles Filter test handler</description>

        <!-- List of producer handles to deploy to, if none are specified ALL 
             producers will have this handler -->
        <producer-handle>NoOpProducer1</producer-handle>
        
<handler-class>com.bea.wsrp.qa.consumer.handlers.ProducerHandlesFilter
</handler-class>

        <!-- If true, the handler will run before the SAML token is added. -->
        <pre-security>true</pre-security>

        <!-- init parameters if needed -->
         <init-parameter>
            <name>param1</name>
            <value>value1</value>
        </init-parameter>
        <init-parameter>
            <name>param2</name>
            <value>value2</value>
        </init-parameter>


        <!-- Specify which ports to add the handler to. -->
        <port-name 
xmlns:wsrp="urn:oasis:names:tc:wsrp:v1:wsdl">wsrp:WSRPServiceDescriptionService
</port-name>
        <port-name 
xmlns:wsrp="urn:oasis:names:tc:wsrp:v1:wsdl">wsrp:WSRPBaseService</port-name>
        <port-name 
xmlns:wsrp="urn:oasis:names:tc:wsrp:v1:wsdl">wsrp:WSRPRegistrationService
</port-name>
        <port-name 
xmlns:wsrp="urn:oasis:names:tc:wsrp:v1:wsdl">wsrp:WSRPPortletManagementService
</port-name>
        <port-name 
xmlns:wsrp="urn:oasis:names:tc:wsrp:v1:wsdl">wsrp:WLP_WSRP_Ext_Service
</port-name>

        <soap-role>someRoleHere</soap-role>
    </soap-handler>

Configuring a Handler on the Producer

On the producer edit the file WEB-INF/webservices.xml as defined by the JAX-RPC specification.

Federated Portals Guide