Consuming a JSR-168 Calculator Portlet in a Java Server Faces application using Oracle WebCenter

Oracle WebCenter allows JSF (including ADF Faces) applications to consume Portlets. That means that our own application can pretend to be a portal too. Anywhere in the JSF page, we can embed a Portlet and even integrate that Portlet with our page – exchanging data, synchronizing views. The WebCenter Framework takes care of merging together the rendered content from the JSF page and the embedded Portlets as well as the synchronization of the page and its Portlets.

In theory, this could mean a lot. Services, so far typically considered to be programmatic, face-less entities, can be provided complete with a User Interface. Remote Reusable Components can be merged into our web applications. Standard infrastructures such as Content Management Systems, BPEL Engines and ERP/CRM software provide Portlets in addition to programmatic interfaces. These portlets can be integrated into custom applications (as well as Portals) to provide insight in and even manipulation on top of those central systems. We also get the ability to leverage the functionality available as Portlet in our applications. In addition to JavaScript libraries, Java jars, Custom Tag Libraries and JSF Components, we have another level of reusable component. One that can be offered over the internet, or one that can be deployed locally in our enterprise and use throughout the organization.

However, this section started with the phrase ‘in theory’. Does it actually work like that? Well,
we cannot embed just any JSR-168 Portlet in our JSF/ADF Faces pages. And not just in any page in any application either. See the WebCenter Developer’s Guide 4.2 Building WebCenter Application-Enabled Pages in Oracle JDeveloper with Oracle ADF  (http://download-east.oracle.com/docs/cd/B32110_01/webcenter.1013/b31074/jpsdg_pages.htm#CJAJBEFF ) for details. One (simple) rule for the Portlet consuming pages is: Create WebCenter application pages as JSP documents (jspx) rather than JSP pages (jsp).

Before you can add a portlet to a WebCenter application, you must register the portlet’s producer with the application. Oracle JDeveloper provides two producer registration wizards: the WSRP Producer Registration Wizard and the Oracle PDK-Java Producer Registration Wizard. Oracle WebCenter Framework supports both WSRP 1.0 and WSRP 2.0 producers. WSRP 2.0 support is for a preliminary (that is, preproduction) version of WSRP 2.0. Preliminary support is provided to accommodate the fact that the WSRP 2.0 standard was not finalized when Oracle WebCenter Framework was released.

This emerging standard, among others, provides support for inter-portlet communication and export or import of portlet customizations. This means that you can leverage the benefits of WSRP 2.0 while building standards-based JSR 168 portlets.
 
In order to be able to register the WSRP Producer with an JSF Application, there has to be one of course. That means that the Portlets we want to consume have to be deployed to a WSRP Portlet Container. For most 3rd party portlets, we have to do little extra work over just deploying the EAR fie to a JSR-168 Portal Container. See also WebCenter Developer’s Guide 18.9.3 Deploying  a Third Party JPS-compliant Portlet to OC4J (http://download-east.oracle.com/docs/cd/B32110_01/webcenter.1013/b31074/jpsdg_java_intro.htm#BHCCBABA ).

In this article I will try to deploy the JBoss Calculator Portlet to the Oracle WSRP Container and subsequently consume that Portlet in an ordinary ADF Faces Web Application. We will see the various steps that I had to perform to get this up and running.
 
The Calculator Portlet is available from the PortletSwap Portlet Catalog at http://labs.jboss.com/portal/portletswap/portlets_misc.html . It can be downloaded in a zip-file, that contains various war’s and configuration files for the JBoss Portal. However, the Portlet is JSR-168 compliant and as such can be deployed to the WebCenter Portlet Container. Supposedly.

Deploying the JBoss Calculator Portlet to our WebCenter WSRP Portlet Container 

The steps:

1. Download the Zip file and extract to a temporary directory, say c:\temp\CalculatorPortlet.

2. Open JDeveloper 10.1.3.2.

3. Create a new application, CalculatorPortletProducer.
 
4. Create an empty project: CalculatorPortlet
 
5. Select the project node and from the New Gallery, select Standards-based Java Portlet (JSR-168)
 

The Java Portlet Wizard opens.
 
We can safely accept all defaults. The wizard will generate a number of files that we will replace later on with files from the Zip-file downloaded from JBoss PortletSwap.

6. Go to the Windows Explorer and open the folder C:\temp\CalculatorPortlet\CalcPortlet\src\resources\calcportlet-war_24\WEB-INF. Copy the folders calc and classes and the files portlet.xml and web.xml to the WEB-INF directory of our CalculatorPortlet project. Remove the directory portlet1 under public_html and the contents of the src directory.

7. Return to JDeveloper. Open the Project Properties Editor. Change the Output Directory from ..\CalculatorPortletProducer\CalculatorPortlet\classes
 to  ..\CalculatorPortletProducer\CalculatorPortlet\public_html\WEB-INF\classes
 
Add the JSTL Format 1.0 Tag Library on the Project’s Tag Libraries page.
 

8. Create a Deployment Profile of type WAR for this project. Specify the J2EE Web Context Root as CalculatorPortlet. Press OK.

9. Deploy the Deployment Profile to a running WebCenter OC4J instance, for example the Preconfigured OC4J that comes shipped with JDeveloper 10.1.3.2 or a stand alone instance. 

An important step during the deployment is the creation of the WDSLs for the WSRP application. These files make this Web Application a special one, that can be registered and consumed as WSRP produced Portlet.
 
During deployment, a dialog window (Configure Application) may pop up. Just click OK to continue Deployment.

Once the deployment is complete, we can turn our attention to the OC4J Enterprise Manager Console, to check out the Portlet and find the URL for the WSRP Portlet Producer.

11. Open the Enterprise Manager Console.  We can see our Portlet Application: CalculatorPortlet2War – the Enterprise Application Name assigned from  the Deployment Profile. Click on the application. Click on the Module CalculatorPortlet2War. Click on the Test Web Module link. Click on Test Web Module. A new browser window opens with an error message: 403 Forbidden, Directory browsing not allowed. Now add info to the URL in the location bar of the browser and press enter. We go to the WSRP Test Page, where we can retrieve the URL for the WSRP WSDL files:
 

At this stage, we assume that the Calculator Portlet that we downloaded from the JBoss PortletSwap Catalog is now available as WSRP compliant Portlet, ready to be consumed in our ADF Faces application
.

Consuming the Calcu
lator Portlet

1. Create a new application in JDeveloper, called SemiPortalApp. Choose the Application Template WebCenter Application.
 
2. Go to the ViewController project. Create a new JSF page.  The JSF JSP wizard opens. Enter a name for the page. Click Next. Click Next on Step 2 – Component Binding. Select the ADF Faces, JSF and ADF Portlet & Customizable Components Tag Libraries in step 3. Click Finish.

Add some ADF Faces components to the page, to clearly demonstrate that this is a very normal ADF Faces page and application.

 
You can run the page to see it is a normal working JSF application.

3. Now we can prepare for consuming the Portlet. We first need to register the WSRP Portlet Producer. Go to the New Gallery, category Portlets, and select the WSRP Producer Registration item.  The Register WSRP Portlet Producer Registration Wizard pops up. Press Next.

Type the name for this Producer: CalculatorPortletProducer and press Next. Now enter the URL for the WSRPv2_WSDL file:

 
 
and press next.

Accept the defaults, press Finish and then press OK.
 
4. The WSRP Portlet Producer that produces our CalculatorPortlet is now registered in our project. As a consequence, a new Component Palette is available when editing our JSF JSP page: CalculatorPortletproducer.
 
5. Drag and drop the Calculator (Portlet) Component from the Component Palette to the Calculator Detail Item component in the ShowOneTab element.

 
6. Run the page. The ADF Faces page is displayed and lo and behold: it has the Portlet in it! So without any programming on my part – though I had to do quite a bit of configuring – I have embedded cool Calculator functionality in my Web Application.
 

Redeploying a more advanced version of the Portlet

1. If we somehow get a more advanced version of the Calculator Portlet, either from the JBoss repository or from our own development staff, we can deploy that to the Portlet Container and automatically the new advanced features are available to all Portlet Consumers in our enterprise: as long as the Portlet Interface (the WSDL) remains unchanged, new implementations are consumed smoothly.

In this case we want to extend the Calculator with the ability to do calculate operand1 to the power operand2.

We add the button labeled ‘^’ to the JSP Calc.jsp:

<td></td>
<td></td>
<td><input type="button" value="^" class="calc-button" onclick="operatorPushed('^');"/></td>

And JavaScript code to perform the calculation:

if (op == '^') {
  document.calc.resultField.value = Math.pow( parseFloat(firstValue),
            parseFloat(document.calc.resultField.value));
}
 

2. Next, we redeploy the Portlet to the Portlet Container.

 
3. Then we can refresh the Web Page that consumes the Portlet, and make use of this cool new feature!

Resources

Download the  JDeveloper 10.1.3.2 Project with the Portlet Producer: CalculatorPortletProducer.zip.