Introduction

Since part 1 of this series was published, IBM made a formal announcement about rewriting Notes completely in J2EE in the next year or two. I applaud IBM's move because J2EE is the right direction. However, many users are asking, "What are we going to do with our existing applications in Notes/Domino?" In this article, I explore how you might transform an existing Notes/Domino application to J2EE.

My previous article discussed the architectural differences between Notes and WebSphere, and how to maximize the system performance by choosing the right one. The focus of this article is on the actual conversion of an existing Notes/Domino application to WebSphere.

Back to top

Design components

Notes/Domino has a few key components: navigator, agent, form, view, and security. Navigator is very easy to replicate on the Web because it was originally designed to make Notes look like the Web. The agent function is business logic, which can be implemented in J2EE accordingly. This section discusses the creation of a form and a view, as well as the security design in the J2EE environment.

Form

A form consists of a front end, middleware, and a back end.

Front end

As discussed in the previous article, Apache Struts is an excellent tool for handling the front-end form input. I use Struts again in this article. Figure 1 shows how documents are read, created, edited, and deleted.

The Struts Model-View-Controller (MVC) model takes the user inputs, passes the validation, and through its' action servlet creates a Java bean (form bean) that contains every field on the form. Client-side validation can be achieved by programming in JavaScript on the JavaServer Pages (JSP) pages. We also made a tag library of our own to create a few unique Notes features, such as the pick list and dialog box. Rich text fields are unique to Notes, and allow users to input text with different fonts and add attachments. On the Web, as demonstrated by many mail programs, attachments can be added one-by-one to an e-mail message. (I will not go into too much detail in this article because there are many existing packages that can handle it.)

Line item is a little tough to build in Notes; it is usually done by building a large table and hiding the empty line with the "hide when" formula. There is a limit on how many line items can be put on a form. In Struts, on the other hand, it is quite easy to build line items in a form. You can simply put an array of beans in the session, request, or page attributes and Struts will build a table line-by-line for you. When users choose to add a line item, the form will be submitted without validation and put in temporary storage. After the item is added, the temporary form will be refreshed so users can see the changes.

Middleware

The copy helper Java bean can be used to transport data from Enterprise JavaBeans (EJBs) to servlets. This type of Java bean will help in the layer isolation. Front end developers can develop JSP pages and form beans with dummy data from the copy helper bean. In the meantime, back end developers can develop EJB for the copy helper bean. When both parts are ready, all you need to do is to replace the beans with dummy data with the real bean.

Back end

The entity EJBs are used to read, create, modify, and delete documents from the database. Notice that we use a session bean to pass the data to multiple entity beans for read and update, as seen in Figure 1, so the session can invoke as many entity beans as needed to complete the form update. Another advantage of this design is that you shield entity beans from the middleware. The EJB 2.0 specification made a few major enhancements on the container-managed persistence (CMP) entity bean, such as EJB-QL, Container Managed Relationship (CMR), and local interface. When the next version of WebSphere implements the EJB 2.0 specification, you can update the entity beans without changing any middleware or front-end codes.

View

Front end Notes/Domino has one of the most sophisticated navigation designs available. Over the Web, few places use Notes-like browsing of sorted and categorized columns; most just use a search function. Because replication of the Notes view in WebSphere is not an easy task, if your users can stay with a Web-like search function, it will simplify the conversion process.

If you decide to replicate the Notes view in WebSphere, there are a few steps to go through. We constructed a special tag library to build standard, categorized, and calendar views. We even extended the tag library to include a few features that are not common in Notes/Domino. For example, we have two types of sorting in a categorized column. Users can sort the documents within a category or sort all the documents in the view. Because users are able to sort on any column, cache is needed to maximize the performance. Our middleware software provides view navigation, including page and sorting.

Since Domino Version 5, you can select the option to use a Java applet-based view. To convert an applet-based view is quite easy; there are many navigation applets you can buy online for a minimum fee, and in some cases even with source code. My colleague, Charles Jones, and I pioneered an applet to navigate a Notes based catalog database in 1997 when we were working together in IBM. However, applets have well-known weaknesses: they are slow and unstable. The majority of Domino views used today are still in HTML formats. Figure 2 shows a diagram of the view design.

Middleware and back end

The rowset Java bean is used to transport data between the servlet and EJB. The EJB will be a bean-managed and stateful session bean to maximize performance. A bean-managed bean gives us the possibility of passing a chunk of data in one batch and sending it to the front end. Using stateful session beans maintains the page information so users are directed to the right page when browsing the document page by page.

To increase efficiency, we recommend you maintain a pre-built view inside the relational database for the default sorting of a Notes view.

Security

Back to top

Example

Now for a real-world example. Several years ago, a timesheet application was written in Notes. Since then it has grown into a very large database and we now need to integrate it with a central DB2 database as well as payroll's SAP. By converting the Notes-based application to a WebSphere-based application, we can resolve performance and integration issues because WebSphere has a direct JDBC connection to DB2 and a SAP connector from IBM or SAP.

Example form

The form is based on Struts, as mentioned earlier. Here is a typical Struts JSP header and an input field. The tojava.tld file describes our custom JSP tag library.

<%@ page language="java" %>
<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %>
<%@ taglib uri="/WEB-INF/tojava.tld" prefix="tojava" %>
<html:text property="phoneNumber"  
   name="timeSheet" size="20" maxlength="20"/>

Figure 3 shows a time sheet form.

Figure 4 shows the time sheet form in read mode.

Figure 5 shows the time sheet form in edit mode

The fields are managed by a Struts form bean.

public class TimeSheetForm extends ActionForm {
    private String employeeName = null;
    private String department = null;
    private String phoneNumber = null;
    private String completeDate = null;
    private String approvedBy = null;
...
}

We built a tag library of our own to handle some of the Notes-specific functions. For example, a dialog box can be coded as follows:

<tojava:select imagedir ="/tojava/image" formname="timeSheetForm" 
  inputproperty="department" selectsize="9" 
optionvalue="Accounting, Administration, Business Development, 
  Engineering, Management, Marketing, Sales, Systems, Technology Support" 
selectwindowheight="250" selectwindowwidth="250" 
  selectwindowdir="/tojava" />

Figure 6 below shows the time sheet form dialog box.

Like the other common tag libraries, properties are used to pass data to the Java code when the HTML page is constructed. Property imagedir refers to the directory that stores the image file. Property formname is the name of the form that contains the field, and inputproperty is the name of the field for the selection.

For a line item, you can simply use the Struts iterate tag as we have seen in the Struts sample code. Below is the complete source code:

<logic:present name="timeSheetDoc" property="timeItems">
<logic:iterate id="item" name="timeSheetDoc" property="timeItems">
<tr>
<td> <bean:write name="item" property="date"/> </td>
<td> <bean:write name="item" property="startTime"/> </td>
<td> <bean:write name="item" property="finishTime"/> </td>
<td> <bean:write name="item" property="hours"/> </td>
<td> <bean:write name="item" property="descrip"/> </td>
<td align="center">
<a href='/tojava/sample/timeSheetFormDemo.do?action=Delete&key=<bean:write 
  name="item" property="itemNumber"/>'>
<img src="/tojava/image/Delete.gif" border="0"> </a>
</td> 
</tr>
</logic:iterate>
</logic:present>

The timeSheetDoc is a document bean that stores all the document related properties. It contains timeItems that store the array of line items for Struts to iterate through. Inside the iterate loop, we list the properties according to the columns of the table. At the end, we add a deletion link to delete any item. Figure 7 shows the time sheet form line item.

Finally, we built a Struts action class to read, edit, and create the form input.

   public class TimeSheetFormAction extends Action {
   	public ActionForward perform (ActionMapping mapping, ActionForm 
        form, HttpServletRequest request, HttpServletResponse response) 
		throws IOException, ServletException {}
}

Example view

Most of the resulting view is built using our own tag library, which supports categorized, regular, and calendar views. A sample of a categorized view follows.

<tojava:view status = "expandall"/>
<table border=0>
<tr> 
<th>Department</th> 
<th>Name</th> 
<th>Total Hours</th>
<th>Completed On</th> 
</tr>
<tojava:viewloop>
<tr>
<td> <tojava:viewitem name="department" category="true"/> </td>
<td> <tojava:viewitem name="employeeName" category="true"/> </td>
<td> <tojava:viewitem name="totalHours"/> </td>
<td> <tojava:viewitem name="completeDate"/> </td>
</tr>
</tojava:viewloop>
</table>

Figure 8 shows the time sheet view.

We use a view-viewloop-viewitem structure. The view tag is used to display view-related functions, such as view navigation, lines per page, and so on. The status property initializes the view primary status. Viewloop starts the actual loop. Viewitem displays the actual item by passing the field name, category, checkbox options, and so on. As you might notice, we extend the Notes/Domino view to have two different kinds of sorting. We have also added the option to have a checkbox in front of each document to run macros for batch processing.

A TimeSheetViewAction class can be written as follows:

    public class TimeSheetViewAction extends ViewAction {
    public void Initialize () {}
    public TreeMap RebuildView (TreeMap formItems) {}
    public TreeMap CreateForms () {}
    public TreeMap CreateDocs () {}
}

The ViewAction is an abstract class that handles all the common view features and navigation. Four abstract methods must be implemented in the subclass:

initialized()

Initializes the view, passes the url forward string and first sorted field name to the view.

CreateForms() and CreateDocs()

Loads initial data from the database, usually through EJBs, to the Struts form beans and document bean.

RebuildView()

Handles document deletion.

In the middleware we also built a library to provide Notes-like security and objects, but due to the size of this article I cannot go into details. You can go to my company's Web site to download the latest code. In this demo, I hard-coded the password as "tojava". If you log in as Editor, you can create, read and update any document. If you log in as Reader, you can only read the documents and create your own. If you log in as any other user, you can only create, read and update your own documents.

In the Resources section I've included the complete source code of the JSP and Java files; you can build a project with your favorite IDE. The one we use most often is JBuilder 5 or 6. Any other Struts-compatible IDE works too, such as IBM WebSphere Studio Application Developer Version 4. VisualAge for Java can be used, but you need to set up Struts according to Kyle Brown's instructions (there's a link to his article in Resources).

I also included the ear file that you can install on your WebSphere server, version 4.01 or later. WebSphere 3.x can be used, but additional steps are needed to set up Struts.

Back to top

Conclusion

In the past few years, my colleagues and I have converted a number of Notes/Domino based applications to Java that were built on top of relational databases. Although it is very hard to cover in this article all of the techniques and architecture we used, I have presented the best strategy I've found for converting Notes/Domino applications to J2EE WebSphere. I believe that using a JSP tag library, JavaBeans middleware, and EJB components for data access is the best approach to this unique problem. Compared with rewriting a completely new application in J2EE, our reusable front-end and middleware components greatly accelerate the conversion process, and using these well-tested components reduces the risk of project failure.

This article concludes my series of Lotus Notes/Domino to WebSphere, but work doesn't stop here as we will continue to improve our libraries and architecture over time. I would like to thank many of you for providing feedback to the first article as well as words of encouragement. As one of the earliest technical articles on the subject of converting Notes/Domino to Java, I hope this article gives some insights. If you have any questions, comments, criticism, or simply want to share your own experience, I would be very happy to hear and discuss. For the latest update, please visit our company's website at http://www.to-java.com.

Acknowledgements

The author would like to thank Mr. Steven R. Desofi for the helpful discussion and Mr. Charles M. Jones from Virtuous Dialogue for reviewing the article.

Back to top

Download

Information about download methods

Resources

• Download the zipped source code discussed in this article.
  
  
• Enterprise JavaBeans by Richard Monson-Haefel, 3rd Edition, O'Reilly & Associates; ISBN: 0596002262; (October 15, 2001)
  
  
• Build your next development project with IBM Struts.
  
  
• Apache foundation Struts, an open source MVC (Model-View-Controller) framework with tag library.
  
  
• Find more information for developers on WebSphere Developer Domain and Lotus Developer Domain.
  
  

About the author

Chen Lin has been a Certified Lotus Notes Developer and Consultant since 1995. As an independent consultant he worked at many Fortune companies, including IBM, where he architected and developed many systems that require high performance and scalability. He is currently working with his colleagues to run a company that specializes in converting Notes/Domino applications to WebSphere. You can contact Chen at clin@to-java.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Design components
• Example
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Notes
• Webcast: Reach for high ROI: Forrester on the economic benefits of upgrading to Lotus Domino 8.5
• Buy: Lotus Notes