The ins and outs of using Java with Domino
By Tony Patton
Java has grown from a buzzword, to a language for creating cute applets that run in your browser, to a full-fledged presence in the development community. It's definitely here to stay. The focus is now more on the back-end, leaving the browser/GUI (Graphical User Interface) development to DHTML (Dynamic Hypertext Markup Language), HTML, JavaScript, and CSS (Cascading Style Sheets).
Lotus has placed its full weight (which is rather large considering IBM's presence) behind the Java language. Full support was added in Domino 5.03 with minor enhancements in each incremental release. The latest release (5.05) includes Java libraries for working with XML (eXtensible Markup Language).
Why bother with Java?
The big question, you may ask yourself, is why bother with Java? I can offer four solid reasons.
Java is object-oriented. Everything is an object. In Domino, there are database objects, session objects, document objects, and so forth. The result is a componentized application with the end-goal of reusability for individual components.
Java offers broader support. There are no other platforms or applications that support the proprietary LotusScript language. On the other hand, the list of Java platforms is seemingly endless.
Java has standard network communication features. Java was developed as an Internet language, so network communication functionality is built into the core language with a common protocol of TCP/IP (Transmission Control Protocol/Internet Protocol). You can create network savvy applications in no time.
Java is portable. We've touched on this point, but it deserves to be repeated. Java code developed in Domino can survive outside the Domino environment. Try that with LotusScript.
Plus, Java has skill-set transportability. You can transfer your Java skill-set in addition to your Java code. It's always a good idea to make yourself more marketable with a new skill.
Domino Designer
One of the excellent additions to R5 is a separate development environment. This includes a rudimentary Java editor and compiler. The best part of it is syntax checking and error reporting.
You may want or need the more advanced features of third party IDEs (Integrated Development Environments), so you do have that option. That is, an IDE such as Visual Café, Jbuilder, or VisualAge for Java can be used to develop Domino Java code. Actually, VisualAge includes directions for working with Domino Java classes.
The Domino Designer allows Java code to be typed directly into it. It also allows Java classes to be imported from the file system. Basically, it has the same layout as the LotusScript editor. Class files in the current project/agent are organized in the left frame/window under the tab labeled Classes. Notice, our agent uses the standard name assigned to all new classes created: JavaAgent.
Domino provides the standard structure for a Java agent when Java is selected as the Run type for an agent. Figure A shows the structure provided.
FIGURE A
Here's the Domino Designer Java environment.
It provides the appropriate import statement (import lotus.domino.*) needed to work with the Domino classes. Also, the main entry point for a Domino Java agent is the NotesMain method, and it's provided. A try/catch block is provided along with two objects: Session and AgentContext. The Session object represents the environment for the current program, and AgentContext represents the current environment for the agent.
Additionally, the reference tab next to the classes tab is available for online help during development. Figure B shows the reference tab opened to the Domino classes.
FIGURE B
The Domino Designer reference tab is opened to the Domino classes.
Core Java and XML classes are available for viewing as well. The reference tab lists the classes by their package names with twisties available to expand to the classes and their associated methods and properties.
I've got a couple of other comments regarding the Designer interface. You may have noticed four buttons at the bottom of the window: Edit Project, New Class, Export, and Compile. The Edit Project button allows classes to be removed and added to the current code. The New Class button adds a new class to the agent. Compile compiles the code into bytecode, and Export allows it to be saved to a local drive. Above the buttons is the error box where errors encountered during compilation are listed with the errant line numbers to the right.
Java Console
All developers should thoroughly debug their code to ensure proper functionality. The Domino client offers the Java Console for working with Domino Java code. All system output via print statements can be viewed in it. All error messages will be displayed in it as well. It's available via the File->Tools->Show Java Debug Console drop-down menu. Figure C shows the drop-down selection
FIGURE C
The drop-down menu activates the Java Debug Console.
Figure D shows the actual window.
FIGURE D
Here's the Java Console window.
Class files
Java class files are most often distributed via JAR (Java ARchive) files. This is a compression format unique to Java, much like WinZip or Microsoft CAB files. Well, the Domino Java classes are distributed in a JAR file. They're located in the base directory of your Domino R5 installation.
Table A shows the files that are available.
TABLE A: Java files
File name
Description
dservlet.jar
Domino Java Servlet classes
i18n.jar
Core SUN Java classes
jsdk.jar
SUN Java Servlet classes
LotusXSL.jar
XSLT Processor (Xalan) classes
Notes.jar
Domino Java classes
rt.jar
Core SUN Java classes
tools.jar
Core SUN Java classes
XML4j.jar
XML Parser classes (Xerces)
If you'll be working with Domino Java outside of the Domino environment, you must place the appropriate class files in your CLASSPATH environment variable. You'll need the Notes.jar file for using Domino Java classes.
Our first Domino Java agent
Okay, we've taken a look at the basics of utilizing Java in Domino. Let's turn our attention to a simple Domino Java agent. We will construct an agent that accesses all person records in the name and address book (names.nsf) and displays the first and last name of the person(s).
As an example, I've numbered a piece of code. Following the code, you'll find each line explained next to its corresponding number.
1. import lotus.domino.*;
2. import java.io.PrintWriter;
3. public class JavaExample extends AgentBase
{
4. public void NotesMain()
{
5. try
{
6. Session s = this.getSession();
7. PrintWriter pw = this.getAgentOutput();
8. Database db = s.getDatabase("","names.nsf");
9. if (db != null)
{
10. View vw = db.getView("People");
11. if (vw != null)
{
12. Document doc = vw.getFirstDocument();
13. String fname = null;
String lname = null;
14. int c = 0;
15. while (doc != null)
{
16. c += 1;
17. fname = doc.getItemValueString("FirstName");
lname = doc.getItemValueString("LastName");
18. pw.println("Person #" + c + " : " + fname + " " + lname);
19. doc = vw.getNextDocument(doc);
}
20. vw.recycle();
}
21. db.recycle();
}
22. s.recycle();
} catch(Exception e) {
e.printStackTrace();
}
}
}
Here's the explanation:
Make the Domino Java classes available to the agent;
The PrintWriter class of the Java.io package;
Class declaration; everything in Java is a class/object;
The entry point for a Domino Java agent is the NotesMain method;
Beginning of the try/catch block;
Create a Session object;
PrintWriter object is used for output; we can view the output in the Java console;
Create a Database object; we will use the name and address book;
Continue only if the database was properly instantiated;
Create a View object using the list of people in the NAB;
Continue only if the View object has been properly instantiated;
Retrieve the first document in the view;
Declare String objects to be used for field values;
Declare variable to be used as a counter;
Loop through all documents in the view;
Increment the counter variable;
Retrieve the contents of the FirstName field as a String;
Display the name and counter variable;
Get the next document from the view;
Return the memory used by the View object to the system;
Return the memory used by the Database object to the system;
Return the memory used by the Session object to the system.
Figure E shows the output of the example as seen in the Java Console.
FIGURE E
Here's the output from the example.
Conclusion
Java is a powerful language that can be used to extend the already powerful Domino environment. In this article, we've looked at the very basic application of Java in Domino: an agent via Domino Designer. Domino Java can be utilized in applets, standalone applications, and servlets as well. The capabilities are only limited by your imagination. For more information on Domino and Java, please refer to my latest book, Domino Development with Java, available through the publisher, Manning Publications, at http://www.manning.com/patton2.
