Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter 11g Release 1 (11.1.1.5.0) E10148-16 |
|
![]() Previous |
![]() Next |
This appendix describes how to reuse components from your existing Oracle Portal application in a WebCenter Portal application built with Oracle WebCenter Framework.
This appendix includes the following sections:
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 57.2.3.1, "PDK-Java Producers."
WSRP producers serve as the containers for standards-based portlets. For more information, see Section 57.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 Oracle WebCenter 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 WebCenter Portal 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 Oracle WebCenter Framework. For more information, see Section F.3, "Reusing Items."
Given the technical differences between Oracle Portal and WebCenter, there is no direct upgrade available across the platform. However, key components of your portal can be exposed within WebCenter.
You can make the portlets used in your portal available to your WebCenter Portal applications.
This section includes the following subsections:
Section F.2.1, "How to Reuse JSR 286 and Oracle PDK-Java Portlets"
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"
To reuse JSR 286 and Oracle PDK-Java portlets in your WebCenter Portal application, simply register the producers in the same way as any other producer.
To reuse JSR 286 and Oracle PDK-Java portlets:
In Oracle JDeveloper, access the WSRP or Oracle PDK-Java Producer Registration wizard.
Step through the wizard providing information about the producer, including the URL endpoint.
Open the page to which you to add the portlet.
Drag the portlet from the registered producer to the appropriate part of the page.
For more detailed information about consuming portlets in a WebCenter Portal application, see Chapter 63, "Consuming Portlets."
Oracle PDK-Java events are not supported in Oracle WebCenter Framework. If you have Oracle PDK-Java portlets that use events and you deploy them in an Oracle WebCenter Framework environment, then the events are ignored.
Mobile portlets are not supported in Oracle WebCenter Framework. If you have Oracle PDK-Java mobile portlets, then they do not work in a Oracle WebCenter Framework environment.
In Oracle WebCenter 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 Oracle WebCenter Framework environment.
As part of this filtering process, Oracle WebCenter 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 Oracle WebCenter 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.
Portlet customizations and personalizations that you or your users applied to your portlets in Oracle Portal are not carried over to your WebCenter Portal application. In a WebCenter Portal application, your Oracle Portal portlets are treated as new instances. Hence, previous personalizations and customizations are not available.
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 Oracle WebCenter 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 Oracle WebCenter 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 Oracle WebCenter Framework environment by using the proper portlet APIs.
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.
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 WebCenter Portal applications.
Note: You can also expose Oracle Portal pages in WebCenter 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 WebCenter Portal 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 WebCenter Portal 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 Oracle WebCenter:
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.
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:
Log in to the Oracle Portal instance as the portal administrator user.
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.
In the Last Name field, enter PORTAL.
In the User ID field, enter PORTAL.
In the Password and Confirm Password fields, enter an appropriate password.
In the Email Address field, enter an appropriate email address.
Click Submit, then Done.
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.
In the Default Group field, enter PORTLET_PUBLISHERS
.
Click OK.
If you want to display Oracle Portal pages in your WebCenter Portal 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.
Confirm that the users of the WebCenter Portal 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 WebCenter Portal 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 WebCenter Portal application and Oracle Portal.
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 user information is correctly propagated to Oracle Portal.
For more information, see Section 63.2.3, "How to Register an Oracle PDK-Java Portlet Producer."
You can drag and drop the producer's portlets onto a page.
To secure communication between the Oracle Portal instance and Oracle WebCenter, provide a shared key using Hash Message Authentication Code (HMAC):
Go to SQL*Plus and log in as the portal schema owner.
Run:
@wwc/proadssr.sql http://www.oracle.com/adapter/portal
Note that, for WebCenter Portal applications, the adapter URL is always the same:
http://www.oracle.com/adapter/portal
Enter a shared key code.
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 |
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 WebCenter Portal applications. For these images to display correctly:
Download the following zip file:
http://download.oracle.com/otndocs/tech/portal/files/portal-images.zip
Extract the contents of the zip file and mount the contents under the URL /images.
You can now run the page that contains the portlet.
The following information may help when trying to resolve issues with the Federated Portal Adapter in Oracle WebCenter.
This section includes the following subsections:
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.
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 WebCenter Portal 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.
The following limitations apply when using the Federated Portal Adapter with Oracle WebCenter:
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. For a full list, see "Oracle Portal - Limitations" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.
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 WebCenter Portal 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 Oracle WebCenter Framework you must manually ensure that the images can be found by portlets.
This section includes the following subsections:
In Oracle WebCenter, 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:
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>
Add a servlet definition for the resource servlet as shown in Example F-2.
Add a servlet mapping for the resource servlet as shown in Example F-3.
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 63.2.3, "How to Register an Oracle PDK-Java Portlet Producer."
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:
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>
Add a servlet definition for the resource servlet as shown in Example F-5.
Add a servlet mapping for the resource servlet as Example F-6.
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 63.2.3, "How to Register an Oracle PDK-Java Portlet Producer."
Items from Oracle Portal have no equivalent in Oracle WebCenter Framework. As such, creating, maintaining, and publishing items is not supported in Oracle WebCenter Framework. To replicate the behavior of items with Oracle WebCenter Framework, you can use JCR data controls to include content from Oracle Portal. Oracle Portal is a content repository that Oracle WebCenter 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 26, "Configuring Content Repository Connections."