Develop Java portlets

Use iViews to render data from a remote database

Maybe you believe the hype: corporate portals belong to the next wave of strategic enterprise applications that will transform the way companies do business. Or maybe you agree with a recent advertisement that proffered the following strategic analysis: portal schmortal. Either way, corporate portals are winning mind share in the boardroom with their promise of frontend, enterprisewide integration. For most corporate portals, this promise is fulfilled by custom-developed application components based on Sun Microsystems' Java 2 Platform, Enterprise Edition (J2EE) Web application model. These portal components—portlets—ultimately deliver business content to users' browsers.

Hands-on portlet development

To date, most vendors have constructed their own APIs and frameworks for portlet development. At the same time, Java Specification Request (JSR) 168 strives to produce a common specification that would enable portlet interoperability between corporate portal applications from different vendors. You can review the details of JSR 168 at the Java Community Process (JCP) Website (see Resources). The specification's public release is planned for April 2003. Until then, the best sources for Java developers to gain initial experience with portlet development are portal vendors' proprietary APIs.

German software vendor SAP offers an excellent place to start. The SAP offering includes a comprehensive development, deployment, and runtime environment—all of which fit on a modest-sized computer. All of the necessary software is free to download, either from open source projects or directly from SAP. In addition to its ready availability and no-cost startup, SAP has also produced a robust API and development framework for dynamic portlets, which SAP calls iViews.

iViews: Content in the SAP Enterprise Portal

The content in a portlet can include anything from a simple Webpage to a personalized view of complex data in multiple systems. Portals usually don't pretend to offer true backend integration without the support of a complete enterprise application integration (EAI) suite, but they instead enable an integrated view—an iView—of backend information for the user.

In this article's example, I will build a portal component iView that queries a remote database and renders the result within SAP's proprietary framework. Even though it is a simplified version of a customer-specific solution, the example is still relatively complex. While extremely basic HelloWorld and stock ticker examples might provide a simpler start, they ultimately fail to utilize the full range of functionality offered by vendors' APIs. The example iView pictured in Figure 1 displays a list of just-in-time (JIT) electronic data interchange (EDI) calls from the automotive industry.

Figure 1. Example iView of JIT EDI calls from MySQL

The download bundle (see Resources) that accompanies this article includes the source code for the JIT iView, as well as some additional resources to support the development process.

I used the open source MySQL database server to store the data for the example, but you can work with any Java Database Connectivity (JDBC)-compliant database and driver. The name of the database I created is edi_db, and it contains a single table, jit_calls. While this article does not describe the process to install and set up the example database, the download bundle includes a SQL flat file jit_calls.sql with dummy data, which you can import into MySQL.

Access to the MySQL database system requires authentication with a user ID and password; I created the user mysql_remote with password gcoe. I also assigned a password to the default ODBC@localhost user to eliminate anonymous login. These configuration details are summarized in the sidebar, "MySQL Information for the JIT iView."

The complete DOS output of table jit_calls, including the full authentication of user mysql_remote, is depicted in Figure 2.

Figure 2. Example data from MySQL. Click on thumbnail to view full-size image.

You have probably worked through the traditional JDBC example covered in Sun's The Java Tutorial (see Resources). The standard construct accesses a database by passing the user ID and password as clear text in the SQL getConnection() method:

getConnection("jdbc:mysql:///"edi_db","mysql_remote","gcoe");

Instead of explicitly passing the user ID and password, though, the JIT iView employs the SAP portal service for user management, which enables authenticated users in the portal to access remote data sources via single sign-on (SSO). By means of a concept called user mapping, the user in the portal maps to a user ID and password from the backend system. When the portal user accesses the back end, the mapped credentials are sent for authentication without prompting for additional login information. In the example, I map a default user from the portal to the user mysql_remote in the MySQL database system.

Set up the portal landscape

To prepare the portal environment for SSO access to a remote system, you must complete the following three activities:

  • Set up the development environment
  • Register the backend system in the landscape settings for the portal
  • Perform user mapping

Set up the development environment

SAP provides the Portal Development Kit (PDK) as a separate, offline development and deployment platform for Java iViews. The PDK's development environment is based on the Java 2 SDK, and its deployment environment is implemented as a Web component inside an Apache Tomcat servlet container. A set of custom APIs provides a development framework for portal components, and global services enable additional functionality, including access to remote data sources, user management, and easy data rendering in the portal. Java developers who don't have immediate access to a full SAP Enterprise Portal (EP) implementation can also use the PDK to deploy and test their iViews.

SAP also offers add-on wizards for Borland's JBuilder and the open source Eclipse platform. The wizards work to integrate a fully featured IDE with the PDK platform. SAP, however, plans to discontinue support for JBuilder with the portal's next release. For simple portal component projects, I prefer to use Apache Ant as the build tool for my portlet application archives.

After an initial registration, the PDK is freely available from the SAP iViewStudio Webpage (see Resources). PDK installation inside Tomcat 3.3x or 4.x is described in SAP's "Installation and Administration Guide." When you start Tomcat, the iView Runtime for Java (IRJ) deploys as a Java Web component, and it ultimately serves as the PDK platform. After deployment, the default start page for the PDK is at http://localhost:8080/irj/servlet/prt/portal/, and you can log in with the default user ID wp and password wpuser. To facilitate testing, the PDK's styles and page navigation structure mirror that of a productive SAP EP. Figure 3 depicts the PDK's dancing Welcome page.

Figure 3. The SAP PDK dancing welcome. Click on thumbnail to view full-size image.

As part of the download bundle, I created a custom JavaWorld tab for the PDK. Install the tab by copying the folder {7} JW Tools and all its contents to the directory structure under tomcat\webapps\irj\WEB-INF\plugins\portal\content\. When you refresh the PDK browser, you should have a new tab on the top-level navigation bar. I introduce this tab's components when we first use them in the next section.

Register the backend system

Once the PDK is installed and configured with the custom JavaWorld tab, you must register the MySQL backend system as a portal data source. Information about the different data sources in the portal landscape is maintained in the Systems.xml file, which is located in the tomcat\webapps\irj\WEB-INF\plugins\portal\services\landscape\xml\ folder. By default, the XML file contains many standard SAP entries, and you must add a new system tag for MySQL. (All of the required entries for the JIT iView example are included in the Systems.xml file that is part of the download bundle.) The System name parameter is freely definable, but you must include the UserMappingType attribute exactly as in the example. The attribute value registers the system with the portal's user management service to enable user mapping:

<System name="MYSQL">
    <Title>
        <pcd:TitleText language="EN">MySQL</pcd:TitleText>
    </Title>
    <Accessability value="true"/>
    <Attributes>
        <pcd:Attribute name="UserMappingType" value="admin,user"/>
    </Attributes>
</System>

After changing the default Systems.xml file, you must upload the modified file to the portal server's persistent layer (the Portal Content Directory (PCD)). Move to the JW Tools tab in the PDK, where the entry page displays the System Landscape Cockpit. The Landscape Upload Status should report that Systems.xml is not uploaded, as shown in Figure 4.

Figure 4. Landscape file Systems.xml is not uploaded

Click on the Upload to Portal button to open the PCD Upload tool on the right side of the cockpit.

Figure 5. The PCD Upload tool in the Systems Landscape Cockpit

Browse to your modified Systems.xml file and upload it (Figure 5). The resulting message should read, "Upload successful: File Systems.xml uploaded to PCD location: /system/landscape/Systems.xml." Refresh the Landscape Upload Status to compare the PCD persistence layer with the IRJ, as shown in Figure 6.

Figure 6. Refresh the System Landscape Service

If the PCD and IRJ are not synchronized, click the Refresh Landscape Service button. The Landscape Upload Status should now report that Systems.xml is uploaded (Figure 7), and it should not report any discrepancies.

Figure 7. Synchronize the persistence layer (PCD) with the runtime (IRJ)

Perform user mapping

As described above, user mapping enables an authenticated portal user to access a remote data source via single sign-on. To assign the mapping, move to the UserMappingAdmin page under the JW Tools tab, as shown in Figure 8.

Figure 8. Map the PDK user to the MySQL remote data source. Click on thumbnail to view full-size image.

First change the drop-down list to Users and search for the default portal user named wp. As a result of the modifications in the Systems.xml landscape file, the remote system MySQL should be visible via the drop-down list in the Data Source Settings section. Make sure your data source is selected and click the Edit link alongside the wp user. Now you can enter the user ID and password from the MySQL system. For me, the user ID is mysql_remote with password gcoe. Finally, save the entry. You should receive the message, "Logon data was saved," and a green check should appear to the left of the wp user in the table.

Build the portal component

Once the portal user is mapped to the MySQL user, we can look at the application architecture of the portal component for the JIT iView. For this basic portlet, the portal component project consists of three general types of files:

  • Ant build files
  • Portal component profiles
  • Portal component application files

Usually, Web resources such as JavaServer Pages (JSP) technology are used to display portlets, but the JIT example uses a special portal service from SAP that automates the rendering process. JavaBeans components can also function as helper files that pass data within the portlet's session. More robust and complex portal components can integrate the full gamut of J2EE technologies, and many customers are currently working with iViews that incorporate Enterprise JavaBeans (EJB) components in particular.

The portal component's overall structure can best be viewed at the project file structure level, as in Figure 9.

Figure 9. Portal component project directory file structure

The download bundle includes a development project folder called MySqlProject, which contains all of the Java source files for the example. I describe all of the project files in the sections below.

Ant build files

Since I use Ant instead of JBuilder or Eclipse, I must manually maintain the required project build files in a separate folder called AntProject. The Ant tool serves to compile the Java source and build the application archive file based on the instruction set in the build.xml file. The resulting application archive, the portal archive (PAR) file, is deployed to the IRJ to expose the component in the portal. The build.xml for this project relies on two additional files, which are also saved in the AntProject folder:

  • The libraries.properties file contains a parameter named path.element, which provides Ant with the required CLASSPATH information for the Java compiler. You do not need to modify the downloaded file.
  • You do, however, need to maintain the global.properties file with values specific to your PDK environment. The root installation directory of the Tomcat servlet container must be set for the attribute portal_lib_root. The provided values for the other two attributes, par.name and jar.name, do not need to change.

Portal component profiles

At runtime, the iView is triggered and controlled by parameters in the portal component's profile properties files. These files are all saved in the project's private\profiles\ folder. A profile named default.properties is required and contains properties that apply to every portal component in the archive, as multiple portal components can be delivered in a single PAR. The default profile for the example only requires a single parameter:

1 2 Page
Join the discussion
Be the first to comment on this article. Our Commenting Policies
See more