| Oracle® Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal 10g Release 3 (10.3.6) Part Number E14235-07 |
|
|
View PDF |
| Oracle® Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal 10g Release 3 (10.3.6) Part Number E14235-07 |
|
|
View PDF |
WebLogic Portal supports a relatively simple technique for passing custom data between consumers and producers. A set of interfaces is provided that let you attach arbitrary data to request and response objects. This chapter explains how to use these interfaces to achieve custom data transfer and includes detailed examples.
This chapter includes the following topics:
Custom data transfer allows portlet developers to exchange arbitrary data between producers and consumers. The primary use cases for custom data transfer are:
To send and receive data that WebLogic Portal does not usually send or receive.
To send and receive data that the WSRP protocol does not allow.
Note:
It is recommend that you use this technique only after trying other techniques for data transfer. The preferred technique for transferring data between producers and consumers is to use custom events. For more information, see Section 7.4, "Data Transfer with Custom Events".
Some example use cases for custom data transfer include:
You are a portal developer building a portal with a set of location-sensitive portlets deployed on one or more producers. You would like to supply a zip code to each of these portlets in a request so that each portlet can use this zip code to generate location-aware markup.
You want to send arbitrary data such as theme or style information or user profile data to portlets.
Custom data transfer allows you to easily resolve these situations and many others like them. The technique for using custom data transfer is straightforward, and involves these primary tasks:
Create one or more "holder" classes that implement the interfaces listed in the following section, "Section 12.2, "Custom Data Transfer Interfaces"." A serializable default implementation of the interfaces, called SimpleStateHolder is provided with WebLogic Portal.
Place a serializable holder object in a request or response object, as appropriate. For example, in a consumer application, you can set a holder object as a request parameter and retrieve it in the producer application. See Section 12.3.1, "Custom Data Transfer with a Complex Producer" for a detailed example of this technique.
Both simple producers and complex producers can take advantage of this feature.
The following interfaces enable the transfer of data between producers and consumers. To perform custom data transfer, implementations of these interfaces must be deployed on both the consumer and producer.
Section 12.3, "Performing Custom Data Transfer" includes a detailed example demonstrating how to use these interfaces. For more information on these interfaces, refer to their Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portaldescriptions.
Note:
These interfaces are not supported for events and render dependencies requests.
com.bea.wsrp.ext.holders.InteractionRequestState
Allows the consumer to send some arbitrary data to the producer when an interaction (such as a form submission) occurs.
com.bea.wsrp.ext.holders.InteractionResponseState
Allows the producer to return some arbitrary data to the consumer after an interaction occurs.
com.bea.wsrp.ext.holders.MarkupRequestState
Allows the consumer to send some arbitrary data to the producer when a portlet is being refreshed.
com.bea.wsrp.ext.holders.MarkupResponseState
Allows the producer to return some arbitrary data to the producer after portlet is rendered.
com.bea.wsrp.ext.holders.XmlPayload
Transfers XML data between consumers and producers. You can place an instance of this class directly in request and response objects. For more information, see Section 12.4, "Transferring XML Data".
Tip:
If you do not want to create your own implementations of these interfaces, the serializable com.bea.wsrp.ext.holders.SimpleStateHolder class provides a default implementation. The examples in this chapter use SimpleStateHolder to pass custom data.
This section presents examples that illustrate how to use custom data transfer between consumers and producers. Both examples use the serializable com.bea.wsrp.ext.holders.SimpleStateHolder class, which implements the five interfaces listed previously in Section 12.2, "Custom Data Transfer Interfaces". This class provides a default implementation of the above interfaces that lets you exchange simple name-value pairs of data.
The examples include:
Section 12.3.1, "Custom Data Transfer with a Complex Producer"
This example demonstrates custom data transfer between a consumer and a complex producer.
Section 12.3.2, "Custom Data Transfer in a Simple Producer"
This example demonstrates custom data transfer between a consumer and a simple producer.
This example explains how to transfer data from a consumer to a complex producer. For information on complex producers, see Section 3.4.2, "WebLogic Portal Producers".
In this example, a backing file in the consumer application packages arbitrary data in a com.bea.wsrp.ext.holders.SimpleStateHolder object. This object is attached to a request using the setAttribute() method. The producer retrieves the data from the request and places it in a JSP page. The modified page is then displayed by the consumer application.
The example consists of these steps:
If you want to try the example discussed in this chapter, you need to run Oracle Enterprise Pack for Eclipse and perform the prerequisite tasks listed in Table 12-1. For detailed information on performing these basic setup tasks, see "Setting Up Your Portal Development Environment" in Oracle Fusion Middleware Tutorials for Oracle WebLogic Portal.
Table 12-1 Prerequisite Tasks
| Task | Recommended Name |
|---|---|
|
Create a Portal domain. |
wsrpPortalDomain |
|
Create a Portal EAR Project. |
wsrpPortalEAR |
|
Create an Oracle WebLogic Server v10.x. |
N/A |
|
Associate the EAR project with the server. |
N/A |
|
Create a Portal Web Project and add it to the EAR. |
consumerProject |
|
Create a second Portal Web Project and add it to the EAR. |
producerProject |
Figure 12-1 shows the Package Explorer after the prerequisite tasks have been completed.
Figure 12-1 Package Explorer After Prerequisite Tasks are Completed
We also assume that you know how to view and edit portlet properties in the Properties view. For information, see the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
With the example environment in place, create a JSP file on the producer and a portlet to surface that file. Code placed in the JSP file retrieves a SimpleStateHolder object from the request, retrieves its data payload, and displays the data.
Be sure you have set up the example environment as explained previously in Section 12.3.1.2, "Setting Up the Example".
Right-click producerProject/WebContent in the Package Explorer and select New > JSP. The New JavaServer Page dialog appears.
In the dialog, enter zipTest.jsp in the File name field, and click Finish.
Replace the entire contents of the JSP source file with the code in Example 12-1.
Example 12-1 Code to Get State from the Request
<%@ page import ="com.bea.wsrp.ext.holders.SimpleStateHolder,
com.bea.wsrp.ext.holders.MarkupRequestState"%>
<%
SimpleStateHolder state = (SimpleStateHolder)
request.getAttribute(MarkupRequestState.KEY);
String zip = (String) state.getParameter("zipCode");
%>
<%=zip%>
Figure 12-2 shows the editor with the new source code.
Figure 12-2 New JSP Source for zipTest.jsp
Save the file.
Tip:
Later in this example, you will add a backing file to the proxy portlet in the consumer web application. This backing file creates the SimpleStateHolder object, adds some data to it, and puts the object into the request that is sent from the consumer to the producer. For more information on SimpleStateHolder, refer to its description in Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.
In the Package Explorer view, open the producerProject/WebContent folder. Right-click zipTest.jsp in the WebContent folder and select Generate Portlet.
The Portlet Details dialog box appears. Note that zipTest.jsp already appears in the Content Path field, as shown in Figure 12-3.
Figure 12-3 Portlet Details with zipTest.jsp Included
In the State checkbox, select Minimizable and Maximizable, then click Next and then click Create.
The portlet zipTest.portlet appears in the Package Explorer, as shown in Figure 12-4.
Next, create a remote portlet in the consumer application to surface in zipTest.portlet from the producer:
Be sure that WebLogic Server is running. If not, select the Servers tab. Make sure the Oracle WebLogic Server v10.x is selected, and click the Start button, as shown in Figure 12-5.
Figure 12-5 Click the Start Button to Start the Server
In the Package Explorer, open the consumerProject folder.
Right-click the WebContent folder, and select New > Portlet.
Tip:
The Portlet selection only appears on the New menu if you are using the Portal perspective. Switch to the Portal perspective if Portlet does not appear on the menu.
The New Portlet dialog box appears, as shown in Figure 12-6.
In the New Portlet dialog, select WebContent as the parent folder, enter zipPrime.portlet in the File name field, and click Next.
The Select Portlet Type dialog box appears as shown in Figure 12-7.
Select Remote Portlet and click Next. The Portlet Wizard – Producer dialog box appears.
In the Portlet Wizard – Producer dialog, select Find Producer and, in the field provided, enter the following WSDL URL, as shown in Figure 12-8:
http://localhost:7001/producerProject/producer?wsdl
Tip:
Of course, the host name localhost is only appropriate if the producer is running on the same server as the consumer. We co-located the consumer and producer to simplify the presentation of this example. Typically, producers and consumers do not run in the same server.
After entering the WSDL URL, click Retrieve.
Tip:
WSDL stands for Web Services Description Language and is used to describe the services offered by a producer. For more information, see Section 3.4.3, "WebLogic Portal Consumers".
After a few moments, the Portlet Wizard – Producer dialog box refreshes, and registration information appears in the Producer Details panel, as shown in Figure 12-9.
Tip:
Registration is an optional feature described in the WSRP specification. A WebLogic Portal complex producer implements this option and, therefore, requires consumers to register before discovering and interacting with portlets offered by the producer. See Section 3.4.2.2, "Complex Producers" for more information.
Click Register. The Register dialog appears.
In the Register dialog, enter myProducer in the Producer Handle field, as shown in Figure 12-10, and click Register. The handle is stored on the consumer and is used to identify the producer.
In the Portlet Wizard – Producer dialog, click Next. The Select Portlet from List dialog box appears.
From the portlet list, select zipTest, as shown in Figure 12-11.
Figure 12-11 Select Portlet from List Dialog Box
Click Next. The Proxy Portlet Details dialog box appears, as shown in Figure 12-12.
Figure 12-12 Proxy Portlet Details Dialog Box
Click Create.
The new portlet appears in the Editor, as shown in Figure 12-13.
Figure 12-13 New Remote Portlet zipPrime.portlet in the Editor
In this step, you will create a backing file called CustomDataBacking.java in the consumer application. Then, you will attach the backing file to the remote portlet you created previously, zipPrime.portlet.
Tip:
A backing file is a Java class that adds functionality to a portlet. For information on backing files, see the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
In the Package Explorer tree, open the consumerProject folder, expand the Java Resources node, and right-click the src folder, and create a new Source Folder called backing.
The src/backing folder appears in the Package Explorer, as shown in Figure 12-14.
Tip:
Alternatively, instead of a folder, you can create a Java package.
Right-click the backing folder and select New > Class. The New Java Class dialog appears, as shown in Figure 12-15.
In the Name field, enter CustomDataBacking and click Finish. The new Java source file appears in the editor.
Replace the entire contents of the Java source file with the code in Example 12-2.
Example 12-2 Adding an Instance of SimpleStateHolder
package backing;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
import com.bea.wsrp.ext.holders.MarkupRequestState;
import com.bea.wsrp.ext.holders.SimpleStateHolder;
public class CustomDataBacking extends AbstractJspBacking
{
private static final long serialVersionUID = 1L;
public boolean preRender(HttpServletRequest request,
HttpServletResponse response)
{
SimpleStateHolder state = new SimpleStateHolder();
state.addParameter("zipCode", "80501");
request.setAttribute(MarkupRequestState.KEY, state);
return true;
}
}
Save the file. The completed backing file is shown in Figure 12-16.
Figure 12-16 CustomDataBacking.java in the Editor
Tip:
The backing file implements the AbstractJspBacking.preRender() method. This method is called before the request is sent to the producer. The implementation attaches a SimpleStateHolder object containing custom data to the request. This object will be retrieved on the producer where the data is extracted and displayed in the remote portlet.
Double-click zipPrime.portlet to display it in the editor.
Add the backing file to zipPrime.portlet. To do this, enter the full classname of the backing file in the Backing File field in the Properties view:
backing.CustomDataBacking
Figure 12-17 shows the class name after it has been added.
With the consumer application components in place, you can now test the configuration. If the test is successful, the zip code 80501, provided by the backing file, will appear in the remote portlet when it is rendered.
To test the application:
In the Package Explorer, right-click consumerProject/WebContent and select New > Portal. The New Portal dialog appears.
In the File name field, enter zipTest.portal and click Finish.
The portal is created and appears in the editor, as shown in Figure 12-18.
Figure 12-18 zipTest.portal in the Editor
Drag the remote portlet zipPrime.portlet from Package Explorer view into the portal. (You can place it in either the left or right column; in Figure 12-19, it is in the right-hand column).
Figure 12-19 zipTest.portlet Added to zipTest.portal
Save the portal.
Run the portal. To do this, right-click zipTest.portal in the Package Explorer and select Run As > Run on Server.
In the Run On Server – Define a New Server dialog, click Finish.
The portal appears in the Oracle Enterprise Pack for Eclipse browser. The custom data sent from the consumer displays in the portlet, as shown in Figure 12-20.
Figure 12-20 zipTest.portal Successfully Rendered
The previous section, Section 12.3.1, "Custom Data Transfer with a Complex Producer", explains how to transfer data between a WebLogic Portal consumer application and a complex producer running in a WebLogic Portal domain. You can also transfer data between a WebLogic Portal consumer and a simple producer running in a WebLogic Server domain.
Tip:
For a detailed discussion of complex and simple producers, see Section 3.4.2, "WebLogic Portal Producers".
To use custom data transfer with a simple producer:
Properly configure a simple producer running in a WebLogic Server domain. The procedure for doing this is explained in Chapter 8, "Configuring a WebLogic Server Producer."
Use the Custom Data Transfer interfaces listed in Section 12.2, "Custom Data Transfer Interfaces" to set and retrieve data in request and response objects. Follow the same basic procedure described for complex producers in Section 12.3.1, "Custom Data Transfer with a Complex Producer".
Use an implementation of the com.bea.wsrp.ext.holders.XmlPayload interface to transfer XML data (objects of type Element) between consumers and producers. You can place an instance of this class directly in request and response objects. For more information on the XmlPayload interface, refer to its description in Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.
Example 12-3 shows sample code that uses XmlPayload.
This section discusses guidelines for implementing the custom data transfer interfaces listed in Section 12.2, "Custom Data Transfer Interfaces".
The implementation must be serializable.
The same class version of the implementation must be deployed on both the producer and consumer. If the versions are different, the implementations must make sure to have the same serialVersionUID for all versions.
Sending large amounts of data may have performance implications.
Tip:
The com.bea.wsrp.ext.holders.SimpleStateHolder class provides a default implementation of the four data transfer interfaces. This class lets you exchange simple name-value pairs of data. For detailed information on the methods of this class, refer to its description in Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.
Whether a consumer or producer can send custom data depends on the type of request. These rules apply:
Consumers can always send InteractionRequestState. There are no exceptions.
Producers can always return InteractionResponseState. There are no exceptions.
Consumers can send MarkupRequestState only when there is a need to refresh the portlet. For example, if caching is enabled on the remote portlet, consumer may not always send a request to the producer to generate markup.
Consumers cannot return MarkupResponseState if any the following options are enabled:
Returning markup as an attachment
Local proxy
In both the cases, the producer invokes the portlet (typically JSPs) after creating the SOAP response, which is too late to update the SOAP response.
|
 Copyright © 2010, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
