In part one of this two-part series, we covered how to integrate Lotus Domino and IBM WebSphere using Domino XML (also called DXL). DXL lets you access Domino objects without knowing much about Lotus Domino. However, some Java experience is required to use the DXL method. For those Notes application developers with little Java experience, there are the Domino JSP tag libraries that ship with the Lotus Domino Toolkit for WebSphere Studio. (The toolkit is available with Lotus Notes/Domino 6.0.2 and later. Passport Advantage customers can also download the toolkit.)

Lotus has been shipping two JSP tag libraries since launching Lotus Domino 6. These libraries provide programmers the ability to develop J2EE applications that can interact with Lotus Domino on virtually any J2EE-compliant application server. Prior to the availability of the tag libraries, JSP developers who wanted to connect their applications with Lotus Domino had to build CORBA and IIOP calls into their applications. This resulted in complex and often database-specific code that is rarely reusable. As the demand for interoperability grows, a smarter, more powerful solution is needed.

Lotus recognized the demand and responded by creating two tag libraries that abstract and encapsulate common Lotus Domino and J2EE functions. These libraries are defined in tag library descriptors domtag.tld and domutils.tld. Domutils.tld describes utility tags that handle tasks common to all J2EE applications. These tags are not Lotus Domino-specific and can be used on any application--independent of a Domino server. Tags described in domtag.tld are Lotus Domino-specific. They provide programmatic access to virtually all Domino elements including designs, access control lists, and documents. In this article, we focus on the Domino-specific tags (those defined in domtag.tld). From this point on, we refer to it simply as the taglib.

Before we begin

The taglib requires more in-depth Lotus Domino knowledge than the XML method discussed in the first article. It uses terminology and controls that are tightly embedded in the Domino framework. To effectively use the taglib, it is important that you have a deep understanding of Lotus Domino, the various design elements, and the structure of the data you are accessing. Review the Roadmap section from part one to help you decide which method is more suitable for you and your application.

Requirements

The taglib conforms to JSP 1.1 and Servlet 2.2 specifications and supports most J2EE-compliant application servers. The examples in this article are installed on IBM WebSphere Application Server 5.1 and developed with WebSphere Studio Application Developer. This article assumes that you are familiar with Domino objects and terminology as well as basic J2EE programming using WebSphere Studio Application Developer.

NOTE: Aside from preparing Lotus Domino to handle IIOP, you do not need any CORBA or IIOP programming knowledge to use the taglib.

Software requirements are as follows:

• WebSphere Application Server 5.x or other J2EE-compliant application server
• Lotus Domino 6.x with DIIOP service installed and enabled

Preparing Lotus Domino

The taglib uses CORBA (Command Object Request Broker Architecture) and IIOP (Internet Inter-ORB Protocol) technologies to communicate with Lotus Domino. You must set up the Domino server to listen for IIOP requests. First, make sure DIIOP is installed. Issue the command show task or load diiop in the Domino console to help determine whether or not DIIOP is present. If not, install it from the Domino installation CD.

Next, edit the Domino server?s Notes.ini file to automatically load DIIOP when Lotus Domino starts. Locate the line starting with ServerTasks. At the end of that line, add diiop. Restart the Domino server and check for the DIIOP server?s start up message.

When the DIIOP process starts, it creates an IOR (Internet Object Reference) called diiop_ior.txt in the Domino HTTP root directory (C:\lotus\domino\data\domino\html for default Domino installation in Windows). If you use Lotus Domino as your HTTP server, you may skip this next section.

If you do not use Lotus Domino as your HTTP server, you must tell DIIOP to put the file in the root HTML directory of your HTTP server.

1. Open the Domino Server document.
2. Select the Internet Protocols tab - DIIOP subtab.
3. In the External HTML directory field, enter the full path to the root HTML directory of the non-Domino HTTP server.
4. Save the Server document and restart DIIOP.

Test to see if the file is accessible from a Web browser: http://127.0.0.1/diiop_ior.txt

Back to top

Configuring the J2EE application environment

To use the taglib, two JAR files are required: NCSO.jar or Notes.jar (see sidebar) and domtag.jar.

1. In Windows Explorer, open [Notes installation path]\Data\domino\java. Locate and copy domtags.jar and NCSO.jar to the WEB-INF/lib directory of the Web application.

   NOTE: Copy these files to the shared-libraries directory of your application server if you have more than one Web application using the taglib.

   
   Figure 4. WebSphere Studio Application Developer's J2EE Perspective
   
   
2. From [Notes installation path]\Data\domino\java, locate and copy domtags.tld into the project?s WEB-INF directory. This file is the Tag Library Descriptor (thus, the TLD extension). It describes tags as they relate to the underlying Java code, so the application server can understand the tags.
3. Next, locate and open the Web application?s web.xml. Add the following taglib reference and save the changes.

   <taglib id="domtags"> <taglib-uri>domtags.tld</taglib-uri> <taglib-location>/WEB-INF/domtags.tld</taglib-location> </taglib>

   
   

Here is an example web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp">
	<display-name>ArticleWeb</display-name>
	<welcome-file-list>
		<welcome-file>index.html</welcome-file>
		<welcome-file>index.htm</welcome-file>
		<welcome-file>index.jsp</welcome-file>
		<welcome-file>default.html</welcome-file>
		<welcome-file>default.htm</welcome-file>
		<welcome-file>default.jsp</welcome-file>
	</welcome-file-list>
	<taglib id="domtags">
		<taglib-uri>domtags.tld</taglib-uri>
		<taglib-location>/WEB-INF/domtags.tld</taglib-location>
	</taglib>
</web-app>

Setting default parameters

The taglib has a number of Context Parameters you can set in the web.xml file. It is highly recommended that you utilize these application-wide parameters as much as possible to increase portability and to ease maintenance havoc in the future.

In our example, we set the host (127.0.0.1) and database (articleSample.nsf) as Context Parameters. They are lotus.domino.default.host and lotus.domino.default.dbname respectively.

To do so, open web.xml and add the following lines and save it.

	<context-param id="dominohost">
		<param-name>lotus.domino.default.host</param-name>
		<param-value>127.0.0.1</param-value>
	</context-param>
	<context-param id="dominodbname">
		<param-name>lotus.domino.default.dbname</param-name>
		<param-value>articlesample.nsf</param-value>
	</context-param>

Back to top

Using the domtags

In the next sections, we use the Car database that we used in the previous article. We will build four JSPs that will do the following:

• Display a document.
• Display the content of a Domino view.
• Enable Domino view search.
• Allow users to create and edit documents.

Before we start, you must include this taglib declaration in all the JSPs that use the taglib. It tells the application server that every tag that begins with the word domino is a reference to an entry in the domtags tag library descriptor, for example, <domino:db>. (Even though you may use a different prefix, it is highly recommended that you use domino.)

<%@ taglib uri="domtags.tld" prefix="domino" %>

Displaying the document

We first create a simple JSP to display the contents of a Notes document. It takes a single querystring parameter called unid whose value is the document unique ID of the requested document. In your JSP editor, create a new JSP called disptagcar.jsp. Begin by typing the taglib declaration mentioned earlier. It is also a good idea to include an import line with lotus.domino.* because it allows you to access the Domino objects directly. We?ll have more on this later.

<%@ taglib uri="domtags.tld" prefix="domino" %>
<%@page import="lotus.domino.*"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<%@ page 
language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"
%>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Vehicle information using Domino Tag Library</title>
</head>
<body>
<h1>Vehicle information using Domino Tag Library for <%= (String) request.getParameter("unid")%></h1>
<domino:document>
<table border="1" width="100%" cellspacing="0" cellpadding="0">
	<tr bgcolor="#ccff00">
		<th>Make</th>
		<th>Model</th>
		<th>Body Type</th>
		<th>Engine</th>
		<th>Year</th>
		<th>Specifications</th>
	</tr>
	<tr>
		<td>
			<domino:item name="make"/>
		</td>
		<td>
			<domino:item name="model"/>
		</td>
		<td>
			<domino:item name="bodytype"/>
		</td>
		<td>
			<domino:item name="enginetype"/>
		</td>
		<td>
			<domino:item name="year"/>
		</td>
		<td>
			<domino:item name="specifications" format="<LI>"/>
		</td>
	</tr>
</table>
</domino:document>
</body>
</html>

The <domino:document> tag provides the context of a Notes document. Within it, your code has access to virtually all items and properties of a particular document. In some cases, you may want to pass in values to the dbserver, dbname, and unid attributes in the document tag. But notice we did not do that in our example. The reason is because the necessary information is already specified elsewhere. The host name of the server and the filename of the database is already defined by the Web Deployment Descriptor (web.xml). The UNID is implicitly specified when there is a querystring parameter unid.

If for some reason, you do not want to expose the UNID in the URL, you must supply it somehow to the document tag explicitly in the unid attribute.

<%
String unid = [[code that obtains the document unid]];
%>

<domino:document unid=?<%= unid %>?>

The <domino:item> tag displays the content of the item specified in the name attribute. For instance, <domino:item name="make"/> displays the value stored in the make item. The last item tag referencing the specifications field has a format attribute. This attribute tells the tag library how to display the value in the JSP. The value you supply this attribute is called a keyword. You can use more than one keyword in a format attribute.

Recall that the specifications field is a multi-value field; it can contain more than one value. The <li> keyword tells the <domino:item> tag to wrap each of the values in the specifications with an opening <li> and a closing </li> tag.

Displaying the view contents

Domino views are accessible via the <domino:view> tag. For instance, in our car example, we have a simple view called Cars\By VIN that has two columns: vin and make. The view also has an alias called vins, which is what we will reference in the view tag.

Here is the code for the JSP that displays the VINs view as HTML.

<%@ taglib uri="domtags.tld" prefix="domino" %>
<%@page import="lotus.domino.*"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<%@ page 
language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"
%>
<%
String count = "30";
if(request.getParameter("count")!=null);
	count = (String)request.getParameter("count");
%>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Car List using Domino Tag Library</title>
</head>
<body>
<h1>Car List using Domino Tag Library</h1>
<domino:db>
	<table border="1">
		<tr bgcolor="#ffcccc">
			<th>
				VIN
			</th>
			<th>
				Make
			</th>
			<th>
				Model
			</th>
		</tr>
		<domino:view viewname="vins" max="<%= count %>">
			<domino:viewloop>
				<tr>
					<td>
						<domino:formlink href="disptagcar.jsp" >
							<domino:viewitem name="vin" />
						</domino:formlink>
					</td>		
					<td>
							<domino:viewitem name="make" />
					</td>
					<td>
						<domino:item name="model" /> 	
					</td>	
				</tr>
			</domino:viewloop>
		</domino:view>
	</table>
</domino:db>
</body>
</html>

Examining the view JSP

Let?s examine the preceding JSP. We use this JSP to build a search page in a later section.

• Database
  The <domino:db> tag gives the application the context of the database. Because we have defined a default database in the web.xml, we do not have to define it here. If you did not define a default database in the web.xml or you want to access a database other than the one defined in the web.xml, you need to provide that information here by defining an attribute dbname and, if the database is on another server, dbserver.
• View
  Placing the <domino:view> tag within the context of the <domino:db> tag provides access to the named view within that database. You must provide the name of the view as an attribute in the viewname attribute. You can use the view?s alias. The max attribute controls the number of entries to display per page.
• Viewloop
  This tag provides iterative access to each of the entries inside a view. It loops through the view and provides access to its contents. In the example, we simply print out the content of the view with the viewitem tag described later.
• Formlink
  The <domino:formlink> tag dynamically builds <a href> links to a specified JSP. The resulting page should include some form of tag library code that can display the content of a document. In our example, we use the JSP that we built in the last section (disptagcar.jsp).
• Viewitem
  The <domino:viewitem> tag provides direct access to the view entry. The name attribute refers to the column name in the view. The name value is case sensitive and must match the column title exactly.

  <domino:viewitem name="vin" />
<domino:viewitem name="make" />

• Item
  The <domino:item> tag provides access to a field that resides within a document. The name attribute specifies which field to retrieve.

The difference between <domino:item> and <domino:viewitem> is that <domino:item> must open the document to retrieve the value, while <domino:viewitem> uses whichever value is displayed on the view. Whenever possible, avoid using the item tag in the context of a viewloop because performance can suffer significantly.

Back to top

View search

In this section, we discuss how to modify the view JSP we created to support search functionalities.

For full-text search to work properly, the Domino database?s full-text index must be turned on. To see whether or not the database is indexed, open the Database Properties box and click the Search tab. If the database is not indexed, click the Create Index button. The Notes client?s status bar tells you if the request has been queued. A full-text index is usually built shortly.

Our search form will include three fields for a customizable search: the query, the maximum number of results to return, and the number of entries to display per result page. We use the view JSP from the last section as the base for the search JSP.

Here is the portion of the JSP code that handles search:

<domino:view viewname="vins" ftsearch='<%= query %>' max='<%= max %>'>
	<domino:page rows='<%= count %>'>
		<tr><td colspan="3" align="right">Go to page: 
		<domino:pagebar navstyle="NextPrev" />&nbsp;&nbsp;&nbsp;
		<domino:pagenext>Next></domino:pagenext></td></tr>
		<domino:viewloop>
			<tr>
				<td>
					<domino:formlink href="disptagcar.jsp" >
						<domino:viewitem name="vin" />
					</domino:formlink>
				</td>		
				<td>
					<domino:viewitem name="make" />
				</td>
				<td>
					<domino:item name="model" /> 	
				</td>
			</tr>
		</domino:viewloop>
		<domino:novalues>
			<tr>
				<td>
				The search for <%= query %> found no matches. Use another keyword and try again.
				</td>
			</tr>
		</domino:novalues>
		<tr><td colspan="3" align="right">Go to page: 
		<domino:pagebar navstyle="NextPrev" />&nbsp;&nbsp;&nbsp;
		<domino:pagenext>Next></domino:pagenext></td></tr>
	</domino:page>
</domino:view>

Examining the Search view JSP

Let's look at the Search view JSP in more detail.

• View
  To build a search view, we have to add two attributes to the <domino:view> tag: ftsearch and max. Ftsearch is the string of the query, and max is the maximum number of results to return.
• Page
  This tag provides pagination controls for displaying view contents as well as results from a search. Its rows attribute limits the number of entries on a single page. This tag provides the context for tags that provide navigational features.
• Pagebar
  Within the context of the page tag, <domino:pagebar> automatically generates links to the pages the search results span across. The link to the current page is rendered as bold and is non-clickable.
• Pagenext
  This tag generates a next page link automatically. The body of this tag is the text label for the link. In this case, we use Next >. You can use this tag alongside pagebar to create a page-navigation similar to figure 8.
  Figure 8. A navigation bar
  
  
• Novalues
  The body of this tag is the text to display when search returns no results. In our example, we display the message, ?The search for [query] found no matches. Use another keyword and try again.?

Back to top

Forms

In this last section, we create a JSP form with which users can create and modify Notes documents. For the sake of simplicity, our sample database allows anonymous author access. In a real-life application, where security really matters, a more sensible approach would be to use a centralized user registry (such as LDAP) and to employ single sign-on (SSO). Set up WebSphere as a trusted container to handle authentication and authorization for Lotus Domino. For more information regarding SSO for WebSphere and Lotus Domino, refer to the WebSphere Application Server InfoCenter.

Our form provides the following features:

• Allows users to create documents. Displays a message indicating the user is creating a new document.
• Allows users to edit existing documents. Displays a message indicating the user is modifying an existing document.
• Validates input. Displays customized error message if validation fails.
• Forwards users to a thank you page when the form is submitted successfully.

For the complete code of the Form JSP, see the side file, "Form JSP code."

The form tag

The <domino:form> tag provides edit access to the specified document. It supports a number of attributes supporting a host of advanced operations. We used the more commonly used ones in the example. Let?s examine them:

• Name
  This is the name of the form object. The value here will also be used as the HTML form name. This value should be unique in each JSP.
• Schema
  This value corresponds to the name of the Domino form with which this document should be saved. The Domino form?s pre-save processing (QuerySave) is done on the document. Setting this value also implicitly places it in the form field of the document.
• Editmode
  This attribute accepts three values: display, edit, and delete. While you can hardcode the value for this attribute, it?s probably most useful when you programmatically assign a value to this attribute based on a certain logic in the code.
• Validhref
  This value is the destination page where you want to send the user after the form has been validated and saved.
• Clientvalidate
  Setting this value to true causes the form to validate user inputs based on the validation tags. Conversely, setting this value to false causes the form to ignore all validation tags.
• User
  Specifies the name of the user who is accessing the Domino data. When authentication is done using a J2EE container, set this value to *webuser. Refer to the Domino Designer Help for full details on the taglib security.
• Unid
  If there is a unid parameter in the JSP?s querystring, the form tag uses that unid to open a document. You may alternatively pass the unid in the unid attribute.
• Input tags
  The input tags create the HTML input fields. The name attribute designates the item with which the value is to be saved. By default, the data type is text. In cases where another data type is required, specify the data type attribute to match that of the field in the form?s schema. For multi-value fields, set multivalue="true" and specify the value delimiter with mveditseparator and mvdisplayseparator. In our example, we use commas to separate values for edits and semicolon for display.
• Validation tags
  These tags handle input validation before the form is saved. Lotus supplies a number of validation tags to handle validations for different data types. In our example, we used more commonly used tags: validaterequired and validatepattern. You can use more than one validation tag per field.

Now, let's examine the validation tags we used:

• Validatesummary
  This tag displays the value of the message attribute of a validation tag that detected a validation failure. Place this tag on the top of the form so a user can see at-a-glance what he/she did not fill out correctly.
• Validaterequired
  This tag determines whether or not the field in the name attribute is null. If not, the body of this tag will display on the page. Place this tag next to the field to point out exactly what the user should focus his/her attention on.
• Validatepattern
  In instances where the basic validation tags are not enough, you can use this tag to create customized validations. The core of this tag relies on Apache's regexp library to validate input values. Build a regular expression that describes the expected value format and put it in the pattern attribute. The tag will then compare the user input against regular expression. In our example, the validatepattern tag checks that the year field is numeric and is four characters long.

The document tag

The <domino:document> tag gives access to the Notes document itself. The existence of the id attribute flags the taglib to assign a lotus.domino.Document object with its name being the value in the id tag. That object, in our example, is doc. This gives the programmer full programmatic access to the object?s properties and methods; further extending the usage of the taglib to be programmable in regular Java code. This powerful facility is available for most tags in the taglib. To learn more about the Domino Java classes, refer to Domino Designer Help.

Back to top

Conclusion

In this article, we discussed how to program with the Domino JSP tag library to build powerful Domino-enabled J2EE applications. Through examples, we discussed the commonly used tags and examined the concepts behind them. The information presented in this series should enable you to adopt J2EE into your existing Domino environment.

Back to top

Download

Information about download methods

Resources

• Read part one in this two-part article series, "Lotus Domino and IBM WebSphere integration solution: Domino XML."
  
  
• See the full code for the Form JSP in this side file.
  
  
• For information about the Lotus Domino Toolkit for WebSphere Studio, see the toolkit page.
  
  
• To learn more about WebSphere, visit the developerWorks WebSphere site. You'll find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Before we begin
• Configuring the J2EE application environment
• Using the domtags
• View search
• Forms
• 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

Dig deeper into Lotus on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers