One of the most important moves Lotus has made to ensure the continued success of Notes/Domino is the company’s efforts to integrate open standards into the product. Lotus began supporting Java and HTML in 4.6, with DHTML and comprehensive Java support added in R5. Lotus continues its trend of embracing open standards with XML support in Domino 5.03. And, if you don’t think open standards are important to the future of software development, consider the fact that Microsoft’s mammoth new .NET initiative revolves around XML. Domino and XML are natural partners with each working at a common level: the document.

What Is XML?

XML stands for Extensible Markup Language. Many Java pundits like to positively compare the two technologies. Java is a platform-independent development language for building applications, and XML is a platform-independent language for describing data. To put it simply, Java is portable code and XML is portable data. XML has two primary purposes: to separate data from presentation and to transmit data between applications. It allows business and back-end database programmers to concentrate on the data and let others concern themselves with presentation. Domino, although its database system is proprietary, can exchange data with the world via XML. All necessary information is included in the XML.

Before I go any further with a discussion of XML and Domino, I need to provide a short overview of document type definition (DTD) and XML schemas. These two technologies are used to define what is appropriate content for an XML document. They outline the acceptable structure of XML, including the available elements, attributes, and possible values. DTDs are left over from XML’s ancestor

Standard Generalized

Markup Language (SGML). The DTD syntax is a bit arcane, and it does not conform to standard rules of XML. On the other side of the fence are XML schemas. These are based on a newer technology that allows more flexibility while conforming to standard XML rules.

One last general note I should offer regarding XML before I move on pertains to the issue of well-formed and validated XML documents. The term well-formed means it

adheres to a strict XML rule that sets it apart from other markup languages such as HTML. Well-formed means that every element must have a closing element, so an element like document must have the corresponding closing document element: Both validated and nonvalidated XML documents signal whether a DTD or XML schema has been utilized to verify its contents. Validity is not a requirement. (For more information on XML see “” and
“Doing E-business with XML Schemas and SOAP” in the March 2000 and September 2000 issues of Midrange Computing.)

Domino Embraces XML

Version 5.03 of Domino Designer and Server included full XML support in the form of an industry-standard XML parser, Xerces’ XML4J, as well as new methods to existing Domino Java objects. Xerces is an XML parser that utilizes the Java programming language. A parser is a tool that reads an XML source (in the form of a document), analyzes its structure, and presents it in a form that you can use. The result of the analysis depends on the type of parser you are using. I will give you a closer look at the two types of parsers: Document Object Model (DOM) and Simple API for XML (SAX). The difference between the two is very simple to explain. A DOM parser accepts an XML document and returns a tree structure (DOM structure) that represents the elements of the XML document. This structure is stored in memory, allowing easy access to all elements of the document. DOM provides a variety of functions you can use to examine the contents and structure of the document. Conversely, SAX is event-based. Events are generated at various points in an XML document. It is up to the programmer to decide how to handle these events. Events are generated at the start and end of a document, at the start and end of an element, when the parser encounters characters inside an element, as well as at several other points. The programmer decides what events to handle and how they are handled.

At this point, you may be asking why there are two approaches. Does it matter which parser is used? The major difference is in the area of memory usage. DOM needs memory to store its tree structure, so the amount of memory needed coincides with the size of the XML document. SAX stores no structure, so the memory used depends on your code. DOM should be used when you need to know about a document’s structure or manipulate portions of a document. You should also use DOM if you will need to use information from a document more than once. The SAX parser should be used when only a few elements need to be extracted from a document on a one-time basis. The Xerces parser can be used in DOM or SAX mode.

The Real Thing

It’s time to move on to real code. As you can see in Figure 1, I will show you an example that accesses XML data via SAX and brings it into the Domino environment. This code runs as an agent in Domino and is invoked from a browser. (XML is accessed through a URL.) Figure 2 illustrates the output generated by the sample agent in Figure 1. The code is comprised of two classes NotifyStr, which is defined at statement 3 and handles SAX calls, and SAXinAction, the main Domino agent, which is defined at 17. The XML data is actually data from a Domino view via the ViewEntryMethod, but any XML source could be used with the code slightly altered. Another example could be receiving a purchase order or


The slash (/) signifies a closing element.
Also, an empty element can include the slash in its designation:

stock quotes formatted as XML. (Note: To use this example in your environment, the URL at label 21 must be changed to reflect your server and database setup.)

It is also possible to send information from Domino to another system via XML. I will show you how to accomplish this task in my next example, which is shown in Figure
3. In this example, I will send the first and last name of all persons in my name and address book (a.k.a. the Domino Directory). The code defines the Example2 class, which basically reads through the People view of my Domino Directory and outputs XML. I will use XML, so the data must be properly formatted. Each entry will exist as a name element. A name element will contain a first and last element. Take a look at the code; as in Figure 1, the code appears on the left with an explanation of what key statements are doing on the right.

What Is XSLT?

As you begin to work with XML, yet another acronym you’ll need to learn is XSLT, Extensible Stylesheet Language Transformations. The key words in the name are styling and transformation. An input document (XML) is transformed to another format and styled (or presented) accordingly. XSLT transformation of an XML document into another format. The new format can be XML, HTML, Dynamic Hypertext Markup Language (DHTML), ASCII, PDF, a sound file, or any other imaginable format. XML facilitates the interchange of structured data between disparate systems. XSLT enables and empowers interoperability.

XSLT takes advantage of another technology called XPATH, which is used to decided which items in a source document are selected for transformation and styling. It has an extensive syntax that is beyond the scope of this article. In addition, you’ll need to know about Extensible Stylesheet Language (XSL), an aspect of the XSLT specification. XSL is a stylesheet (an XSL file usually has a .xsl extension) that signals how the tranformed document should be styled or presented.

Domino and XSLT

Domino 5.03 was the first release to include XSLT support, which came with the inclusion of the Xalan processor (formerly called LotusXSL). The Xalan processor accepts the input document (usually XML), which stylesheet to be used, and where the output (transformation) is to be stored. Figure 4 shows a sample XSLT document that will be transformed by the agent in Figure 5. Figure 4 includes an explanation of important parts in the right-hand column. Now, take a look at the code that transforms the stylesheet by examining the agent code in Figure 5. The explanations in the right-hand column will walk you through the code. When you run the agent shown in Figure 5, you get the output shown in Figure 6.

Domino Objects

In addition to adding the parser and processor, Lotus has made enhancements to existing Domino Java objects that will benefit those who want to use XML. Programmers can work with the Document, MIMEEntity, EmbeddedObject, Item, and RichText classes to generate, parse, and transform XML. These are available via the generateXML, parseXML, and transformXML methods.

DXL: The Future

The future of Domino and XML is Domino’s DTD, known as DXL. It is a universal format for Domino, i.e., the XML representation of Domino data. DXL will allow the export, import, and modification of Domino elements both to and from a Domino environment.

One possible application of DXL is the exchange of Domino data with a non- Domino system. This exchange would encompass a few steps. First, the Domino data

would be retrieved in the DXL format. XSLT would then be used to translate the resulting DXL into the proper format for conversing with the other system; this format may well be XML. Once the other system receives the XML, it will use its own XSLT to transform it into a format more acceptable to it.

Although DXL is still in the development stages, you can get a glimpse of its look and feel through a couple of methods added in Domino. The ReadViewEntries command is applicable to Domino view and outline elements rendered in a Web browser client. The view or outline has the command appended with a question mark (?) like this: Figure 7 demonstrates this command issued for a view in a custom application. It shows the contents of a view displayed via DXL in the Microsoft Internet Explorer browser. The top element of the XML document is viewentries. This element contains all other elements in the document. Each row in a view is contained in a viewentry element, and each column of data in the row is contained in an entrydata element. This same format will be taken farther in the Domino environment; it will be used to describe form data as well as other data. Figure 8 is a possible format for a simple Notes mail memo.

DXL is used to describe Domino data as well as Domino design elements. It will enable the creation of new Domino design elements like views or forms.

In the past, this was only available via the C API.

Playing to Win

The developers at Lotus have only just begun to wrap their arms around XML, and it is indeed a good beginning. The current XML supports the power of XML to the Domino development community. The future promises more flexibility with the further enhancements provided by DXL. Lotus has announced further DXL support in an upcoming version of Domino. Also, XML will be a supported format for the enterprise connectivity tools Domino Enterprise Connection Services (DECS) and Lotus Enterprise Integrator (LEI).

REFERENCES AND RELATED MATERIALS

• IBM’s alphaWorks Web site: www.alphaworks. ibm.com

• IBM’s XML zone Web page: www.ibm.com/xml

• Lotus’ DXL Resources page: www.notes.net/dxl

• Lotus’ Web guide to XML: www.lotus.com/xml

• The Apache XML Project: www.apache.org (This site includes information on both Xalan and Xerces.)

• XML Powered by Domino: How to Use XML with Lotus Domino, Redbook (SG24- 6207-00), available at www.redbooks.ibm.com/abstracts/ sg246207.html

• XML.com: www.xml.com

http://dominoServer/dominodatabase.nsf/
elementName?ReadViewEntries

1. import org.xml.sax.AttributeList;

import org.xml.sax.HandlerBase;

import org.xml.sax.Parser;

import org.xml.sax.Locator;

import org.xml.sax.SAXException;
2. import java.io.PrintWriter;
3. public class NotifyStr extends HandlerBase{
4. boolean flag = false;

boolean firstTime = true;

PrintWriter pw = null;
5. public NotifyStr(PrintWriter passed) {

pw = passed;

}

6. public void startDocument() throws SAXException {

}

7. public void endDocument() throws SAXException {

pw.println("");

pw.println("");

}

8. public void startElement(String name, AttributeList amap) throws SAXException {
9. if (name.equalsIgnoreCase("viewentry")) {

pw.println(""); }
10. else if (name.equalsIgnoreCase("text")) {

flag = true; }

else if (name.equalsIgnoreCase("datetime")) {

flag = true; }

else {

flag = false; }
11. for (int i = 0; i < amap.getLength(); i++) {

String attname = amap.getName(I);

String type = amap.getType(i);

String value = amap.getValue(i);
12. if (firstTime == true) {

pw.println("

");

pw.println("

");

firstTime = false;

} } }

13. public void endElement(String name) throws SAXException {
14. if (name.equalsIgnoreCase("viewentry")) {

pw.println(""); } }
15. public void characters(char[] ch, int start, int length) throws SAXException {

if (flag == true) {
16. pw.println("

");

flag = false;

} } }

import lotus.domino.*;

import java.io.PrintWriter;
17. public class SAXInAction extends AgentBase {

public void NotesMain() {

try {
18. PrintWriter pw = this.getAgentOutput();
19. com.ibm.xml.parsers.SAXParser parser = new com.ibm.xml.parsers.SAXParser();
20. NotifyStr nStr = new NotifyStr(pw);

parser.setDocumentHandler(nStr);
21. String url = "http://DominoServer/names.nsf/People?ReadViewEntries";
22. pw.println("");

pw.println("");

pw.println("");
23. parser.parse(url);

pw.println("");
24. } catch(Exception e) {

e.printStackTrace(); } } }
======================================================================================

1. Import the appropriate SAX classes into the code.
2. The PrintWriter object will be used to display the output.
3. The NotifyStr Class is declared.
4. I set the flag variables. These flags are used to signal when elements are to be handled and so forth.
5. Constructor method is called when the NotifyStr object is instantiated (see statement 20).
6. The startDocument method is triggered at the beginning of an XML document.
7. The endDocument method is triggered at the end of an XML document.
8. The startElement method is fired whenever a new element is encountered.
9. You are interested in ViewEntry elements; these signal the beginning of a row in a Domino view.
10. The text elements designate column data. The flag is set accordingly so the data will be displayed.
11. A FOR loop is used to access all attributes of an element; this program doesn't use attributes, but it
is helpful to see how it works.
12. If it is the first time through, the program will output the beginning of an HTML table.
13. The endElement method is triggered at the end (slash) of an element block.
14. It is the end of a row if it is the end of a ViewEntry element, so end the HTML table row.
15. The SAX characters method is triggered when characters are encountered in an element.
16. This line displays the appropriate characters in a HTML table cell.
17. The beginning, or declaration, of the Domino agent.
18. The PrintWriter class will be used to send output to the browser.
19. Create a new SAX parser object.
20. Create a new instance of the object for handling SAX events.
21. This is the URL to be used as the XML source.
22. Send HTML to the requesting client.
23. Parse the XML document.
24. Handle any errors encountered.

Figure 1: This sample Domino Java agent accesses XML data from a Domino view.

Figure 2: When the agent is called from a Web browser, it creates this output.

import lotus.domino.*;
1. import java.io.*;

public class Example2 extends AgentBase {

public void NotesMain() {

try {

Session s = this.getSession();
2. Database db = s.getDatabase(“”,”names.nsf”);
3. View vw = db.getView(“People”);

if (vw != null) {
4. DataOutputStream outFile =

new DataOutputStream(

new BufferedOutputStream(

new FileOutputStream(“c:people.xml”)));
5. outFile.writeBytes(“

outFile.writeBytes(“ encoding=”UTF-8”?> ”);
6. outFile.writeBytes(“ ”);

Document doc = vw.getFirstDocument();
7. while (doc != null) {
8. String firstName = doc.getItemValueString(“FirstName”);

String lastName = doc.getItemValueString(“LastName”);
9. outFile.writeBytes(“ ”);
10. outFile.writeBytes(“” + firstName + “”);

outFile.writeBytes(“” + lastName + “”);

outFile.writeBytes(“ ”);
11. doc = vw.getNextDocument(doc); }
12. vw.recycle();

outFile.writeBytes(“”);

outFile.close(); }

db.recycle();

s.recycle();

} catch (Exception e) {

e.printStackTrace(); }}}

======================================================================================

1. The necessary class files used to work with files are imported.
2. The name and address book is accessed.
3. This line defineds the people view as the view to be used, since only individuals are wanted.
4. The output stream is set to a file on the local hard drive.
5. The XML header information is written to the file.
6. The beginning XML tag for the people element is written.
7. All documents in the view are accessed via a loop. This line tells the program to loop through all
documents in the view.
8. The first name is retrieved from the person document.
9. The beginning XML tag for the name element is written.
10. The first name value with its element tags is written.
11. The next document from the view is retrieved.
12. The memory used by the view object is returned to the system.

Figure 3: This Domino Java agent sends XML data to another system.




1.
2. http://www.w3.org/1999/XSL/Transform" version="1.0">
3.
4.

" + new String(ch,start,length) + "


5.

#	Date			Author






6.
7.
8.


9.


10.


11.
12.
13.

======================================================================================

1. This is the required header; it signals the XML version.
2. This is the namespace declaration, using standard XML.
3. All root elements of the XML document will be evaluated.
4. This is the beginning of the HTML document; this will be output.
5. All elements using other templates will be processed in the stylesheet. There are template designations
for different elements.
6. This is the end of the template.
7. This is the instructions for processing viewentries elements.
8. All children elements of the viewentries element are processed.
9. This is the instructions for processing viewentry elements.
10. All children elements of the viewentry element are processed.
11. This is the instructions for processing entrydata elements.
12. The datetime elements are selected and displayed.
13. Text elements are selected and displayed.

Figure 4: This is a sample XSLT document that will be transformed by the agent in Figure
5.

1. import org.apache.xalan.xslt.*;

import com.lotus.xsl.XSLProcessor;

import lotus.domino.*;

import org.apache.xalan.xslt.XSLTResultTarget;

import java.io.PrintWriter;
2. public class Example3 extends AgentBase {

public void NotesMain() {

try {
3. PrintWriter pw = this.getAgentOutput();
4. com.lotus.xml.xml4j2dom.XML4Jliaison4dom XMLLiaison = new

com.lotus.xml.xml4j2dom.XML4Jliaison4dom();
5. XSLProcessor xp = new XSLProcessor(new com.lotus.xml.xml4j2dom.XML4Jliaison4dom());

String url = "String url = "http://DominoServer/xmlact.nsf/All?ReadViewEntries";
6. XSLTInputSource xmlSource = new XSLTInputSource (url);
7. String xslUrl = "http://DominoServer/midrange.nsf/Attachments/VIEW/$File/view.xsl";
8. XSLTInputSource xslSheet = new XSLTInputSource (xslUrl);
9. XSLTResultTarget tout = new XSLTResultTarget(pw);
10. xp.process(xmlSource, xslSheet,tout);

} catch(Exception e) {

e.printStackTrace(); }}}

============================================================================

1. The appropriate XSL classes are imported.
2. This is the Class/Agent declaration.
3. The PrintWriter object will be used to display output.
4. The appropriate object for utilizing XSL is created.
5. The create XSL processor object is created.
6. This defines the XML source document to be transformed.
7. This is the URL of the XSL stylesheet to be used. The stylesheet is stored in the Domino database as an
attachment. Your stylesheet should be stored in your Domino database.
8. The XSL source object is set.
9. This line signals where the output of the transformation will be sent.
10. The transformation is executed.

Figure 5: This agent transforms the XSLT document in Figure 4.

Figure 6: This is the output displayed as a result of opening the Figure 5 agent from Internet Explorer.

Figure 7: Use the Domino ReadViewEntries URL command to display a Domino view via DXL.

19991205T091500



DXL is great



Tony Patton



Somebody else


Figure 8: This is an example of a Domino form presented in DXL.

Also Read

Open Source Starter Guide for IBM i Developers: Language Basics

Open Source Starter Guide for IBM i Developers: Ruby and IBM i, An Introduction

Open Source Starter Guide for IBM i Developers: i Object!