F Reuse of Oracle Portal Components

This appendix describes how to reuse components from your existing Oracle Portal application in an application built with Oracle WebCenter Portal: Framework.

This appendix includes the following sections:

• Section F.1, "Introduction to Oracle Portal Components"

• Section F.2, "Reusing Portlets"

• Section F.3, "Reusing Items"

F.1 Introduction to Oracle Portal Components

The two most basic building blocks of Oracle Portal are as follows:

• Portlets are the fundamental building blocks of a portal page. Portlets can be deployed to Oracle Portal through three producer (known in Oracle Portal as provider) types:

  • Web (or Oracle PDK-Java) producers use open standards, such as XML, SOAP, HTTP, or J2EE for deployment, definition, and communication with applications. The Oracle PDK-Java provides a framework that simplifies the task of building Web producers. For more information, see Section 58.2.3.1, "PDK-Java Producers."

  • WSRP producers serve as the containers for standards-based portlets. For more information, see Section 58.2.3.2, "WSRP Producers."

  • Database producers own one or more database portlets. Examples of database portlets include, portlets built using the Oracle PDK-PL/SQL, Portlet Builder portlets (charts, forms, reports, and so on), and Oracle Portal page portlets).

  In WebCenter Portal: Framework, you can make Web and WSRP portlets available by registering their producers with the application. For more information, see Section F.2.1, "How to Reuse JSR 286 and Oracle PDK-Java Portlets."

  You can also make database portlets available to Framework applications by using the Federated Portal Adapter. For more information, see Section F.2.8, "How to Use the Federated Portal Adapter to Reuse Database Portlets."

• Items are individual pieces of content (text, hyperlink, image, and so on) that reside on a page in an item region. Users with an appropriate privilege level can add items to a page. Item content and metadata are stored in the Oracle Portal schema of the Metadata Repository. Items are rendered on the page according to the layout, style, and attribute display defined for the item region.

  Because items are stored in a content repository, you can retrieve them with Java Content Repository (JCR) data controls. A default adapter for the Oracle Portal content repository is provided with WebCenter Portal: Framework. For more information, see Section F.3, "Reusing Items."

Given the technical differences between Oracle Portal and WebCenter Portal, there is no direct upgrade available across the platform. However, key components of your portal can be exposed within WebCenter Portal.

F.2 Reusing Portlets

You can make the portlets used in your portal available to your Framework applications.

This section includes the following subsections:

• Section F.2.1, "How to Reuse JSR 286 and Oracle PDK-Java Portlets"

• Section F.2.2, "What You May Need to Know About Events"

• Section F.2.3, "What You May Need to Know About Mobile Portlets"

• Section F.2.4, "What You May Need to Know About the Portlet Chrome"

• Section F.2.5, "What You May Need to Know About Personalizations and Customizations"

• Section F.2.6, "What You May Need to Know About Oracle Portal System Resources"

• Section F.2.7, "What You May Need to Know About Partner and External Applications"

• Section F.2.8, "How to Use the Federated Portal Adapter to Reuse Database Portlets"

• Section F.2.9, "What You May Need to Know About Troubleshooting the Federated Portal Adapter"

• Section F.2.10, "What You May Need to Know About Limitations of the Federated Portal Adapter"

• Section F.2.11, "How to Reuse Oracle PDK-Java Producers from Earlier Oracle Application Server Versions"

F.2.1 How to Reuse JSR 286 and Oracle PDK-Java Portlets

To reuse JSR 286 and Oracle PDK-Java portlets in your Framework application, simply register the producers in the same way as any other producer.

To reuse JSR 286 and Oracle PDK-Java portlets:

1. In Oracle JDeveloper, access the WSRP or Oracle PDK-Java Producer Registration wizard.

2. Step through the wizard providing information about the producer, including the URL endpoint.

3. Open the page to which you to add the portlet.

4. Drag the portlet from the registered producer to the appropriate part of the page.

For more detailed information about consuming portlets in a Framework application, see Chapter 64, "Consuming Portlets."

F.2.2 What You May Need to Know About Events

Oracle PDK-Java events are not supported in WebCenter Portal: Framework. If you have Oracle PDK-Java portlets that use events and you deploy them in an WebCenter Portal: Framework environment, then the events are ignored.

F.2.3 What You May Need to Know About Mobile Portlets

Mobile portlets are not supported in WebCenter Portal: Framework. If you have Oracle PDK-Java mobile portlets, then they do not work in a WebCenter Portal: Framework environment.

F.2.4 What You May Need to Know About the Portlet Chrome

In WebCenter Portal: Framework, the portlet does not provide the chrome. The consuming application provides the chrome. This behavior conforms to the WSRP convention, but it is a change from Oracle Portal, where Oracle PDK-Java provided the chrome for portlets. Hence, the Oracle PDK-Java portlet header is filtered out in the WebCenter Portal: Framework environment.

As part of this filtering process, WebCenter Portal: Framework parses the title area of PDK-Java portlets to preserve the title and add the necessary portlet mode links. The filtering algorithm is as follows:

• If the portlet has multiple tables, then the title area is considered to be the first table. If the portlet has only one table, then the title area is considered to be the first row in that table.

• The first text in the title area is considered to be the title. If the portlet has no tables or a discernible title, then the title is taken from the adfp:portlet component.

• Any link that contains the fragment _mode= parameter is considered to be a portlet mode link. These links are moved into the portlet menu by WebCenter Portal: Framework.

If you want to bypass the rendition of the header section of your portlet chrome and reuse its original, Oracle PDK-Java header, then you can set the displayHeader attribute of the adfp:portlet tag to false and retainPortletHeader as true in the associated portlet bindings of the page definition XML. Setting retainPortletHeader=true in the page definition portlet binding retains the portlet header in the portlet response. Setting displayHeader=false in the adf:portlet tag suppresses the application's header for the portlet chrome, and hides the icons and links normally displayed in the header.

F.2.5 What You May Need to Know About Personalizations and Customizations

Portlet customizations and personalizations that you or your users applied to your portlets in Oracle Portal are not carried over to your Framework application. In a Framework application, your Oracle Portal portlets are treated as new instances. Hence, previous personalizations and customizations are not available.

F.2.6 What You May Need to Know About Oracle Portal System Resources

Portlets built with a target consumer of Oracle Portal in mind tend to make invalid assumptions about the runtime environment. For example, the portlet might assume the presence of Oracle Portal resources, such as images or JavaScript functions. In WebCenter Portal: Framework, these resources are not available. Hence, you must bundle the resources the portlet needs with the producer to ensure that the portlet runs properly in the WebCenter Portal: Framework environment.

Another common issue with portlets designed for Oracle Portal consumption is the portlet assuming the Oracle Portal URL format and the presence of Oracle Portal parameters. The page URL of an Oracle ADF application is different from that of Oracle Portal. Therefore, portlet developers cannot make assumptions about the page URL and must prepare their Oracle PDK-Java portlets for execution in the WebCenter Portal: Framework environment by using the proper portlet APIs.

F.2.7 What You May Need to Know About Partner and External Applications

Partner applications are not supported. External applications are supported. Automatic login is supported through an external application automated login servlet, which is automatically configured in your application when you register a producer.

F.2.8 How to Use the Federated Portal Adapter to Reuse Database Portlets

The Federated Portal Adapter is a component of Oracle Portal that enables Oracle Portal instances to share their database portlets through the Web portlet interface. The Federated Portal Adapter receives the SOAP messages for a Web producer, parses the SOAP and then dispatches the messages to a database producer as PL/SQL procedure calls. In effect, the Federated Portal Adapter makes a database producer behave in the same way as a Web producer. You can make Oracle Portal database portlets, including PL/SQL portlets, Portlet Builder portlets, and page portlets, available for use in your Framework applications.

Note:

You can also expose Oracle Portal pages in WebCenter Portal through the Federated Portal Adapter by publishing them as portlets in Oracle Portal.

Implementing the Federated Portal Adapter for your portal exposes the Oracle Portal portlets through the Oracle PDK-Java Web producer protocol making it possible to register them as PDK-Java producers. Registering the producer with a Framework application causes the portlets to appear in the Component Palette, and you can then drag and drop them onto pages in the same way as any other portlet. Without the Federated Portal Adapter, you cannot access these producers from a Framework application.

For more information about the Federated Portal Adapter, see the chapter "Using the Federated Portal Adapter" in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

To register a Federated Portal Adapter producer with WebCenter Portal:

1. Set up the Oracle Portal environment for the Federated Portal Adapter. For more information, see the section "Setting Up the Environment to Use the Federated Portal Adapter" in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

2. To register an instance of Oracle Portal through the Federated Portal Adapter, the portal must have a user named "PORTAL" in Oracle Internet Directory. To create this user:

   1. Log in to the Oracle Portal instance as the portal administrator user.

   2. In the User portlet, click Create New Users.

      By default, the User portlet is on the Administer tab of the Portal Builder page, on the Portal subtab.

   3. In the Last Name field, enter PORTAL.

   4. In the User ID field, enter PORTAL.

   5. In the Password and Confirm Password fields, enter an appropriate password.

   6. In the Email Address field, enter an appropriate email address.

   7. Click Submit, then Done.

   8. In the Portal User Profile portlet, enter PORTAL in the Name field, and click Edit.

      By default, the Portal User Profile portlet is on the Administer tab of the Portal Builder page, on the Portal subtab.

   9. In the Default Group field, enter PORTLET_PUBLISHERS.

   10. Click OK.

3. If you want to display Oracle Portal pages in your Framework applications, you must first publish each of those pages as portlets. To display Oracle Portal pages, edit the page properties and select Publish As Portlet on the Optional tab. For more information, see the section "Placing One Page Onto Another" in the Oracle Fusion Middleware User's Guide for Oracle Portal.

4. Confirm that the users of the Framework application have appropriate privileges on the portlets and pages exposed through the Federated Portal Adapter, and that they map to the users of the Oracle Portal instance. The user name for a person on the Framework application should map to the user name of the same person in Oracle Portal. For example, JSMITH should represent the same person in both the Framework application and Oracle Portal.

5. In Oracle JDeveloper, register the producer as an Oracle PDK-Java producer using the Federated Portal Adapter URL and Service ID:

   http://host:port/adapter/dad/schema
   

   To verify the URL, enter it in a browser. If the URL is correct you should see the following message:

   Congratulations - you got to the adapter test page
   

   If you are logged in you should see a list of producers, their service IDs, and the portlets each provides. If you are logged in as an Oracle Portal administrator, you should also see additional details about page portlets and Oracle Portal HMAC registrations.

   When you register the producer, ensure that you select the Establish Producer Sessions checkbox on the Specify Connection Details page of the wizard. This is so that the WebCenter Portal user information is correctly propagated to Oracle Portal.

   For more information, see Section 64.2.3, "How to Register an Oracle PDK-Java Portlet Producer."

6. You can drag and drop the producer's portlets onto a page.

7. To secure communication between the Oracle Portal instance and WebCenter Portal, provide a shared key using Hash Message Authentication Code (HMAC):

   1. Go to SQL*Plus and log in as the portal schema owner.

   2. Run:

      @wwc/proadssr.sql http://www.oracle.com/adapter/portal
      

      Note that, for Framework applications, the adapter URL is always the same:

      http://www.oracle.com/adapter/portal
      

   3. Enter a shared key code.

   4. In Oracle JDeveloper, enter this shared key code into the Shared Key field on the Specify Additional Registration Details step of the Create/Edit Oracle PDK-Java Portlet Producer wizard or dialog.

   Note:

   To remove the shared key from the Oracle Portal instance use:

   @wwc/proadsdr.sql
   

8. Certain portlets built in Oracle Portal, such as page portlets and several sample database portlets, assume that the set of images shipped in the portal middle tier are available in the path /images in the Web server of the portal page. These images are not available by default for your Framework applications. For these images to display correctly:

   1. Download the following zip file:

      http://download.oracle.com/otndocs/tech/portal/files/portal-images.zip

   2. Extract the contents of the zip file and mount the contents under the URL /images.

9. You can now run the page that contains the portlet.

F.2.9 What You May Need to Know About Troubleshooting the Federated Portal Adapter

The following information may help when trying to resolve issues with the Federated Portal Adapter in WebCenter Portal.

This section includes the following subsections:

• Section F.2.9.1, "On Registration"

• Section F.2.9.2, "During Runtime"

F.2.9.1 On Registration

Error occurred trying to register producer

The shared key has not been set up in the Oracle Portal instance or it does not match that given in Oracle JDeveloper, or the service ID has not been entered.

Could not Contact Producer

Either the portal registration URL is not correct, the service ID given in Oracle JDeveloper does not match a provider in the Oracle Portal instance, the Oracle Portal instance could not be contacted (for example, it is behind a firewall or is not available), or the users in Oracle JDeveloper do not match those in Oracle Portal. The details of the message should give further information about the cause:

• 404 Not Found: The Oracle Portal instance could not be contacted or has timed out. Try increasing the time out period.

• 406 Not Acceptable: The provider with the given service ID could not be found in this Oracle Portal instance or HMAC authentication has either failed or been incorrectly configured.

• 503 Service Unavailable: the PORTAL user could not be found in Oracle Internet Directory. The Oracle Portal administrator may not have added the PORTAL user to Oracle Internet Directory.

F.2.9.2 During Runtime

Could not Contact Producer

Either the portal registration URL is not correct, the service ID given in Oracle JDeveloper does not match a provider in the Oracle Portal instance, the Oracle Portal could not be contacted (for example, if it is behind a firewall or not available), or the users in Oracle JDeveloper do not match those in Oracle Portal. The details of the message should give further information about the cause:

• 404 Not Found: The Oracle Portal instance could not be contacted or has timed out. Try increasing the time out period.

• 406 Not Acceptable: The provider with the given service ID could not be found in this Oracle Portal instance or HMAC authentication has either failed or been incorrectly configured.

• 503 Service Unavailable: the PORTAL user could not be found in Oracle Internet Directory. The Oracle Portal administrator may not have added the PORTAL user to Oracle Internet Directory.

Portlet does not render properly

• If images are missing or appear as links, see the instructions for downloading the images zip file provided in Section F.2.8, "How to Use the Federated Portal Adapter to Reuse Database Portlets."

• If navigation does not work properly, try editing the page and setting RenderPortletInIframe to true. Some portlets work better in their own inline frame (IFRAME).

• If the portlet responds with the following message, try putting the portlet in an IFRAME, by setting RenderPortletInIframe to true:

  The portlet attempted to issue a redirect in response to a render request.
  

• If popups, lists of values, and so on do not work in the portlet, it may be because JavaScript exceptions are raised in an attempt to avoid XSS attacks. The popup must have the same server URL as the Framework application.

• If a portlet renders a blank screen for Customize or Personalize, it may be that the user does not have permission to edit the portlet. Check the Portal log files.

F.2.10 What You May Need to Know About Limitations of the Federated Portal Adapter

The following limitations apply when using the Federated Portal Adapter with WebCenter Portal:

• Deep linking may not work. In some cases, putting the portlet in an IFRAME helps (setting RenderPortletInIframe to true).

• Links rendered by the portlet must be absolute URLs.

• If a page portlet displays a page with tabs it should be placed into an IFRAME.

• Refresh, Collapse, and Remove portlet links do not work in portlets displayed in page portlets.

• Not all objects are returned by the Federated Portal Adapter, and thus are not visible in WebCenter Portal. For a full list, see "Oracle Portal - Limitations" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

F.2.11 How to Reuse Oracle PDK-Java Producers from Earlier Oracle Application Server Versions

If you have a producer that you designed and deployed on Oracle Application Server Release 2 (10.1.2) or earlier, then you can reuse it in either one of two ways:

• You can consume a portlet from a producer running on an Oracle Application Server Release 2 (10.1.2.0.2) middle tier. In this case, the producer's code is running on Release 2 (10.1.2.0.2) while the application consuming the producer is running on Release 11.

• You can redeploy the producer application as an EAR file on Oracle WebLogic Server and consume its portlets in other Framework applications. In this case, both the producer's code and the consuming application run on Release 11.

In either of these cases, you must take some additional steps to get the producer's portlets to operate correctly. Portlets built for Oracle Portal expect certain boilerplate images to be present on the page assembly servlet and they break if those images are not available. These images were included in the middle-tier servlet by default in Oracle Application Server Release 2 (10.1.2.0.2), but for WebCenter Portal: Framework you must manually ensure that the images can be found by portlets.

This section includes the following subsections:

• Section F.2.11.1, "Consuming a Portlet from Oracle Portal"

• Section F.2.11.2, "Redeploying PDK-Java Producers from Oracle Portal"

F.2.11.1 Consuming a Portlet from Oracle Portal

In WebCenter Portal, to consume a portlet running on a page in an Oracle Portal instance, you can do either of the following:

• Obtain the Oracle Portal images zip file from the Oracle Technology Network and unzip it inside the ADFP servlet.

• Properly configure the resource servlet as follows:

1. Add an initialization parameter to the Web servlet as shown is Example F-1.

   Example F-1 Web Servlet Initialization Parameters

   <servlet> 
    <servlet-name>SOAPServlet</servlet-name> 
    <display-name>SOAPServlet</display-name> 
    <description>Extended Portal SOAP Server</description> 
    <servlet-class>oracle.webdb.provider.v2.adapter.SOAPServlet</servlet-class> 
    ...
    <init-param> 
      <param-name>resourceServletMapping</param-name> 
      <param-value>/pdkresource</param-value> 
    </init-param> 
   </servlet>
   

2. Add a servlet definition for the resource servlet as shown in Example F-2.

   Example F-2 Servlet Definition for Resource Servlet

   <servlet> 
    <servlet-name>ResourceServlet</servlet-name> 
     <display-name>ResourceServlet</display-name> 
     <description>Image resource servlet</description>     
     <servlet-class>oracle.webdb.provider.v2.adapter.ResourceServlet</servlet-class> 
   </servlet>
   

3. Add a servlet mapping for the resource servlet as shown in Example F-3.

   Example F-3 Servlet Mapping for Resource Servlet

   <servlet-mapping> 
    <servlet-name>ResourceServlet</servlet-name> 
    <url-pattern>/pdkresource/*</url-pattern> 
   </servlet-mapping> 
   

4. Now you can register this PDK-Java producer in the same way as any other PDK-Java producer. For more information about registering PDK-Java producers, see Section 64.2.3, "How to Register an Oracle PDK-Java Portlet Producer."

F.2.11.2 Redeploying PDK-Java Producers from Oracle Portal

If you choose to take a PDK-Java producer built for Oracle Portal and redeployed on Oracle WebLogic Server, then you must enable the resource servlet as follows:

1. Add an initialization parameter to the Web servlet as shown in Example F-4.

   Example F-4 Web Servlet Initialization Parameter

   <servlet> 
    <servlet-name>SOAPServlet</servlet-name> 
    <display-name>SOAPServlet</display-name> 
    <description>Extended Portal SOAP Server</description> 
    <servlet-class>oracle.webdb.provider.v2.adapter.SOAPServlet</servlet-class> 
    ...
    <init-param> 
      <param-name>resourceServletMapping</param-name> 
      <param-value>/pdkresource</param-value> 
    </init-param> 
   </servlet>
   

2. Add a servlet definition for the resource servlet as shown in Example F-5.

   Example F-5 Servlet Definition for Resource Servlet

   <servlet> 
    <servlet-name>ResourceServlet</servlet-name> 
     <display-name>ResourceServlet</display-name> 
     <description>Image resource servlet</description>     
     <servlet-class>oracle.webdb.provider.v2.adapter.ResourceServlet</servlet-class> 
   </servlet>
   

3. Add a servlet mapping for the resource servlet as Example F-6.

   Example F-6 Servlet Mapping for Resource Servlet

   <servlet-mapping> 
    <servlet-name>ResourceServlet</servlet-name> 
    <url-pattern>/pdkresource/*</url-pattern> 
   </servlet-mapping> 
   

4. Now you can register this PDK-Java producer in the same way as any other PDK-Java producer. For more information about registering PDK-Java producers, see Section 64.2.3, "How to Register an Oracle PDK-Java Portlet Producer."

F.3 Reusing Items

Items from Oracle Portal have no equivalent in WebCenter Portal: Framework. As such, creating, maintaining, and publishing items is not supported in WebCenter Portal: Framework. To replicate the behavior of items with WebCenter Portal: Framework, you can use JCR data controls to include content from Oracle Portal. Oracle Portal is a content repository that WebCenter Portal: Framework supports out of the box in the Create a Content Repository Data Control dialog in JDeveloper. For more information about integrating content from Oracle Portal, see Chapter 27, "Managing Content Repository Connections."