IFrame Consumer Technique

Using an IFrame to insert a new feature into a Web page has become a common technique across the Internet. Many mashup sites rely on this approach, for example. The concept is simple: A developer edits an existing page, and then adds an <iframe> tag without disturbing the rest of the page. IFrames render within their own isolated frame, and so they cannot harm the surrounding page. For legacy Web applications that are risky to update, an IFrame is the right approach.

The IFrame tag is very easy to understand. The developer need only specify the source of the rendered content, and optionally some size and scrolling attributes:

The process of using the IFrame to render an Adrenaline portlet is easy. Follow these steps:

Obtain the URL to the portlet. This can be determined by looking into the producer Web application, and creating a URL to the desired .portlet file—for example,
http://[host]:[port]/[webappContextPath]/[relative path]/[portletName].portlet.

Open the consumer Web page in an editor.

Insert the <iframe> tag into the page where the portlet should be rendered, using the URL to the portlet as the source. Use the example shown above as a reference.

Ajax Snippet Consumer Technique

While using an IFrame to insert a portlet into a page is an effective technique, at times it is desirable to render a portlet inline onto a page. In certain cases, the portlet may wish to use JavaScript to interact with elements of the enclosing page. Also, rendering the portlet inline allows the portlet to consume as much screen area as it needs without the need for scrollbars.

With the Ajax consumer technique, all clicks within the portlet are routed to the producer asynchronously, and the returned HTML is inserted into the page. Therefore, the enclosing page is not refreshed for portlet events, which allows the portlet to operate independently without interfering with the application. Multiple Ajax rendered portlets may be used on the same page as long as each instance is given a unique id attribute.

The following is the snippet to use when rendering an Adrenaline portlet via Ajax. Notice how
div tags define containers that control different pieces of the rendered portlet.

The key to the Ajax snippet is the call to
bea.netuix.ajax.updateContents() function. It is this function that will ultimately render the HTML contents from the portlet into the
_cmbrowser div tag. The portlet is accessed via a URL to the .portlet file, which will trigger a servlet to render that portlet. The links and form actions in the rendered HTML will be correctly rewritten to submit through the XMLHttpRequest and will not cause a page refresh. The JavaScript code that powers Adrenaline is found within the file
async.js, which is referenced at the top of the snippet.

Note that there is a significant limitation for using this approach. Browsers have a security feature that will not allow the portlet to come from a server in a different IP domain than the outer HTML page. Therefore, this approach will work only when the portlet and the Web application are hosted by the same organization.

To use this snippet to surface your portlet in your own Web application, follow these steps:

Copy the above snippet into an HTML page in your Web application. You will need to remove the preceding line numbers.

Search for the text
cmbrowser within the snippet, and replace that text with a unique id for your portlet on the page.

Obtain the URL to the WebLogic Server Web application in which your Adrenaline portlet is deployed. This will likely be a URL of the form
http://[host]:[port]/[webappContextPath]

Update the URL in snippet line 0 with the portlet Web application URL, as in
/[webappContextPath]/framework/features/js/async.js.

Obtain the relative path of the portlet descriptor within the WebLogic Server Web application, as in
/[relative path]/[portletName].portlet.

Update the URL in snippet line 12 with the portlet Web application URL and the relative path to the portlet, as in
http://[host]:[port]/[webappContextPath]/[relative path]/[portletName].portlet?[keep the existing parameters shown above].

Ajax JSP Tag Consumer Technique

Adrenaline offers a JSP tag that may be embedded into any JSP page in a WebLogic Server Web application that has Adrenaline installed. The portlet to which it refers must also be deployed in the same Web application (for a local portlet) or it can be deployed remotely if using WSRP. Ultimately, Adrenaline must have a WebLogic Portal .portlet descriptor in the Web application for the portlet that is to be exposed.

To surface a portlet in a JSP page, the new Adrenaline
portalFacet tag is inserted into the JSP page:

where the Web application has a file called
sample.portlet deployed in the
portlets subdirectory. The
label tag attribute must be unique to all
portalFacet tags on the page as it identifies the portlet instance. At runtime, the
portalFacet tag will render the specified portlet on the page using the Ajax approach that has already been described. You may include multiple portlets on a single page by inserting multiple
portalFacet tags with unique
label attributes.

Configuring a WebLogic Server Web Application as a Portlet Producer

After reviewing the three techniques for consuming portlets into any Web application, it is important to focus on how to create the producer and its portlets. For customers with existing WebLogic Portal 9.2 Web applications, there is no work to be done. Any WebLogic Portal 9.2 Web application is automatically an Adrenaline portlet producer. Any portlet deployed within WebLogic Portal 9.2 can instantly be consumed using the three techniques above without any configuration or additional work. Customers deploying portlets on WebLogic Portal 8.1 will need to upgrade to version 9.2 to take advantage of this capability.

For WebLogic Server customers that are not currently building portlets on WebLogic Portal, it is a straightforward effort to take advantage of Adrenaline. The appendix contains a small set of steps to add Adrenaline to any WebLogic Server 9.2 Web application. However, note that there are three major prerequisites for building an Adrenaline portlet producer Web application:

Downloading WebLogic Platform 9.2 provides WebLogic Server and a development license for WebLogic Portal. To configure the Adrenaline libraries, it is easiest to use WebLogic Workshop for WebLogic Platform following the steps in Appendix A of this article.

Adrenaline Considerations

Adrenaline will work with almost any portlet developed and deployed within WebLogic Portal 9.2. No special steps need to be taken to make a portlet Adrenaline compatible. However, several specific issues can affect the usability of a portlet through Adrenaline.

Why use Adrenaline portlets on the producer?

The IFrame technique could be accomplished without Adrenaline portlets; IFrames can consume any HTML source. You could add an IFrame to a legacy application that consumes
www.bea.com, for example. In a similar way, using an Ajax toolkit, you can replicate the Ajax Snippet technique without Adrenaline. If this is true, why should you use Adrenaline portlets on the producer side?

What follows are the primary reasons for developing portlets on the producer side instead of plain Web applications:

Components, not pages: most Web applications would not fit well within a portlet-sized IFrame. What is needed are user interface components to consume, not entire pages.

Inter-Portlet Communication

Inter-Portlet Communication (IPC) allows for one portlet to communicate with another portlet within a portal. In some cases, this feature is used by portlet writers to allow multiple portlets to collaborate. The Master-Detail pattern formalizes this idea by defining a Master portlet and a Detail portlet that appear on a single portal page. The Master portlet usually contains a list of topics, that when one is clicked, causes the Detail portlet to update and display the clicked content.

Because Adrenaline surfaces a single portlet on a consumer Web page, the Master-Detail pattern is not supported. Portlets that rely on IPC therefore should not be consumed using Adrenaline.

Authentication

When using any of the consumer techniques, it is always possible for the consumer and producer to be in the same Web application. For the
portalFacet tag, this is actually required. There is an advantage with deploying in this manner. In this configuration, if a user authenticates with either the consumer Web page or the producer portlet, the authentication is automatically shared. This is due to the fact that the user is operating entirely within the boundaries of a single Web application.

When using the IFrame Consumer or Ajax Consumer techniques, it is common for the consumer and producer to be part of different Web applications. While this is a flexible approach, it is important to understand how this configuration affects authentication. Because the consumer and producer are in different Web applications, by default authentication will not be shared. Therefore, the user will be required to authenticate twice—once with the consumer and once with the producer.

This problem is not unique to Adrenaline. Forcing users to authenticate with many Web applications is commonly seen within the enterprise. To solve this issue, Single Sign-On (SSO) solutions have become widely deployed within the enterprise. SSO solutions commonly use cookies to maintain user identity across Web sites. As long as both consumer and producer are in the same network domain, these SSO solutions will work without issue with Adrenaline.

Adrenaline complements WSRP

Adrenaline is not the first portlet technology to allow consumers to surface remote producer portlets. A standard called Web Service for Remote portlets (WSRP) already exists to provide exactly this capability. WebLogic Portal contains the industry-leading implementation of WSRP, and continues to enhance its implementation. WSRP is an advanced technology that contains many features useful for creating federated portals. Features such as shared authenticated, inter-portlet communication, and interceptors make the WebLogic Portal WSRP solution very powerful.

BEA recommends WSRP as the primary portlet federation technology. However, in cases where WSRP is not available on the consumer side, Adrenaline is a great substitute. Fortunately, with WebLogic Portal, the same portlet can be deployed once on the producer, and then can be surfaced to some consumers using Adrenaline and others with WSRP. In this way, Adrenaline and WSRP are complementary, not competing technologies.

Conclusion

Adrenaline dramatically expands the reach and flexibility of portlet technology. Adrenaline can breathe life into legacy applications, and promotes the reuse of portlet user interface components throughout the enterprise. For WebLogic Portal customers, this new technology comes for free and enhances the return on existing investment in portlet development. For all others, Adrenaline offers a compelling reason to adopt WebLogic portlet technology.

This appendix describes the list of steps to add Adrenaline to a WebLogic Server Web application. You must add certain WebLogic Portal components to the Web application using Workshop for WebLogic Platform 9.2, following these steps:

Ensure that the license.bea file in your BEA home folder contains a valid key for PortalFramework.

Create a WebLogic Server domain if one is not already created using the Domain Configuration Wizard. The domain must include support for the WebLogic Workshop product. Rerun the Domain Configuration Wizard, and then choose to
Extend the domain to verify the configuration.

Launch Workshop for WebLogic Platform.

Open an existing Workspace or create a new Workspace.

Create an
Enterprise Application Project if one is not already created.
File->New->Project...

Create a
Dynamic Web Project if one is not already created.
File->New->Project...

Select the Enterprise Application Project in the Navigator pane.

In the Project menu, select the Properties item.

On the Properties dialog, select the J2EE Module Dependencies option in the left pane.

Ensure that the Web Project has a checkmark to indicate that it is a component of the Enterprise Application.

Select the Web Project in the Navigator pane.

In the Project menu, select the Properties item.

On the Properties dialog, select the Project Facets option in the left pane.

Click the Add/Remove Project Facets button.

Expand the WebLogic Portal node in the tree.

Select the
Portal Framework and
Portal Framework Struts facets.

To offer WSRP portlets, you must also add the
WSRP Producer and
Portal Customizations Framework facets.

Click Finish.

Configure the application to use the WebLogic Server domain created above by using the Servers view; see this page for more information.