Writing Java to build applications using IBM Lotus Domino Designer

Writing Java to build applications using IBM Lotus Domino Designer Oscar I. Hernandez IBM Software Group Staff Software Engineer, Lotus Notes/Domino Austin, TX August 2009 © Copyright International Business Machines Corporation 2009. All rights reserved. Summary: The objective of the article is to help the traditional LotusScript® developer, who typically has no hard-core development background, move to JavaTM. With little or no existing Java knowledge, this article will help you get started on developing Java applications in IBM® Lotus® Domino®.

Table of Contents 1 Introduction.................................................................................................................. 2 2 Java language.............................................................................................................. 2 2.2 Line by line explanation ........................................................................................ 3 2.3 Java language basics........................................................................................... 4 2.4 Differences between LotusScript and the Java language .................................. 10 3 Examples................................................................................................................... 10 3.1 Example 1: Sending an email ............................................................................. 10 3.2 Example 2: Cycling through a Notes view........................................................... 16 3.3 Example 3: Generate a report with mail database information ........................... 21 4 Other essentials......................................................................................................... 30 5 Conclusion................................................................................................................. 31 6 Resources.................................................................................................................. 31 7 About the author ........................................................................................................ 31

1

1 Introduction For IBM Lotus Notes application developers, LotusScript and the LotusScript classes are invaluable when designing Notes applications. The LotusScript API allows you to interact programmatically with databases, documents, and even with design elements. As Javahas continued to emerge as a mainstream programming language, more and more Notes application developers are making the move to Java. This article is intended for LotusScript developers who want to start programming with Java in IBM Lotus Domino. It is assumed that the reader is an experienced LotusScript programmer. This document consists of three main sections: Java Language, Examples, and Other essentials. Java programmers may feel comfortable enough to jump into the Examples section, while beginners should review the Java Language section first.

2 Java language Released in 1995, Java is an object-oriented programming language that was created to address the need for platform independence. This was accomplished by compiling the Java source code into bytecodes, which could then be interpreted by any Java Virtual Machine (JVM) on any platform. Hence, as long there was a JVM implemented for the desired platform, it could run any Java application. For more information, visit The History of Java Technology. Java's syntax is similar to C, and its object-oriented implementation is similar to C++, making it an easy-to-learn language for C/C++ programmers. LotusScript developers, however, will find the Java syntax quite different from LotusScript. Since this article focuses on using Java in Lotus Domino, the examples presented will be in the context of Lotus Domino. Let’s begin with the classic "Hello World" example. When you create a new Java agent in Domino Designer, you received the template code on the left-hand side of table 1. The code on the right-hand side has been modified to accommodate the "Hello World" example.

2

Table 1. Hello World example Template Java Agent Code

Hello World Java Agent Code

import lotus.domino.*;

import lotus.domino.*;

public class JavaAgent extends AgentBase {

public class JavaAgent extends AgentBase {

public void NotesMain() {

public void NotesMain() {

try { Session session = getSession(); AgentContext agentContext = session.getAgentContext();

try { Session session = getSession(); AgentContext agentContext = session.getAgentContext();

// (Your code goes here)

}

}

// (Your code goes here) System.out.println("Hello World!");

} catch(Exception e) { e.printStackTrace(); } }

}

} catch(Exception e) { e.printStackTrace(); }

2.2 Line by line explanation Let's examine the code, line by line: import lotus.domino.*; Java uses the import statement to include other Java classes. In this case, all the lotus.domino classes are available to the agent code. Java classes are usually contained within JAR files. There are several methods for making JAR files available to an agent. Refer to the “Using external JAR files with Java agents”paragraph in Section 4 of this paper for information on JAR files. public class JavaAgent extends AgentBase { Java is an object-oriented programming language. This line demonstrates that, when you create a Java agent, it creates a JavaAgent class, which will be the main class where you will write your Java code. You may also notice that the JavaAgent class extends the AgentBase class. Since Java is object-oriented, extending the AgentBase class gives us an entry point into the agent, which brings us to the next line. public void NotesMain() { The NotesMain method is the entry point to the agent. Here we override the AgentBase method definition with our own. try { In Java, error handling is handled through try and catch blocks. Methods that throw exceptions in Java must be surrounded by a try block, and every try block must have a corresponding

3

catch block. The try and catch blocks are required in the "Hello World" example because the getAgentContext method throws a NotesException. To see which Domino methods throw an exception, refer to their method signature in the Domino Designer Help file. Session session = getSession(); The getSession method from the AgentBase class allows us to create a session object. The Java Session class is similar to the LotusScript NotesSession class. AgentContext agentContext = session.getAgentContext(); The AgentContext class lets you get a handle to the current database (using its getCurrentDatabase method). In LotusScript, this additional class is not required to get a handle to the current database. // (Your code goes here) The thing to note with this line is that a single line comment begins with "//". For multiple line comments we use "/*" at the beginning and end with "*/" (similar to C++). System.out.println("Hello World!"); This is the Java method used to print to the console. To open the Java console in Notes, select Tools > Show Java Debug Console, from the menu. The System.out.println method is similar to the LotusScript Print method. } catch(Exception e) { This is the corresponding catch statement for the try above. e.printStackTrace(); In the catch block, you can opt to handle the exception as you wish; in this case, we are simply printing out the stack trace.

2.3 Java language basics Java provides eight primitive types: byte, short, int, long, char, float, double, and Boolean. Table 2 describes each type and indicates the LotusScript equivalent (if any). Table 2. Primitive types and LotusScript equivalents Java Primitive Type

Java Description

LotusScript Equivalent

byte

8-bit signed two's complement integer (-128 to 127)

Byte Similar: 8-bit Difference: unsigned (0 to 255)

short

16-bit signed two's complement integer (-32,768 to 32,767)

Integer Similar: 16-bit, signed (-32,768 to 32,767)

int

32-bit signed two's complement integer (-2,147,483,648 to 2,147,483,647)

Long Similar: 32-bit, signed (-2,147,483,648 to 2,147,483,647)

long

64-bit signed two's complement

N/A

4

integer (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807) char

single 16-bit Unicode character

N/A However, LotusScript does provide a String type which can contain multiple characters.

float

single-precision 32-bit IEEE 754 floating point

Single Similar: single-precision 32-bit floating point

double

double-precision 64-bit IEEE 754 Double floating point Similar: double-precision 64-bit floating point

Boolean

true or false value

Boolean Similar: true or false value

Operators Java has a rich set of operators. Table 3 shows merely a subset of its operators along with the description and LotusScript equivalent. For a complete listing, visit the Java Tutorials Operators page. Table 3. Java operators Java Arithmetic Operator

Description

LotusScript Equivalent

=

Assignment

=

+

Addition

+

++

Increment

N/A

+=

Addition assignment

N/A

-

Subtraction (also unary minus)

-

--

Decrement

N/A

-=

Subtraction assignment

N/A

*

Multiplication

*

*=

Multiplication assignment

N/A

/

Division

/

/=

Division assignment

N/A

%

Modulus

Mod

%=

Modulus assignment

N/A

Java Relational Operator ==

Description Equal

LotusScript Equivalent =

5

!=

Not equal

, >


Greater than

>

>=

Greater than or equal to

>=, =>