Develop Java portlets

Use iViews to render data from a remote database

Summary
While the public release of a common API for portlets is still a couple of months away, Java developers can use proprietary APIs from corporate portal vendors to experiment with portlet development. In this article, Carl Vieregger introduces SAP's portlet API and provides a detailed example that renders information from a remote database using single sign-on. He also demonstrates how you can run the example portlet within your own development and deployment environment based on SAP's Portal Development Kit. (3,300 words;February 7, 2003)

Printer-friendly version | Mail this to a friend

aybe 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.

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.

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.

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.

Click on the Upload to Portal button to open the PCD Upload tool on the right side of the 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.

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.

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.

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.

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:

ServicesReference=htmlb,com.sapportals.pct.srv.portaldataviewer,usermanagement


When I introduced the PDK, I explained that a set of global platform services provide additional functionality to portal components at runtime. These services are included in the component via the default profile's ServicesReference parameter. The example iView uses three portal component services:

• HTML Business for Java (HTMLB) is an API and custom tag library to support rendering in the portal, usually via JSP technology
• The Portal Data Viewer (PDV) is an API that automates tabular rendering in the portal and provides standard functionality for the table (e.g., column sorting and view personalization)
• The User Management service enables the portal component to provide dynamic authentication on backend systems

In addition to default.properties, you must have a separate, class-specific profile for each portal component in the project. This properties file's name is the same name as the portal component's implementation class. In our case, the implementation profile is named MapController.properties. The only property required in the class profile for the JIT iView is ClassName, where the value is set to the implementation class's fully defined name.

ClassName=com.ibm.gcoe.mysql.MapController


When the iView executes in the portal, the IRJ first reads the default and class profiles, from which it determines the name of the initial portal component application file (i.e., the implementation class) to load and instantiate automatically.

Portal component application files
SAP has constructed the DynPage development framework as an interface-based model for the application architecture of portal components. The framework is an implementation of the Service to Worker J2EE pattern (see Resources), and it includes both a controller and a dispatcher class. More complex iViews will contain view and helper classes as well. The portal component's Java source files are maintained in the project's private\src\ folder.

The portal component's implementation class is extended from the central abstraction of SAP's portal component API. It serves as the application controller:

public class MapController extends PageProcessorComponent {
  public DynPage getPage() {
    return new MapDispatcher();
  }
}


The getPage() method from com.sapportals.portal.htmlb.page.PageProcessorComponent is abstract and is implemented to create a new instance of the MapDispatcher class, which is defined in a separate file.

The JIT iView's dispatcher class manages the retrieval and display of data from the backend system. In the example, the application logic of MapDispatcher consists of three separate parts:

• Determine the user mapping credentials for the current portal user
• Access the remote database with the mapped credentials and execute the SQL query
• Set the query result as the data source for the PDV service

To hold the data passed between the portal client and the IRJ, you must first get the com.sapportals.portal.prt.component.IPortalComponentRequest interface's request object:

IPortalComponentRequest request = (IPortalComponentRequest) this.getRequest();


Using the request object, the dispatcher class determines the user context of the portal user in the current session. This context, though, is only a wrapper for the true user object, which is obtained with the getUser() method. In addition to user-related information such as first and last names, default language, and business roles, userObject now contains the actual user ID wp from the corporate directory server's tree structure. (When using the PDK as a test environment, user management is maintained in text files, but the API is the same as when using a lightweight directory access protocol (LDAP) directory server.) Subsequently, the broker object is also enriched with this user information:

IUserContext uc = request.getUser();
IUser userObject = (IUser)uc.getUser();
ILogonDataBroker broker = userObject.getMappingInfo();


The Backend class, which is also provided in the download, is the default implementation for retrieving user mapping properties in the SAP portal server. For instantiation, Backend requires the name of the data source from the portal landscape. The data source system name MYSQL from the Systems.xml file is set in the dispatcher's KEY constant:

private static final String KEY="MYSQL";


Using the broker object, bConn is enriched with the required logon data for the connection to the backend system. The final step simply involves getting the user ID and password from the bConn backend object. At runtime, the value of un is mysql_remote and pw is gcoe:

bConn = new backend(KEY);
broker.enrich(bConn);
un = bConn.getUser();
pw = bConn.getPassword();


The next logical section in the dispatcher class uses the well-known format to register an instance of the JDBC driver and establish a connection to the database:

Class.forName("org.gjt.mm.mysql.Driver");
Connection con = DriverManager.getConnection("jdbc:mysql:///edi_db",un,pw);
Statement std = con.createStatement();
ResultSet res = std.executeQuery("select * from jit_calls");
con.close();


The main factor, of course, is that the user ID and password are not hard coded, but instead are determined at runtime based on the portal user. The database query executes once the mapped credentials authenticate, a connection establishes, and the query result returns to an instance of the java.sql.ResultSet class.

To enable the JDBC connection within the IRJ framework, you only need to copy the JDBC driver to your jre\lib\ext\ folder. Alternatively, you can put a copy of the driver in the portal component project's private\lib\. For the JIT iView example, I use MySQL Connector/J, the official JDBC driver for MySQL.

In the dispatcher class's final logical section, the result table from the SQL query is rendered in the iView by the PDV service. Normally, the DynPage framework is used to produce dynamic output via JSP technology. The com.sapportals.pct.util.pdv.PDVDynPage class, however, is an implementation of DynPage that uses the PDV to display tabular data without any JSP coding:

ISource pdvSource = portalDV.createSource(request, res);
portalDV.setSource(pdvSource);


The SQL query's result res is the table of data that is set as the PDV's source. At runtime, the PDV service automatically renders the table from the pdvSource object in an iView.

Test the iView
When using Ant, you create the portal archive by executing the ant command from the AntProject folder, where it reads the project build.xml file by default. The result of a successful build is the par file, com.ibm.gcoe.mysql.par, which is created in the project's root folder. The complete DOS output from a successful build of the example project is provided in Figure 10.

To deploy the PAR to the runtime environment, you can use the ComponentManager on the DevTools tab in the PDK. Browse to the PAR for your project and hit the Upload button. You should receive a number of INFO messages, as in Figure 11, if the upload is successful.

To test the iView, move to the ComponentInspector page in the PDK and find the name of your archive on the Overview tab. From here, you can click the Add to Favorites link and then switch to the Favorites tab. Finally, click the Start link for the portal component to launch the example iView, shown in Figure 12.

If the iView launches, then you have successfully built and deployed the portlet. The PDK includes many other iView examples and further documentation. You can also go back to the Java DevZone on the iViewStudio Webpage, where SAP experts regularly answer PDK-related questions in the developers' forum.

Get started today
The main drawback of the JIT example iView, of course, is that it is built using proprietary technology that will only run on an SAP portal server. Yet even when the public reference implementation for JSR 168 is released, it will still be some time before it can match the level of robustness offered by APIs from SAP and other leading portal vendors. Indeed, until the open source portlet API has proven that it can offer the same functionality of proprietary APIs, Java developers will continue to develop portlets with vendor-specific frameworks.