Lotus Domino and IBM WebSphere integration solutions: Domino XML

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Introductory

Jeffrey Lo, Advisory Software Engineer, IBM Corporation

01 Mar 2005

Manage your data in Lotus Domino, but take advantage of IBM WebSphere's highly scalable, transactional J2EE platform using one of these solutions: Domino XML or Domino JSP tag libraries. In part one of this series, we focus on Domino XML or DXL.

Many organizations find that the next logical move for their Domino Web applications is to integrate them with IBM WebSphere software. And they are doing so for good reasons. Lotus Domino's document-based architecture makes it easy to create and share documents between content creators and editors. Its built-in security and versioning capabilities are ideal for administering document-based content.

WebSphere is a high performance, enterprise-level transactional application server. At its core is a powerful J2EE engine designed for high scalability and robustness. WebSphere is also the melting pot for the latest Web technologies. Organizations that seek to expand their current Domino applications to utilize these technologies find embracing WebSphere in their environment a logical choice.

While the benefits are apparent, the path to achieving integration may not be. Oftentimes, developers who are proficient with one system are not so with the other. Hence, integration entails a combination of a steep learning curve and tight timelines for the developers. IBM and Lotus recognize this and have incorporated a number of tools to aid in the process.

In this two-part article series, we introduce you to two different integration methods: one using Domino XML (DXL) and the other using the Domino JSP tag libraries that are part of the Lotus Domino Toolkit for WebSphere Studio. We examine the pros and cons of each method and discuss their strengths and weaknesses. Through the use of a checklist, we will help you decide which method is best suited for you and your application. Then through examples, we show you how each method works in detail.

In part one of this series, we focus on Domino XML. In part two, we focus on the Domino JSP tag libraries. Both articles assume that you are an application developer familiar with XML and JSP technology. Part one also assumes some Java experience.

The two methods: XML and Domino JSP tag libraries

Lotus is a longtime supporter of XML. Since the release of Lotus Notes/Domino 5, Lotus has been adding new functionality to each version of Lotus Notes/Domino to increase its capabilities to handle XML. Lotus Notes/Domino 6.5 is no exception. It comes with numerous features that enable developers to generate and extract XML from virtually all Domino elements. For those who are less familiar with Domino terminology, a Domino database contains Notes documents as well as design elements such as forms, views, and agents. XML lets you access those design elements and documents. Think of it as your application server, Web server, and database engine rolled into one.

Another access method is the Domino JSP tag libraries. These libraries are provided by Lotus to aid developers in building Domino-enabled JSPs. The tag libraries hide the underlying Java code that is necessary to connect a JavaServer Page (JSP) to Lotus Domino. The communication is done using CORBA via IIOP. This allows the Java code to programmatically access virtually all of the database's elements.

Roadmap: XML or tag libraries?

These two methods offer different approaches to integration. The following checklist will help you decide which method is most suitable for you and/or what you want to accomplish.

Your expertise
Many Java developers cringe at the idea of learning Lotus Domino only because it bears little resemblance to what they are accustomed to. These individuals seek solutions in the open standards realm where languages such as Java and XML are prevalent in developing applications. If you are one of these developers, you will find the XML method more easily understandable. It requires minimal Domino experience, but requires more understanding of XML, XSLT, and Java.

On the other end of the spectrum are seasoned Domino developers who have in-depth knowledge of Lotus Domino, but who have little to no Java or WebSphere experience. For these developers, the tag libraries are more appealing. This method requires fairly extensive Domino knowledge and skills. It also requires minimal administrative experience and access to modify system configuration changes.

Nature of the site/application
Presentational
Many Web sites are presentational. This means that their main objective is to display HTML content over the Web. This type of Web site requires little to no user inputs. The contents are usually not modified after initial publishing. Examples of presentational sites are news or product documentation pages.

There may be times when you need to distribute data on mediums other than the Web. For instance, you may need to make fliers and brochures or to generate email newsletters from the data stored in Lotus Domino. Presentational-driven sites/applications benefit most from the XML method because XML is extensible and can be transformed to a countless number of formats.

Transactional
Technically, all Web sites are transactional. But in this case, for the sake of explanation, a transactional site is one that relies heavily on user input. These sites offer a collection of services where contents are personalizable and are often dynamic. This usually requires some form of authorization and authentication against a user registry. Examples of transactional sites are auction sites and on-line discussion forums. This type of site/application benefits most from the tag libraries solution.

Characteristics of the two methods
XML is very portable. You can use it to share data between virtually all application servers and databases using most modern programming languages. XML uses industry standards, such as Java, XSLT, and so on, and is extensible, but not system or platform dependent. It does not require intimate knowledge of Lotus Domino and the database to work with it. XML is excellent for presentational Web sites that focus on content delivery.

The tag libraries are very tightly integrated with Lotus Domino and J2EE standards. They provide low-level Domino object access, such as a direct query to a Domino view. To use the tag libraries, you must have intimate knowledge of the Domino architecture and the database design. The tag libraries support bidirectional data flow between Lotus Domino and WebSphere. They are excellent for transactional and interaction-intensive Web sites.

Back to top

The XML method

In part one of this article series, we focus on the XML method. In part two, we focus on the tag libraries. The XML method can be broken down into three parts: exporting XML from Domino, transforming the XML, and displaying the resulting contents in a JSP. We discuss the method in this order. To modify the JSP file, we use WebSphere Studio Application Developer 5.1, but this software is not required.

Introducing Domino XML (DXL)

Lotus Domino ships with a number of features to export and import Domino data and design elements as a special type of XML. Lotus Domino calls it DXL, short for Domino XML Language. Do not let the name confuse you. DXL is simply XML that conforms to the Domino DTD, which you can find in the Notes\xmlschemas directory.

As of this writing, Lotus Domino 6.5.1 ships with eight schema documents, one for each iteration of Lotus Domino 6.x.

Before we move on, let's set up the environment in which the examples can run. The example assumes the Microsoft Windows operating system running Lotus Notes 6.5:

1. In Windows Explorer, create a directory called article on the root or C: drive.
2. Download the sample files for this article and extract the files to the newly created C:\article directory.
3. Verify that the following folders are present:
   • Article
   • Com
   • Dxl
   • Xml
   • Xsl
4. Copy the included articleSample.nsf database to your Notes\data directory. This database stores simple car information that you can get from a used car dealership.
5. With the Notes Client closed, locate and open the notes.ini file (typically in the Notes directory) and add the included XML .jar files to the JVM classpath. You do so by adding the following line as first item in the document (immediately under "[Notes]"):
   
   JavaUserClasses=C:\article\xercesImpl.jar;C:\article\xmlParserAPIs.jar
   
   Save and close the file.
6. Open the articleSample.nsf database in Domino Designer.

   NOTE: You must have at least Designer-level access in the ACL and the Create Lotuscript/Java agents option must be enabled.

7. In the left pane, under the articleSample.nsf database, choose Shared Code - Agents. You should see two Java Agents.
8. The database is empty, but you can populate it by running the GenerateCars agent, which will generate 1,000 cars based on a randomly select set of values. Right-click the GenerateCars agent and choose Run to create Car documents in the database. Open the Notes client and check the database contents.
   Figure 1. Sample Car document in Lotus Notes
   
   
9. Next, generate DXL and XML from the newly generated Car documents. Right-click the GetandTransformDXL agent and choose Run. This agent does two things: First, it generates DXL documents from the Car documents and places the DXL documents in the C:\article\dxl directory; and second, it transforms the newly generated DXL documents to XML files and places them in the C:\article\xml directory.
   Figure 2. A list of transformed XML documents
   
   

Now, let's examine the individual components of what we just did.

Back to top

DxlExporter

Lotus Domino 6.5 ships with a Java utility class called DxlExporter. DxlExporter gives developers a programmatic means to generate DXL from Domino elements. Prior to Lotus Domino 6.5, DxlExporter was available in a separate download called the Lotus XML Toolkit. Those who are using older versions of Lotus Domino may use that version of DxlExporter instead.

In our example, we use DxlExporter inside a Domino Java agent. A Java agent is a Java program that extends the Lotus-supplied base class called AgentBase and that runs inside the Domino framework. Check the Domino Designer help for more information on Java agents.

DxlExporter allows you to export four different types of Domino elements to DXL using the exportDxl methods. The elements are database, document, documentcollection, and notecollection:

public String exportDxl(Database database)
Exports everything in a Domino database to DXL format. This includes design elements and data documents.

public String exportDxl(Document document)
Exports a Domino document to a single DXL document.

public String exportDxl(DocumentCollection documentcollection)
Exports a collection of Domino documents to a single DXL document.

public String exportDxl(NoteCollection notecollection)
Exports a collection of Domino elements. This can include design elements and data documents.

In the case of our example, we use the second version of this method in GetandTransformDXL which, through a For loop, exports one document at a time. We could have easily used a third version of the method, which exports a documentcollection, but that would generate one XML file for all the documents instead of one file for each.

DxlExporter exporter = session.createDxlExporter();
exporter.setForceNoteFormat(false);
exporter.setOutputDOCTYPE(false);
Stream stream = session.createStream();
if (stream.open(DXL_FILE_PATH+ this.getFilename()+ FILETYPE_SUBFIX)) {
	stream.writeText(exporter.exportDxl(doc));
}

Lotus supplies DxlExporter with a number of methods for customizing the output of the DXL. Let's discuss the two that were used in the example: ForceNoteFormat and OutputDOCTYPE.

ForceNoteFormat - DxlExporter.setForceNoteFormat(boolean)

Setting the parameter to true tells the exporter to export each Domino element as a note element. Setting the parameter to false tells the exporter to export each Domino element as its own type. To illustrate this, consider the following example. Setting the ForceNoteFormat property to true as follows:

generates XML that contains the top-level object called note with an attribute value class='document'. The generated DXL document from the car example looks like this:

<note class='document' xmlns='http://www.lotus.com/dxl' version='6.5' maintenanceversion='1.0'
 replicaid='88256F0C0071CEAD'>
…
<note>

On the other hand, when ForceNoteFormat is set to false, DxlExporter exports the top-level element as the Domino element type. Setting the ForceNoteFormat property to false:

generates a DXL document that looks like this:

<document xmlns='http://www.lotus.com/dxl' version='6.5' maintenanceversion='1.0'
 replicaid='88256F0C0071CEAD' form='car'>
...
</document>

NOTE: Setting the ForceNoteFormat property to either true or false does not change the output of containing elements.

OutputDOCTYPE - DxlExporter.setOutputDOCTYPE(boolean)

This appends a DOCTYPE tag along with the SYSTEM and DTD information. This can be useful when the generated DXL is to be handed off to another program or individual to verify the integrity of the DXL. The SYSTEM value can be set with DxlExporter.setDoctypeSYSTEM( ). Notice the reference to the Domino DTD in the DOCTYPE tag.

There is a LotusScript version of the DxlExporter called NotesDxlExporter. It provides virtually the same functionalities as its Java counterpart. It was first released with Lotus Domino 6.

Back to top

Examining the DXL

Now browse to C:\article\dxl\ and open a newly created DXL file (the extension is still XML) in your favorite text editor or browser. Let's examine its structure and contents.

DXL is designed to represent Domino elements in a tree-like, hierarchical structure. It is constrained by the Domino DTD which describes each element in terms of the Domino construct. Because of that, a DXL document is usually not semantically meaningful for your data. Consider this from the car example: Suppose that there is a text field called VIN that stores an alphanumeric value in the Domino document. The exported DXL representation of this field is:

While this is valid XML, it does not represent the true meaning of a vehicle identification number, the unique ID of a car. In fact, the VIN is represented no differently than any other text fields in the document. It is up to the developer to transform a DXL document into an XML file that is semantically sound. For maximum portability, we recommend transforming the DXL document to an XML file that can describe your data more effectively.

Back to top

Transforming DXL

The ability to transform XML is extremely powerful. This function is handled by XSLT (Extensible Stylesheet Language Transformation). If you are not familiar with XSLT and other related technologies, check out http://www.w3.org/Style/XSL/.

In the case of DXL, transformation plays an essential role in making the data meaningful outside of Lotus Domino. In the following sections, we describe the specifics in transforming DXL as well as some tips and tricks.

Overriding the namespace dxl

DXL documents have an XML namespace of dxl. While this namespace value is meaningful to describe a DXL document, it is not useful to describe your XML format. By default, the XSLT engine appends namespace of source XML in the resulting XML. To override that, add the attribute exclude-result-prefixes="dxl" in the <xsl:stylesheet> tag:

Handling text fields and other simple data types

There are seven simple data types defined in the Domino 6.5.1 DTD. These types are:

• Text: Simple string data stored as #PCDATA, break, or non-XML characters.
• Number: Simple number stored as #PCDATA.
• Datetime: Datetime item that maps to a contiguous string, such as yyyymmddThhmmss.
• Textlist: A collection of text elements.
• Numberlist: A collection of number elements.
• Datetimelist: A collection of datetime elements.
• Itemdata: This is used to represent fields that the DTD does not yet handle. For instance, a file attachment stored in a Domino document is represented as an itemdata. The value would be in raw Base64 format.

To add some intelligence to your XSL, you may consider using the choose/when tags to detect the data type and to select the appropriate template to handle it:

	<xsl:choose>
		<xsl:when test="name(child::*)='text'">
			<xsl:apply-templates select="dxl:text" />
		</xsl:when>
		<xsl:when test="name(child::*)=’number’">
			<xsl:apply-templates select="dxl:number" />
		</xsl:when>
		<xsl:when test="name(child::*)='datetime'">
			<xsl:apply-templates select="dxl:datetime" />
		</xsl:when>
		<xsl:when test="name(child::*)='textlist'">
			<xsl:apply-templates select="dxl:textlist" />
		</xsl:when>
		<xsl:when test="name(child::*)='numberlist'">
			<xsl:apply-templates select="dxl:numberlist" />
		</xsl:when>
		<xsl:when test="name(child::*)='datetimelist'">
			<xsl:apply-templates select="dxl:datetimelist" />
		</xsl:when>
	</xsl:choose>

We included templates for a couple of simple types below.

Transforming element value to attribute value

As a general XML convention, top-level elements usually contain an ID-type attribute to identify their uniqueness, for example:

In the DXL document, the VIN number is simply listed as a <text> element. To make that into an attribute in the resulting XML, we do the following: First, test for the document's existence with match="dxl:document". If the document exists, create a car element (because each of our DXL documents represents a car object). Next, add to the car element a vin attribute with the value of the VIN item. Lastly, locate the VIN item using xPath as follows:

<xsl:value-of select="./dxl:item[attribute::name='VIN']/dxl:text/text()" />
<xsl:template match="dxl:document">
	<xsl:element name="car">
		<xsl:attribute name="vin">
			<xsl:value-of select="./dxl:item[attribute::name='VIN']/dxl:text/text()" />
		</xsl:attribute>
		<xsl:apply-templates select="./dxl:item" />
	</xsl:element>
</xsl:template>

Handling multi-value fields

Lotus Domino supports the concept of a multi-value field. This type of field is often referred to as a list. A textlist is the most commonly used type of multi-value field. In our example, we have a multi-value field called Specifications that contains the various options a vehicle has. The following is the multi-value DXL. Notice the set of <textlist> tags inside the item tags.

<item name='Specifications'>
<textlist>
<text>Power locks</text>
<text>AWD</text>
<text>Anti-lock brakes</text>
<text>Automatic windows</text><text>A/C</text>
<text>ABS</text>
</textlist>
</item>

Using field names as element names

Most other Domino fields have a generic DXL representation like this:

<item name='fieldName'>
<fieldType>Acura</fieldType>
</item>

Oftentimes, fieldName is ideal as the element name in the resulting XML:

Thus, using an element from our example, we would have something like this:

<item name='Make'>
<text>Acura</text>
</item>

transformed to this:

The XSL code to do this is as follows:

<xsl:element name="{@name}"> 
	<xsl:apply-templates select="dxl:text" />
</xsl:element>

<xsl:template match="dxl:text">
	<xsl:value-of select="text()" />
</xsl:template>

We want to convert the above to this format:

<Specifications>
<listitem>A/C</listitem> 
<listitem>Anti-lock brakes</listitem>
<listitem>AWD</listitem> 
<listitem>Defrost</listitem>
</Specifications>

In this case, we use:

<xsl:template match="dxl:textlist">
	<xsl:for-each select="./dxl:text">
		<xsl:element name="listitem">
			<xsl:apply-templates select="text()" />
		</xsl:element>
	</xsl:for-each>
</xsl:template>

Displaying the data in a JSP

At this point, we are ready to display the Domino data using a JSP. Start WebSphere Studio Application Developer 5.1 and import ArticleWeb.war as a new Web Project. (For more information on WebSphere Studio Application Developer, refer to the developerWorks: WebSphere Studio zone). Locate and expand the ArticleWeb Project Folder. Double-click the WebContent folder and locate the file dispxmlcar.jsp. Right-click the dispxmlcar.jsp and choose Run on Server.

If you are prompted to choose a version of the server instance, choose WebSphere Application Server 5.1. The server and the application start automatically.

After the application is started, you see an error message in the WebSphere Studio Application Developer's embedded Web browser window. Ignore it because the JSP is expecting a vin parameter in the querystring. To fix this, simply get a vehicle identification number from either the XML files or the Domino database and append it as a querystring to the URL like this:

After you press Enter, you see the result.

Back to top

JSPs and the transformer

Dispxmlcar.jsp provides the basic HTML framework. This is where you would setup your company site masthead and navigation. In the middle is a <jsp:include> for dispxmltable.jsp. This JSP is what displays the middle table that contains the car data.

Dispxmltable.jsp
<%@page import="java.io.*,java.util.*, java.net.*, com.ibm.alphaworks.utils.xml.*" %>
<%
String vin = request.getParameter("vin");
String xml = "c:\\article\\xml\\" + vin + ".xml";
String xsl = "c:\\article\\xsl\\TransformHTML.xsl";

aWTransformer at = new aWTransformer();
at.setXmlin(xml);
at.setXslin(xsl);
at.setWriter(response.getWriter());
at.doTransform();
%>

It uses the vin parameter as a key to locate an XML document in the C:\article\xml\ directory. There is a hardcoded path to the XSL document, TransformHTML.xsl.

NOTE: There are more sophisticated ways to store and retrieve your XML or XSL. One popular method is to use a relational database, such as DB2, to store the XML as CLOBs (Character Large Object). For the sake of not overcomplicating this article, we use the file system.

The actual transformation is handled by a class called aWTransformer. This class is based on the Xalan's sample transformer class and for the most part, should not require any further development from you.

There is no HTML code in dispxmltable.jsp. The HTML table is generated based on the construct in the TransformHTML.xsl stylesheet. This setup allows for a lot of flexibility:

• It abstracts the presentation code from the transformation code.
• The presentation of the data can be modified with XSLT independent of the JSP.
• The same Java code can be used for many different XML data and presentation layouts.

This application works on other J2EE application servers also.

Back to top

Conclusion

Lotus Domino provides developers many integration utilities and tools. In this article, we covered how to use DxlExporter to generate DXL documents, how to transform them into meaningful XML files, and how to display them as JSPs under WebSphere. In the second article, we will discuss in detail how to use the Domino tag libraries to create dynamic JSPs.

Back to top

Download

	Information about download methods

Resources

• Read part two of the article series, "Lotus Domino and IBM WebSphere integration solution: Domino JSP tag libraries."
  
  
• For more information about Domino XML, see the following resources:
  • developerWorks: Lotus article, "DXL roadmap: Understanding Domino's XML language"
  • IBM Redbook, XML Powered by Domino: How to use XML with Lotus Domino
  • Domino Designer help
  
  
• For information about WebSphere, including WebSphere Studio Application Developer, check out the developerWorks WebSphere site.
  
  
• For more information about XML in general, see the developerWorks XML site.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  

About the author

		Jeffrey Lo is an Advisory Software Engineer for alphaWorks, IBM's resource for emerging technologies. Jeff has been with IBM since 1999, spending his waking hours architecting and building applications around Lotus Domino and IBM WebSphere. His responsibilities include the alphaWorks Web site, its content management system, and a number of backend applications. On the weekends, he likes to go biking in California's Santa Cruz mountains and taking photos of the Pacific Coast.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top