| Oracle® Fusion Middleware Portal Development Guide for Oracle WebLogic Portal 10g Release 3 (10.3.4) Part Number E14243-06 |
|
|
View PDF |
| Oracle® Fusion Middleware Portal Development Guide for Oracle WebLogic Portal 10g Release 3 (10.3.4) Part Number E14243-06 |
|
|
View PDF |
This chapter explains how to add or import existing web applications to an existing WebLogic Portal application. This chapter includes these topics:
Section 5.1, "Apache Beehive and Apache Struts Supported Configurations"
Section 5.2, "Importing Existing Struts Applications into WebLogic Portal"
Section 5.4, "Integrating Existing Java Server Faces Applications into WebLogic Portal"
Section 5.6, "Other Methods of Integrating an External Web Application into a Portal"
Note:
If you have an existing web application to which you want to add WebLogic Portal features, see Chapter 6, "Integrating WebLogic Portal into Existing Web Applications."
This section discusses supported configurations for Apache Beehive and Apache Struts in WebLogic Portal. The following topics are discussed:
Section 5.1.2, "Supported Configurations for Apache Beehive"
Section 5.1.4, "Mixing Apache Struts 1.3 and Apache Beehive NetUI Applications"
Apache Beehive is an open source Java Application Framework for building Java EE based applications. WebLogic Portal offers optional support for Apache Beehive. If the Apache Beehive facets are added to your web application, you can use the Oracle Enterprise Pack for Eclipse to create Java Page Flows and you can use the WebLogic Portal Portlet Wizard to create Page Flow portlets.
Like Apache Beehive, Apache Struts is an open source Java Application Framework for building Java EE based applications. WebLogic Portal offers optional support for Struts. See also Section 5.2, "Importing Existing Struts Applications into WebLogic Portal."
WebLogic Portal does not support Apache Beehive by default. To use Apache Beehive dependent features, like Java Page Flow portlets, you must install the appropriate Apache Beehive and Struts facets into your portal web application. Once these facets are added, you can use Oracle Enterprise Pack for Eclipse to create new Java Page Flows and Java Page Flow portlets.
Note:
Content Presenter portlets require the Apache Beehive facets. For information on Content Presenter, see "Adding the Content Presenter Portlet" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
For information on installing facets into an existing portal web project, see Section 5.5, "Adding Facets to an Existing Project." For information on creating a new portal web project, see Section 4.6, "Portal Web Project Wizard."
The supported configurations for Apache Beehive in a WebLogic Portal web application are:
| Supported | Not Supported |
|---|---|
|
Neither Struts nor Apache Beehive installed (This is the default configuration for WLP.) |
Apache Beehive with Struts 1.3. See also Section 5.1.4, "Mixing Apache Struts 1.3 and Apache Beehive NetUI Applications." |
|
Apache Beehive with Struts 1.1 – For full WLP support, these facets are required:
Note: The Project Facets dialog enforces these listed requirements. |
Beehive NetUI without Struts 1.1 or 1.2 installed. |
|
Beehive NetUI with Struts 1.2 – For full WLP support, these facets are required:
Note: The Project Facets dialog enforces these listed requirements. |
WebLogic Portal does not support Apache Struts by default. To use Struts applications and Struts-dependent WLP features, like Struts portlets, you must add the appropriate Struts facets into your portal web application, as explained in this section.
For information on installing facets into an existing portal web project, see Section 5.5, "Adding Facets to an Existing Project." For information on creating a new portal web project, see Section 4.6, "Portal Web Project Wizard."
The supported configurations for Apache Struts in a WebLogic Portal web application are listed in the following table:
| Supported | Not Supported |
|---|---|
|
Struts not installed (This is the default configuration for WLP.) |
Apache Beehive with Struts 1.3. See also Section 5.1.4, "Mixing Apache Struts 1.3 and Apache Beehive NetUI Applications." |
|
Struts 1.1 – For full WLP support, the following facets are required:
Note: This configuration requires the above listed facets. Apache Beehive is required even if you do not intend to use it. The Project Facets dialog enforces this requirement. |
Struts 1.1 or 1.2 without Apache Beehive. |
|
Struts 1.2 – For full WLP support, the following facets are required:
Note: This configuration requires the above listed facets. Apache Beehive is required even if you do not intend to use it. The Project Facets dialog enforces this requirement. |
|
|
Struts 1.3 – For full WLP support, the following facets are required:
Note: Apache Beehive is not required with Struts 1.3. |
Apache Struts 1.3 and Apache Beehive NetUI 1.0.2 cannot co-exist in the same web application. This configuration is not supported by WebLogic Portal. A possible workaround to this limitation is to use federated portal (WSRP) techniques. For example, you could have two web applications, one that has Struts 1.3 enabled (but not Apache Beehive) and the other with Apache Beehive enabled (but not Struts 1.3). Using federation, you could consume portlets from the Struts 1.3-enabled producer in the portal application that uses Apache Beehive NetUI 1.0.2 (or the other way around). For information on federation, see Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.
Another, similar, option is to use Portlet Publishing instead of WSRP. For details, see "Portlet Publishing" in the Oracle Fusion Middleware Client-Side Developer's Guide for Oracle WebLogic Portal.
Note that is possible to have a Struts 1.3 enabled web application and a Apache Beehive NetUI 1.0.2 (Java Page Flow) application that co-exist in the same EAR project.
You can integrate, or import, a Struts application into an enterprise application in Oracle Enterprise Pack for Eclipse. Once in Oracle Enterprise Pack for Eclipse, you can give the Struts application a portal user interface by creating portlets, add personalization and campaign functionality, and take advantage of WebLogic Portal's content and user management services.
This topic contains the following sections:
By default, Struts support is optional in WebLogic Portal. This means that to use Struts framework technology with WebLogic Portal, you must enable it by installing the appropriate Struts facet. By offering Struts as an optional framework, WebLogic Portal is able to support multiple, arbitrary versions of Struts. See also Section 5.1.3, "Supported Configurations for Apache Struts."
Follow the guidelines presented in this section as you prepare your existing Struts application for integration with WebLogic Portal:
If you have a top-level Struts application, you must refactor it before you can integrate it. Any Struts applications that are intended for use in a portal must be developed as Struts modules, including the usage of the html:link tag for any URLs used in JSPs. Without this, it is impossible for WebLogic Portal to perform the necessary URL rewriting that is required to transparently modify links when the Struts application is used within a portlet.
As part of this process, modify your application to use WebLogic Portal tags using either of these methods:
Rely on the taglib mapping in web.xml to map the WebLogic Portal struts adapter tags to the URI that you already have in your JSPs; this allows you to use your existing JSPs.
To use Struts 1.2, which is the default version of Struts used for new portal web projects, Oracle recommends that you change your JSPs to use WebLogic Portal taglib URIs; this prevents you from having to change your web.xml file, and provides the benefit that these taglibs are automatically deployed.
If a Struts application used within a portal also needs to support stand-alone operation, JSPs referenced by Action forwards must be authored to use several optional tags in the HTML tag library found in struts.jar and struts-adapter.jar (a file that is created by Oracle). The first of these, <html:html>, is found in both Struts and the Struts-adapter. The Struts-adapter version overrides the Struts version of the tag and adds support for detecting whether or not to inhibit rendering of the tag output text if it is used from within a portal, where outputting the HTML text would result in non-well-formed HTML. Two additional tags are provided in the Struts-adapter version of the HTML tag library; use them in JSPs that also need to be used standalone: <html:head> and <html:body>. These two tags have the same portal-aware rendering behavior as the <html:html> tag.
Some Struts applications use a custom RequestProcessor. WebLogic Portal Struts integration requires that you override certain behaviors of a RequestProcessor. The class com.bea.struts.adapter.action.AdapterRequestProcessor, located in struts-adapter.jar, provides this standard behavior and must be used in all Struts applications used within a portal. Any custom RequestProcessors must either extend this class or use a utility class to perform the same required operation that this RequestProcessor performs. When extending this class, overrides of doForward() must call the superclass doForward() and also must not attempt to write to the response. Custom RequestProcessors that do not extend AdapterRequestProcessor must call com.bea.struts.adapter.action.AdapterRequestProcessorUtil.forwardUsingRequest() to perform any forwarding operations. (This method replaces an actual RequestDispatcher forward request with an operation that captures the forward URI for later use in including the URI into the portal output.)
If a Struts application depends on the use of a custom Action servlet, it must be refactored to use a custom RequestProcessor instead, as outlined above, and as recommended by the Struts implementation. Since the page flow functionality in WebLogic Portal uses a custom Action servlet, and since there can be only one Action servlet in a portal web project, portal Struts integration requires that the Action servlet not be customized. For more information on refactoring an Action servlet customization into a RequestProcessor customization, see the Struts documentation at http://jakarta.apache.org/struts/.
The StrutsContent control supports module switching using Action forwards. If the Action forward returned by an invoked Action results in a content URI that resides in another module, the current module is switched to the corresponding new module, and all further requests to the Struts portlet containing the control are performed using the new module. Perform module switching using only Action forwards, not by using the <html:link> tag to directly link to a JSP in another module; doing so might prevent the portal and Struts frameworks from correctly setting up and selecting the module.
Perform these steps to integrate your refactored Struts application:
Create a portal application and portal web project to which you will add the Struts application. For instructions, refer to Chapter 4, "Setting up Your Portal Development Environment."
Note:
Struts is not by default part of a new WebLogic Portal application. You must add the appropriate Struts facet to the project when you create the WLP web project or add it to an existing project. See Section 5.5, "Adding Facets to an Existing Project." For information on the versions of Struts that are supported by WLP, see Section 5.1, "Apache Beehive and Apache Struts Supported Configurations."
You may or may not need to perform this step. In order for URLs in the Struts pages to resolve correctly, page flow support must be enabled. By default, page flow support is enabled, but if the page flow setting has been disabled at some point, you must edit the portal web project's WEB-INF/netuix-config.xml file to enable it. Example 5-1 shows the syntax of the tag that you might need to add to the netuix-config.xml file. Notice that the <enable> element is set to true.
Example 5-1 Enabling and Disabling Page Flow Support Using the <pageflow> Tag
<!-- Enable or disable Pageflow support -->
<pageflow>
<enable>true</enable>
</pageflow>
If this block is not present in netuix-config.xml, do not add it. Without the block, the setting defaults to true.
Deploy the Struts application to the portal web project.
Note:
The following steps assume a deployment structure that is not based on split-source; your specific steps might differ from these example steps.
Copy any JSP, HTML, or image files into the portal web project following the standard Struts module directory structure (the module path is the directory path relative to the web application root).
Copy any supporting Java source used by the Struts application into the project's source folder, typically Web_Project_Name/src.
Copy any necessary custom JARs for the Struts application into WEB-INF/lib folder.
Copy the Struts application module's struts-config.xml or module configuration file into WEB-INF, but rename it struts-auto-config-<module-path>.xml, where <module-path> is the module path to the Struts application relative to the web application root, with all instances of '/' or '\' changed to '-'.
For example, if the module path is /struts/my/module, then rename struts-config.xml to struts-auto-config-struts-my-module.xml. Naming the module configuration file in this manner enables the PageFlowActionServlet used as the Action Servlet to automatically register the module without explicitly registering it with an init-param in web.xml. If you don't want to take advantage of this functionality, you can rename struts-config.xml arbitrarily, but you must manually register the module in web.xml as usual for a Struts 1.1 or 1.2 (Apache Beehive) module.
In the module configuration file, add the following line to configure the RequestProcessor that is required for portal integration:
<controller processorClass="com.bea.struts.adapter.action .AdapterRequestProcessor"/>
(unless the Struts application requires a custom RequestProcessor).
Create a portlet that contains a StrutsContent control that specifies the module and the default action for the Struts application. For instructions, refer to the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
Add the new portlet to the portal. For instructions, refer to the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
Use the following guidelines for integrating Struts applications in portals:
It is highly recommended that you fully develop and test a Struts application before attempting to host it within a portal. This helps to separate the complexities of developing a working Struts application from the additional issues involved in putting the Struts application into a portlet.
If you encounter stack traces or messages in the Struts application portlet showing that an action cannot be found, ensure that the module is correctly configured, named correctly, and registered in web.xml. This can be tested by running the Struts application stand-alone.
If you encounter resource not found exceptions or class not found exceptions for dependent classes:
Make sure that all dependent Java source exists in WEB-INF/src, and that it has successfully been built into the corresponding class files in WEB-INF/classes.
If more than one message-resource element is specified in the Struts configuration file for the module, any module files that reference a non-default message bundle must append the module path to the bundle key. For example, if the bundle key is alternate, and the module is /my/module, any users of the bundle must fully qualify it as alternate/my/module.
If following action links in a Struts portlet results in full-screen, stand-alone Struts pages, make sure that struts-adapter JSP tag libraries are in the project's WEB-INF/lib directory and that they are registered in web.xml.
If the "No ActionResult returned for action" error is returned when the action attribute of an html:form element contains a query parameter, use a hidden html:text input field.
If you have an existing Java Page Flows application, you can integrate the page flows into a portal by installing the WebLogic Portal-related facets using the steps described in Chapter 6, "Integrating WebLogic Portal into Existing Web Applications"; then you surface those page flows using portlets. You can also build new page flows within the portal web project before creating page flow portlets.
For instructions on creating a page flow, refer to the Oracle Enterprise Pack for Eclipse online help. For instructions on creating page flow portlets, refer to "Building Portlets" in Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
In order for URLs in the page flows to resolve correctly, page flow support must be enabled. By default, page flow support is enabled, but if the page flow setting has been disabled at some point, you must edit the portal web project's WEB-INF/netuix-config.xml file to enable it. Example 5-2 shows the syntax of the tag that you might need to add to the netuix-config.xml file. Notice that the <enable> element is set to true.
Generally the integration process for JSF is simple, requiring only that you follow the instructions accompanying the distribution of JSF that you are using. The portal-specific tasks for incorporating a JSF application into WebLogic Portal are:
Create a .portlet file with a facesContent control.
Insert the namingContainer JSP tag as an immediate child of the JSF view tag.
Note:
This step is optional but Oracle highly recommends it. For more information about this tag, refer to Section 5.4.1, "JSF and the namingContainer JSP Tag." The namingContainer tag is only used with the WLP native JSF portlet bridge. For more information on the namingContainer component see "Client ID Namespacing with the WLP NamingContainer" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
The following section contains more information about the namingContainer JSP tag.
The purpose of the namingContainer JSP tag is to ensure generation of unique IDs on a page. The NamingContainer component provides a WLP-integrated naming container and exposes a naming container instance that can be accessed through an EL expression for use in custom id rewriting in backing beans or input to other components.
Note:
The namingContainer tag is only used with the WLP native JSF portlet bridge. For more information on the namingContainer component see "Client ID Namespacing with the WLP NamingContainer" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
Note:
For the default JSR 329 JSF portlet bridge and the JSR 301 portlet bridge, their respective specifications define mechanisms for accessing the naming container. Refer to those specifications for more information.
Currently the JSF architecture does not provide an explicit hooking mechanism to override default component ID generation. JSF uses a hierarchical namespace for components on a page, and JSF automatically generates unique IDs for the components on a page; however, because JSF is not "aware" of the portal, it might generate non-unique component IDs on a page. For simple forms you would not likely experience this problem, but if you use JavaScript on a page and non-unique IDs are generated, the JavaScript might target the wrong component.
For more detail on the implementation of JSF in WebLogic Portal, refer to the Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal for the package com.bea.portlet.adapter.faces.
You can add a project facet to your EAR project or portal web project at any time. For example, in your portal web project you might originally have selected not to install the facet that enables visitor tools, but you might decide later that you want to use this feature.
To add a facet to an existing EAR project or portal web project, follow these steps:
Right-click the EAR project or portal web project to which you want to add a facet, and select Properties.
The Properties dialog displays; an example is shown in Figure 5-1.
Figure 5-1 Example Properties Dialog Displaying Installed Project Facets
Expand the Project Facet nodes in the tree as needed and select the check boxes for any facets that you want to add, or deselect the ones you want to remove.
Figure 5-2 shows an example for a typical portal web project with Collaboration Portlets selected for addition.
Figure 5-2 Example Add/Remove Project Facets Dialog with Collaboration Portlets Selected
Click Finish.
The facets are added and then displayed in the list of facets in the Properties dialog.
Click OK to close the dialog. The new facets are now available to your project.
A recommended method of integrating a web application's functionality into a portal is to incorporate the application into Java page flow portlets, but this implementation could be difficult if the application is not based on the MVC architecture, Java, or Struts. In these cases you can continue to host the application externally from the portal project but surface its content within WebLogic Portal.
The alternative implementations generally rely on a JSP portlet acting as a sort of proxy, which allows the existing web application to remain intact. Some possible implementations for JSP "proxy" portlets include:
Creating a JSP portlet that is identical to the home page of the web application, but altering each link to use JavaScript that pops up a new browser window. This allows you to leverage the existing application while providing a way to interact with the portal.
Using an IFRAME in the portlet to contain the web application. The internal frame acts as an embedded browser window that the user interacts with independently of the parent browser.
Using the WLP portlet clipping feature.
Web Services for Remote Portlets (WSRP) provides another alternative implementation, but this implementation requires the legacy server to support SOAP and WSDL, and works best with existing applications designed using MVC.
WebLogic Portal supplies a utility JSP tag called uriContent that you can use to retrieve an HTTP response document from a given URI. The browser portlet uses the uriContent tag (Content URL) to surface an external web application in a portal, using a portlet. For more information about the browser portlet, refer to the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.
|
 Copyright © 2010, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|