Java portlets are built based on the JSR 168 portlet standard. Sometimes they are packaged and made available to developers in Web Application Archive (WAR) files. This article describes how to use JSR 168 portlets distributed in a WAR file.

Download the author's files associated with this article

Starting with WebLogic Portal 8.1 SP3, there are two new ways to make portlets that are packaged in a WAR file available in the portal. You can either integrate the portlets into an existing Portal Web application or you may choose to keep the portlets in a separate Web application. We will make use of the Portlet Preparer Tool and Web services for Remote Portlets (WSRP) to showcase the two approaches. You should select the approach that best match your needs:

• Single WAR file - Uses the portlet preparer tool to integrate the content of the WAR into an existing project. If you are using a small set of third party portlets and your Portal project, this approach may be best for you.
• Multiple WAR files - Uses WSRP to keep portlets in a separate WAR and reference them from the destination Portal project. If you have a very large project with several third party portlets you may want to consider using this approach.

We will discuss these two approaches in detail below.

Single WAR File - Using the Portlet Preparer Tool
The Portlet Preparer Tool is available as a utility from dev2dev at:
http://dev2dev.bea.com/codelibrary/code/portletpreparer.jsp

The tool creates.portlet files out of JSR168 portlets contained in the WAR file, thereby allowing WebLogic Workshop to import the contents of that file into a Portal Web project. The steps to run the preparer tool are simple and straightforward. There are two options to consider:

• Adding portlets to a new project
• Adding portlets to an existing portal project

Below are the steps for each scenario:

Adding Portlets to a New Project
To import a WAR file containing JSR168 portlets, complete the following steps:

1. Extract portletConverter.jar to a temporary location on your hard drive (In the following instructions this directory will be called <converter-root>).
2. Place your WAR file in <converter-root>.
3. Set the WEBLOGIC_HOME in env.sh or env.bat (depending on your platform).
4. run env.sh or env.bat (depending on your platform).
5. run ant -Dwar.file= (where <war-file-name> is the name of the WAR file).
6. A directory called tempDir under <converter-root> is created.
7. Open WebLogic Workshop and import the tempDir as a portal Web project.

Adding Portlets to an Existing Portal Project
To add portlets to an existing portal Web application, complete the following steps:

1. Complete steps 1-7 above.
2. Copy any necessary classes to the WEB-INF\classes directory and the necessary jars to the WEB-INF\lib directory.
3. Make necessary changes to the web.xml (example: servlet definitions).
4. Add elements to the portlet.xml for each portlet added (these can be copied from the portlet.xml in the tempDir created above).
5. Copy the .portlet files from tempDir\portlets to your Web application
6. Add the portlets to your portal.

Multiple WAR files: Using Web Services for Remote Portlets (WSRP)

Using WSRP you can deploy Java portlets in a separate Web application and reference them from your Portal project. For more details on how WSRP works please visit the links below and download WebLogic Portal 8.1 SP3:

• WSRP Overview: http://dev2dev.bea.com/products/wlportal81/articles/wsrp.jsp
• WebLogic Portal 8.1 SP3 downloads: http://commerce.bea.com/index.jsp

Below is a scenario where the SamplePortal is the main portal from which you create references to portlets in other WARs. This allows you to surface portlets from different WAR files into the SamplePortal.

1. Create a new Portal project, separate from your portal, and follow steps 1-7 from the above section "Adding portlets to a new project".
2. Launch the Portal samples domain and login to the Administration Portal under: http://localhost:7001/portalAppAdmin .
3. Under the Portals tab, click on the Library which is on the left hand side.
4. After the tree expands, click on the Portlet Producers icon.
5. Once the producer resources panel shows up on the right side, click on the "Browse/Add Producers" tab.
6. Under the "Enter Producer to Browse" box, enter: http://localhost:7001/<new portlet war file>/producer?wsdl . Click "OK".
7. At this point you should see a list of producer's properties including available portlets. Click "Add Producer" and fill in the registration fields.
8. After registering, you will be at the "Available Producers" window. From the "Available Producers" box, click the "Register" button. On the dialog box, click "Save".
9. Click the producer that you registered and pick the portlet(s) you want to reference from your portal.

At this point you can click on "All Portlets" in the library tree and you should see the remote portlet you just added. There is also a convenient portlet category, "All Remote Portlets," created under the "Category" drop-down menu in the "Available Portlets" box. Now you can add the remote portlet to a page and make them available to users.

In this scenario the SamplePortal will be playing consumer role while your other Web applications will be playing producer role.

Making the Pluto Test Suite Portlets available in the SamplePortal
Below is an example to highlight the use of portlets in multiple WAR files. The basic idea is to have a set of portlets available in one Web application and allow for the WebLogic Portal in another Web application to make use of these portlets.

In the example below we downloaded the Pluto test portlets (JSR 168 - test suite) from Apache. Next, we created a new Web application, used the portlet tool to import the WAR file, and finally used WSRP to make them available in the Portal Web application.