Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Use IFrame, WDSC to build and deploy a portal subfile Web application

WDSC and the IFrame portlet make it easy to create a simple Web application and deploy it in a portal.

You've read about Web portals: WebSphere, Domino (from IBM) and Jetspeed (from the Apache Software Foundation). You want to know how to create a simple Web application and deploy it in a portal. Good news! IBM's WebSphere Development Studio Client for iSeries (WDSC) and the IFrame portlet make that easy. This article summarizes how to build a simple subfile application for the Web quickly and deploy it on any Web portal. (Jetspeed is the portal I used here because it's no-charge software from Apache Software Foundation.)

What is a portlet?

Similar to the concept of Java servlet (a Java application designed to run in a Web application server that implements a client/server request/response model), a portlet implements a standard interface for an application designed to run in a portal server. Many portal servers, including WebSphere and Jetspeed, support running portlets.

Jim Mason

A portlet is an active application component within a portal page that implements the Portlet interface:

  • Like a servlet, it receives input and returns a response.
  • The method getContent with input and output data is called by every request to a portlet.
  • Input is a RunData object that contains the HTTP request and other information.
  • Output is an Element Construction Set (ECS) object that is turned into an HTML response.
  • It can be built with servlets or JSP to get content for a portlet.

The portlet interface defines three methods for a portlet to implement:

  1. init: This method is called once when the portlet is loaded by the portal server. Usually, expensive operations done once (like a database connection) are done here.
  2. getContent: This method is called every time a portal user requests a portlet. This is the "run" method that returns a ConcreteElement.
  3. destroy: This method is always called before the portlet is destroyed (unloaded in the portlet container) so you can ensure critical operations like closing a database connection are completed normally.

Runs in a portlet framework on a portal page

  • PortletController runs multiple portlets in a page.
  • PortletControl renders title and body of portlet.
  • Portlet Skins are like cascading style sheets.

Portlets can be implemented as subclasses of AbstractInstancePortlet or another, more specialized portlet framework class. Some of the other supplied classes are better choices for building JSP portlets, file serving portlets and more.

A portlet is configured with a portlet catalog registry fragment file (for example: ebtnow-portlets.xreg). This XML file has the properties the instant the portlet needs to load your Web application into a portlet window on a portal page (the name of the class, the size of the window, etc.).

At runtime, the portal server combines all of the registry fragment files into a single portlet catalog. Administrators and, in some cases, users can configure portal pages visually by selecting a portlet from the catalog and placing it on the page.

What is the IFrame portlet?

IBM created an IFrame portlet to run EXISTING Web applications (servlets and JSPs) in a portlet environment. It can eliminate the need to develop custom portlets to run existing Web applications. IBM also made a great contribution by donating the IFrame portlet to the Apache Software Foundation. Any portal server can use the open-source Apache frameworks to run an IFrame portlet.

The IFrame portlet is configured with a portlet catalog registry fragment file (for example: ebtnow-portlets.xreg).

Our employee phonebook application

The Database application wizard in WDSC generates the Web database application. It is simple but typical of a useful Web database application for a simple Employee phonebook. The application lets a user do the following:

  • Search the Employee table by last name.
  • Browse and select a single employee record from the Employee result table.
  • Display details on a single employee.
  • Navigate back and forth through these three steps.

Figure 1: Search employees by last name -- prompt for a last name to search for in the phone book
Figure 2: Subfile list of employee phone numbers -- browse and select a single employee record in the result table
Our Web database application in action

Summary to create a simple Web subfile application in WDSC

I assume your familiar with WDSC, have it installed and have used it already.

Here we'll build a very simple subfile application for the Web that accesses an employee master file to create an employee phone book that can be embedded as a portlet on a home page for a company.

We'll use the WDSC data perspective and the SQL statement wizard to create an SQL SELECT statement. Then we'll use the WDSC Web perspective and the Web database pages wizard to create the Web subfile application using our SQL SELECT statement.

Basic setup steps to build Java Web applications in WDSC would normally include:

  • Create a database model for the iSeries data library

Steps to create the Web database application:

  • Create an SQL query object for the Employee table.
  • Generate the database application using the Database application wizard.

The Web database application uses the IBM data access beans and JDBC to access the iSeries database. The concepts are similar to using files in a traditional program:

  • You connect to a database -- here using a JDBC Connection or opening a data source.
  • You position to data in a table -- here using a SELECT statement with a WHERE clause.
  • You scroll forward or backward a page at a time to locate a specific record.
  • You select a specific record for detail viewing.

A key difference from RPG: You can use different JDBC drivers to connect to many different databases. RPG can use only the local file system on an iSeries by comparison. JDBC drivers are supplied by database vendors to allow your Java application to connect to a database, read, write, update and delete data. IBM supplies two JDBC drivers for the iSeries: a native JDBC driver included with the iSeries JSDK (57xx-JV1) and the a portable JDBC driver included with the Java Toolbox (included in WDSC) and on the iSeries (57xx-JC1).

One strength of this wizard is you can use ANY JDBC driver, not just the iSeries drivers, if you add the appropriate jar file containing the database driver into your WDSC project. In fact, I've connected to almost every type of data using different JDBC drivers: iSeries DB2, DB2 Common Servers (Windows, Linux, AIX), mainframe, Domino, Microsoft Excel, Access and SQL Server and MySQL, to name a few. In short, I can use the different JDBC drivers to talk to any relational data source.

You can also use the "Run on Server" option on the generated HTML input page for this phonebook to run the application in WDSC for testing WITHOUT setting up ANY external servers. Look what happened with ONE click:

  • The test WebSphere application server configuration and instance is created in the workbench.
  • The test WebSphere server is started.
  • The application is published.
  • A Web browser is opened.
  • Your input form is invoked in a test browser.

Exporting the application to Jetspeed

Once the Web subfile application has been created in WDSC, we can export it in two steps to run in Jetspeed:

  1. Select the Web project in WDSC > right button menu > Export > Name the .war file (Web Application Archive) and location to export > click Finish
  2. Copy the generated .war file to the Tomcat Webapps directory. For example, ctp25.war file in c:temp could be copied to: c:tomcatWebapps.

Configuring the Web application as a portlet in Jetspeed

For our employee phonebook application, I created an XML portlet registry fragment file that defines the URL to access the phonebook from our Web application as well as the size of the portlet frame for the portal page to run this portlet. I used just Microsoft Wordpad to edit this as a simple text file. I saved it as ebtnow-demo.xreg. Then I copied this file into the Jetspeed configuration directory. For my setup, c:tomcatWebappsjetspeedWeb-Infconf. Jetspeed will automatically use this fragment to build the portlet catalog when it starts up.

In addition to the portlet name, description and URL for the phonebook application, note the parameters that set the size of the portlet frame on the page:

<?xml version="1.0" encoding="UTF-8"?>
 <portlet-entry name="EmpPhonebook1" hidden="false" type="ref"
 parent="IFramePortlet" application="false">
 <security-ref parent="default"/>
 <title>Employee Phonebook1</title>
 <description>Employee Phone book with search.</description>
 <parameter name="source"
 hidden="false" cachedOnName="true" cachedOnValue="true"/>
 <parameter name="align" value="left" hidden="false"
 cachedOnName="true" cachedOnValue="true"/>
 <parameter name="width" value="400" hidden="false"
 cachedOnName="true" cachedOnValue="true"/>
 <parameter name="height" value="350" hidden="false"
 cachedOnName="true" cachedOnValue="true">
 <media-type ref="html"/>
 <url cachedOnURL="true"/>
 <category group="Jetspeed">wdsc</category>

Running the Web subfile application in Jetspeed portal

I'll start Tomcat running, then log on to the Jetspeed portal and add the portlet to my home page. At that point, I'll be able to access the portlet from my home page on the portal.

Steps to setup and run the portlet on a page:

  1. Start Tomcat running in a command window:
    For my setup, c:tomcatbinstartup
  2. Access the Jetspeed home page in a Web browser:
    For my setup: http://localhost:8080/jetspeed/index.jsp
  3. I took the option in the upper right to create a new account for a user.
  4. I took the option in the upper right to customize HTML.
  5. I selected the only page I had (Home) for edit.
  6. On the customize pane shown below, I clicked "Add Portlet" to add the phonebook portlet.
  7. From the portlet catalog list shown below, I clicked "Employee Phonebook 1" to add it.
  8. Then I hit in sequence: "Apply", "Save and Apply" and "Apply".

Figure 3: Customize pane
Figure 4: Add portlet from catalog list

Now I'm looking at the resulting portal page with the employee phonebook added. I just typed a last name to start my search with and this is the result:

Figure 5: Portal page with employee phonebook added


As you can see, it was very easy to build a Web subfile application with WDSC. No Java coding needed. It was also very easy to deploy that Web application and run it in Jetspeed thanks to IBM's IFrame portlet.

For more information on portals, see the following:

Let me know what your preferred portal solution is, why it's the right one for your company and how it's paid off. You can reach me at jemason@ebt-now.com.


About the author: ebt-now


  • Portal servers improve Web user satisfaction
    Looking to do more with your Web site? Try portal servers. They provide a central, organized Web access point for a group of users. They can be a flexible, effective "front door" to your Web applications, Web content and Web site. And they provide the right content, services and tools to a specific group of users to make it easy to work over the Web.
  • Getting Jetspeed up and running
    Recently a user was trying to run Jetspeed on the iSeries, but he kept getting errors. What was going on? Web development expert Jim Mason had an idea for figuring it out.
  • Tame the information tiger with a corporate portal
    Have trouble finding that report from last February? Want to check overnight sales figures from home? Are your systems an information tiger? A corporate portal may be the way to get that tiger by the tail.

Jim Mason, president of , is an iSeries WebSphere engineer. ebt-now provides iSeries WebSphere, WebFacing project management, engineering, development and training services.

Dig Deeper on Web Tools

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.