4 Creating Remote Portlets, Pages, and Books

This chapter focuses on how to use Oracle Enterprise Pack for Eclipse to create and configure remote portlets, pages, and books. This chapter includes the following sections:

• Section 4.1, "Introduction"

• Section 4.2, "What Types of Portlets Can Be Remote?"

• Section 4.3, "Creating a Remote Portlet"

• Section 4.4, "Creating Remote Pages and Books"

4.1 Introduction

Before getting started, we recommend that you review the following chapters in the architecture part of this guide:

• Chapter 2, "What are Federated Portals?"

• Chapter 3, "Federated Portal Architecture"

.These chapters explain basic concepts such as producers, consumers, and remote portlets, pages, and books. This chapter assumes you familiar with these concepts.

4.2 What Types of Portlets Can Be Remote?

WebLogic Portal applications can consume the following types of portlets:

• JSP (JavaServer Pages) portlets

• JSF (JavaServer Faces) portlets

• Java portlets (supported only for complex producers)

• Page flow portlets

• Struts portlets

Note:

Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. Apache Struts is also 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.

To be consumable, a portlet must be deployed to a web application that is running in a WSRP-compliant producer. The consumer application must also be capable of contacting the producer using the producer's WSDL URL.

4.3 Creating a Remote Portlet

This section presents a step-by-step example showing you how to create a remote (proxy) portlet in a consumer application using Oracle Enterprise Pack for Eclipse. This section includes the following topics:

• Section 4.3.1, "Overview"

• Section 4.3.2, "Setting Up the Example"

• Section 4.3.3, "Locating and Consuming a Portlet"

• Section 4.3.4, "Viewing the Portlet"

• Section 4.3.5, "Summary"

4.3.1 Overview

For this example, you will consume a portlet deployed in a producer application. The producer application in this example is a Portal Web application deployed to a WebLogic Portal Domain.

Tip:

For information on working with a producer that is running in a WebLogic Server domain (as opposed to a WebLogic Portal Domain), see Chapter 8, "Configuring a WebLogic Server Producer."

The basic procedure for creating remote portlets is fairly simple: Oracle Enterprise Pack for Eclipse provides a convenient wizard for this purpose. No programming is required. The basic steps always include:

1. Locating a producer.

2. Selecting a remote portlet on the producer.

3. Consuming the portlet.

Figure 4-1 illustrates the basic parts of a federated portal, where the consumer includes a remote portlet. A remote portlet is a proxy for a portlet that is deployed in a producer application.

Tip:

To an end user, the features of the remote portlet are indistinguishable from the actual portlet deployed on the producer. It is possible, however, to customize many of the properties of a proxy portlet, as explained in Chapter 5, "Configuring Remote Portlets."

Figure 4-1 Remote Portlet in a Consumer

Description of "Figure 4-1 Remote Portlet in a Consumer "

4.3.2 Setting Up the Example

If you want to try the example discussed in this section, you need to run Oracle Enterprise Pack for Eclipse and perform the prerequisite tasks outlined in this section.

To set up the example environment, perform the prerequisite tasks outlined in Table 4-1. If you are not familiar with the specific procedures for these tasks, they are described in detail in Oracle Fusion Middleware Tutorials for Oracle WebLogic Portal.

Table 4-1 Prerequisite Tasks

Task	Recommended Name
Create a WebLogic Portal domain.	consumerPortalDomain
Create a Portal EAR Project.	portalEarProject
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 portal.	consumer.portal

Figure 4-2 shows the Project Explorer after the prerequisite tasks have been completed.

Figure 4-2 Project Explorer After Prerequisite Tasks are Completed

Description of "Figure 4-2 Project Explorer After Prerequisite Tasks are Completed"

4.3.3 Locating and Consuming a Portlet

1. Be sure you have set up the example environment as explained previously in Section 4.3.2, "Setting Up the Example".

2. Open the consumerProject folder in the Project Explorer, right-click on the WebContent folder, and select New > Portlet.

   Tip:

   If you do not see the Portlet feature on the New menu, be sure to open the Portal perspective using Window > Open Perspective > Portal.

3. In the New Portlet dialog, enter remoteExample.portlet in the File name field, and click Finish. The Select Portlet Type dialog appears.

4. In the Select Portlet Type dialog, select Remote Portlet, as shown in Figure 4-3, and click Next. The Portlet Wizard – Producer dialog box appears.

   Figure 4-3 Select Portlet Type Dialog

   
   Description of "Figure 4-3 Select Portlet Type Dialog "
   
   

5. In the Portlet Wizard – Producer dialog, select Find Producer and, in the field provided, enter a WSDL URL. For example:

   http://wsrp.bea.com/portal/producer?wsdl 
   

   Just remember that the pattern for the URL is as follows:

   http://host:port/webAppName/producer?wsdl

   where host is the host and port are the hostname and port number of the server on which the producer is deployed, and webAppName is the name of the web application in which the producer's portlets are deployed.

   Tip:

   If the producer was previously added to the consumer, it will appear in the Select Producer list, and you can simply choose Select Producer and select the producer from the list.

   Tip:

   WSDL stands for Web Services Description Language and is used to describe the services offered by a producer. For more information, see Chapter 3, "Federated Portal Architecture."

   Figure 4-4 Entering the WSDL

   
   Description of "Figure 4-4 Entering the WSDL "
   
   

6. After entering the WSDL URL, click Retrieve.

   Checkpoint: At this point, the consumer uses the WSDL to locate the producer and learn about its available portlets. The Producer Details section of the wizard panel now displays information about the producer, including the number of portlets that are available to the consumer, as shown in Figure 4-5.

7. Click Register in the Producer Details section of the wizard panel, as shown in Figure 4-5. The Register dialog appears.

   Tip:

   During registration, the producer stores information about the consumer and returns a handle to the consumer. 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.

   Figure 4-5 Producer Details

   
   Description of "Figure 4-5 Producer Details"
   
   

8. In the Register dialog, enter beaProducer in the Producer Handle field, as shown in Figure 4-6. This handle identifies the producer on the consumer. This dialog also lets you choose to store registration properties on the consumer and (if available) edit the registration properties 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. For detailed information storing registration properties, see Chapter 14, "Other Topics and Best Practices."

   Figure 4-6 Registering the Producer

   
   Description of "Figure 4-6 Registering the Producer"
   
   

9. Click Register. You are returned to the Producer dialog.

   Checkpoint: At this point the WSDL data from the producer has been retrieved and is displayed in the Producer Details panel of the dialog, as shown in Figure 4-7. Note that four portlets on the producer are available to the consumer.

   Figure 4-7 Registration Information

   
   Description of "Figure 4-7 Registration Information"
   
   

10. Click Next to proceed.

11. In the Select Portlet from List dialog, select one of the remote portlets from the list of portlets on the producer, as shown in Figure 4-8. You can pick any one of them.

    Figure 4-8 Select a Portlet on the Producer

    
    Description of "Figure 4-8 Select a Portlet on the Producer"
    
    

12. Click Next. The Proxy Portlet Details dialog appears. The title of the portlet you selected appears in the Portlet Title field, as shown in Figure 4-9. You can change this title if you want to.

    Note:

    If the producer does not require registration, the Producer's Handle field will appear editable and initialized. In this case, you must enter an arbitrary value for the producer handle before the Create button will be enabled.

    Figure 4-9 The Proxy Portlet Details

    
    Description of "Figure 4-9 The Proxy Portlet Details"
    
    

13. Click Create.

    The new remote portlet shows up in the Project Explorer in the WebContent folder, as shown in Figure 4-10.

    Figure 4-10 Remote Portlet

    
    Description of "Figure 4-10 Remote Portlet"
    
    

4.3.4 Viewing the Portlet

To view the portlet, you need to add it to the consumer portal, as explained in this section.

1. If it is not already open, open the consumerProject/WebContent folder.

2. Double-click the file consumerPortal.portal in WebContent folder. The portal editor appears in Oracle Enterprise Pack for Eclipse.

3. Drag the remoteExample.portlet file from the Project Explorer to the portal. The result is shown in Figure 4-11.

   Figure 4-11 Remote Portlet Placed in Portal

   
   Description of "Figure 4-11 Remote Portlet Placed in Portal"
   
   

4. To test the portal, right-click the portal filename, remoteExample.portlet, in the Project Explorer, and select Run As > Run On Server. The New Server – Define a Server dialog appears.

5. In the Run On Server – Define a New Server dialog, be sure the Oracle WebLogic Server v10.x is selected, and click Finish.

6. The portal containing the remote portlet appears in a browser, as shown in Figure 4-12.

   Figure 4-12 Federated Portal

   
   Description of "Figure 4-12 Federated Portal "
   
   

4.3.5 Summary

In this section you added a remote portlet to a WebLogic Portal consumer application. The consumed portlet is a proxy for a portlet that is deployed in a remote producer application. In addition to the basic setup steps, this example demonstrated the following tasks:

• Discovering the producer using its WSDL URL

• Registering the producer

• Selecting a portlet from the producer

• Adding the remote portlet to a consumer portal

• Running a consumer portal

4.4 Creating Remote Pages and Books

The primary advantage of remote books and pages is that they act as containers for other remote resources. For example, a producer can offer a remote book that contains several remoteable pages, each of which contain multiple remoteable portlets. When you consume that book, the remoteable pages and portlets it contains are consumed as well—no additional steps are required.

Tip:

The term remoteable refers to a book, page, or portlet that is deployed in a producer application and that is offered as remote to consumers. Application developers decide whether or not books, pages, and portlets they create are offered as remote.

For detailed information on creating remoteable pages and books in a producer application, see Chapter 6, "Offering Books, Pages, and Portlets to Consumers." If a remote book or page does not appear as you expect it to, see Section 6.4, "Rules for Creating Remoteable Books and Pages".

Remember that changes you make to a remote book or page are not reflected back to the producer; therefore, after a remote book or page is modified on the consumer, it can become inconsistent with the original book, page, or portlet in the producer application.

You can add remote books and pages to your portal as you would any other book or page.

4.4.1 Basic Procedure

The procedure for creating a remote page or book is similar to the procedure for creating a remote portlet.

Tip:

This example explains how to create a remote page. The procedure for creating a remote book is similar.

1. Select File > New > Other.

2. In the New dialog, select Remote Page (or Remote Book), as shown in Figure 4-13, and click Next.

   Figure 4-13 Creating a New Remote Page

   
   Description of "Figure 4-13 Creating a New Remote Page"
   
   

3. In the New Remote Page dialog, select a folder in which to place the resulting .page file, and give the file a name, as shown in Figure 4-14, and click Next.

   Figure 4-14 Creating a Remote Page File

   
   Description of "Figure 4-14 Creating a Remote Page File"
   
   

4. In the Page Producer dialog, select Find Producer and, in the field provided, enter the WSDL URL of the producer, as shown in Figure 4-15:

   The pattern for the WSDL URL is as follows:

   http://host:port/webAppName/producer?wsdl

   where host and port are the hostname and port number of the server on which the producer is deployed, and webAppName is the name of the web application in which the producer's remoteable pages and books are deployed.

   Tip:

   If the producer was previously added to the consumer, it will appear in the Select Producer list, and you can simply choose Select Producer and select the producer from the list.

5. After entering the WSDL URL, click Retrieve.

   Checkpoint: At this point, the consumer uses the WSDL URL to locate the producer and learn about its available remoteable pages. The Producer Details section of the wizard panel now displays information about the producer, including the number of pages that are available to the consumer, as shown in Figure 4-15.

6. Click Register in the Producer Details section of the wizard panel, as shown in Figure 4-15. The Register dialog appears.

   Figure 4-15 Producer Details

   
   Description of "Figure 4-15 Producer Details"
   
   

   Tip:

   During registration, the producer stores information about the consumer and returns a handle to the consumer. 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 books and pages offered by the producer. See Section 3.4.2.2, "Complex Producers" for more information.

7. In the Register dialog, enter a handle name in the Producer Handle field, as shown in Figure 4-6. This handle identifies the producer on the consumer.

   Figure 4-16 Registering the Producer

   
   Description of "Figure 4-16 Registering the Producer"
   
   

8. Click Register. You are returned to the New Remote Page–Page Producer dialog.

   Checkpoint: At this point the WSDL data from the producer has been retrieved and is displayed in the Producer Details panel of the dialog.

9. Click Next to proceed.

10. In the Select Page from List dialog, select one of the remote pages from the list of pages offered by the producer, as shown in Figure 4-8, and click Next.

    Figure 4-17 Select a Page on the Producer

    
    Description of "Figure 4-17 Select a Page on the Producer"
    
    

11. The Remote Page Details dialog appears. The title of the page you selected appears in the Page Title field, as shown in Figure 4-9. You can change this title if you want to.

    Note:

    If the producer does not require registration, the Producer's Handle field will appear editable and uninitialized. In this case, you must enter an arbitrary value for the producer handle before the Finish button will be enabled.

    Figure 4-18 The Remote Page Details Dialog

    
    Description of "Figure 4-18 The Remote Page Details Dialog"
    
    

12. Click Finish.

    The new remote page shows up in the Project Explorer in the folder you selected. The page appears as a .page file, for example, /WebContent/myRemotePage.page. You can now add the remote page to your portal. Any remoteable portlets on the page will show up in the remote page as inlined portlets. For more information on remoteable portlets, pages, and books as remote, see Chapter 6, "Offering Books, Pages, and Portlets to Consumers." For information on inlined portlets, see the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.