Lotus Domino Release 5.0 A Developer’s Handbook phần 6 pot

On accessing the applet, JavaScript can also access the Java public
methods/properties of the applet:
• document.applets.Hi.methodname
• document.applets.Hi.variable
Obvious advantages include repainting applets with new data at runtime,
without roundtrips to the server via submits.
Accessing Java/CORBA Applets via LiveConnect
Consider the current Notes Client Programmability model. The Domino
Object Model (DOM) is accessed by LotusScript in the event handlers. On
the Web, the scripting language is JavaScript, which has no interface to the
Domino Object Model (DOM). Java has an interface to the DOM, but the
API’s are remote. This is where you can utilize a CORBA applet.
A CORBA-enabled applet can access a remote Domino Session object and, in
combination with LiveConnect, make this property available to JavaScript
via a public property or method. An HTML page can now have a persistent
session with the Domino server via JavaScript and utilize the DOM, without
the need to submit the page to the server for each transaction.
Example
The following example illustrates how LiveConnect can be used in the Notes
client. It has been taken from the Lotus Domino Toolkit for Java/CORBA 2.0.
338 Lotus Domino Release 5.0: A Developer’s Handbook
The Rich Text field on the document contains a 1 pixel square embedded
applet. The applet code is minimal as you can see below:
import lotus.domino.*;
public class PinpointApplet extends lotus.domino.AppletBase {
public void notesAppletInit()
{
setLayout(null);
setSize(1,1);
}
}

The important thing here is that the applet extends the AppletBase class.
This class implements the method
AppletBase.openSession()
which we
will use to get a Domino session object.
The Rich Text field on the document in the figure also has a button that,
when clicked, locates the applet, passes the openSession() method to it and
then accesses the Domino Object Model through JavaScript. You can see all
the JavaScript code for that button.
// Sample JavaScript code accessing back-end data via Java
// Retrieves the first or second database in the DBDirectory
{
// Once session is obtained, we can utilize any class
// in the Domino Object Model. Can also
// use document.applets[0].openSession(user, pwd);
var s = document.applets[0].openSession();
if ( s == null ) {
window.defaultStatus = "Unable to connect to server";
}
// Update a field on the form
document.forms[0].Platform.value = s.getPlatform();
var dir = s.getDbDirectory("");
// Use introspection to retrieve static constants
// such as lotus.domino.DbDirectory.DATABASE
var dirclass = dir.getClass();
Chapter 10: Programming for Domino 339
var dbcode = dirclass.getField("DATABASE").getInt(null);
var db = dir.getFirstDatabase(dbcode);
// For fun, switch between first and second DB each time
// button is clicked

if ( document.forms[0].DatabaseTitle.value ==
db.getTitle() ) {
db = dir.getNextDatabase();
}
db.open();
document.forms[0].DatabaseTitle.value = db.getTitle();
var server = db.getServer();
if ( server == "" ) server = "Local";
document.forms[0].DatabasePath.value = db.getFilePath() +
" on " + server
}
Once JavaScript has retrieved the session object reference, it can utilize the
full Domino Object Model in the JavaScript code.
In the code above, the JavaScript code uses the Session object to access the
following data, which is placed into the respective fields on the form.
• Platform of the Domino server
• Title of the first or second database on the Domino Server
• File path of the first or second database on the Domino Server
From a performance perspective, the applet initially takes a small amount of
time to load from the server. Once it is loaded and initialized, however,
access to the remote session object is fast.
For the button to implement the JavaScript, the Use JavaScript When
Generating Pages option must be selected.
340 Lotus Domino Release 5.0: A Developer’s Handbook
The applet and the button with the JavaScript code can be placed in the form
design, so that every document created automatically contains them. The
applet can be in a hidden paragraph, as users do not need to see it.
It is advisable to place complex code into a public method within the applet
to correctly handle Java Exception conditions.
This method could also be used for hiding JavaScript implementation code

as Java inside an applet.
If the form had many applets, the one session reference could be shared
among the applets via the InfoBus technology.
External Tools
The API for Domino and Notes
The C and C++ API for Domino and Notes allows you to write a program
that processes data in a Domino database, or moves data in and out of
Domino. The API accesses the Domino database layer, much as the Domino
Object Model itself accesses it. You can also use the API to access the server
software, the Tools menu in the workstation software, and the File Types list
in the File Export dialog box.
Note
Because Domino R5.0 supports a CORBA/IIOP architecture, you are
also able to run API programs through the Web. In this case, the client uses
the server API’s. For more information about CORBA/IIOP architecture,
read Chapter 11: Advanced Domino Programming.
You can write an API program to do the following:
• Extract external data, reformat it, and store it in the Domino database.
For example, you can retrieve information from SQL records.
Chapter 10: Programming for Domino 341
• Extract Domino data, reformat it, and store it in an external application.
For example, you can retrieve Notes workflow status data into a word
processor or executive information management (EIS) system.
• Add commands to the File - Tools menu.
For example, when a user chooses your new command, Domino can
launch your program and pass user context information to it, such as
which view is active, whether the user is editing a document, and which
field contains the cursor. Your program can compute new values and
enter them into Domino fields.
• Implement server add-in tasks.

For example, you can implement a task that takes conditional actions
beyond Notes background macro capabilities. A server add-in task
functions as a daemon. It has no user interface and runs in the
background like other server tasks.
• Create a custom file export format.
For example, when a user selects your new file type in the Notes File
Export dialog box, Domino launches your program and exports data to it.
For more information about the API products refer to the documentation
found at:
/>Summary
In this chapter we have covered some of the basic methods for programming
the Domino Object Model using LotusScript and JavaScript. In the next
chapter we will cover some of the more advanced methods, such as Java,
CORBA and the LSX toolkit.
342 Lotus Domino Release 5.0: A Developer’s Handbook
This chapter will discuss some of the more advanced methods of coding
applications for Domino. We will cover Java, CORBA/IIOP, OLE
automation, and writing your own LotusScript Extensions using the LSX
toolkit.
Java
As the Web evolves, Java becomes a more important and more commonly
used programming language. Domino offers you the option to write your
applications in Java. For example, you can write your Domino agents in Java.
Domino supports Java programs written in Java 1.1.x.
About Java Domino Classes
Java Notes classes are created by modifying some of the LotusScript
Extension (LSX) architecture to include a Java “adapter” to compose the new
Java Domino classes. The Java Domino classes have similar functions to
some of the LotusScript Domino back-end objects. You can use these classes
from any Java program — within the Notes Designer environment or outside

of it — as long as Notes Release 5 is installed on the machine.
Internally, Java Notes classes execute the same C++ code as the LotusScript
Domino back-end objects, only the language syntax is different.
A Java program is generally made up of a number of files. You must
designate one as the Base Class, which is the starting point for the Java
program. For efficiency, typically for improving applet download speeds,
you can bundle all of the class files and additional resources (for example
GIF files) into a single compressed Java Archive file. The imported Java files
can be of the following types:
• Class - *.class
• Archive - *.jar
For example, when you write a Java agent program, the class you write must
extend the class
AgentBase
. The code you want to execute when the agent
runs is in the
NotesMain()
method.
Chapter 11
Advanced Domino Programming
343
To work with Java in Domino you need the Lotus Domino Toolkit for
Java/CORBA 2.0. You can download the toolkit from this Web site

Java Coding Conventions
There are some conventions you should follow to write a Java program.
These are as follows:
Classes
The names of the Java classes are similar to the LotusScript classes except
that they begin with the “lotus.domino”-prefix. The table below shows how

some of the Java Domino classes correspond to LotusScript objects:
NotesRichTextItemlotus.domino.RichTextItem
NotesItemlotus.domino.Item
NotesDocumentlotus.domino.Document
NotesViewlotus.domino.View
NotesDatabaselotus.domino.Database
NotesDbDirectorylotus.domino.DbDirectory
NotesSessionlotus.domino.Session
LotusScript ObjectJava Class
Note
The lotus.domino package has the same content as the Release 4.6
lotus.notes package plus new classes, methods, and other enhancements. The
Release 4.6 lotus.notes package continues to be supported for backwards
compatibility only. It does not contain the new classes, methods, and other
enhancements.
Methods
Method names are written with the first character being lower case, for
example getFirstDocument. Of course, there are some exceptions such as
FTSearch.
Note
By convention you should start your own classes with the first
character as uppercase.
Caution
Java is case sensitive; the wrong case causes an error.
Properties
To access properties in Java you also have to use methods. In Java,
properties are implemented through methods, known as accessors, which
use the following naming conventions:
• The name of a method used to get the value of a non-boolean property is
the name of the property prefixed with “get”.

• The name of a method used to set the value of a property is the name of
the property prefixed with “set”.
344 Lotus Domino Release 5.0: A Developer’s Handbook
• The name of a method used to get the value of a boolean property is the
name of the property prefixed with “is”.
Parameters and Return Values
Parameter and return values differ from LotusScript as needed to match the
different data types in Java. For example, in LotusScript boolean values are
represented by Variants. In Java they are of type boolean.
Object Containment Hierarchy
In Java you cannot create lotus.domino objects using the “new” modifier. All
lotus.domino objects must be created with lotus.domino methods emanating
from the root Session object.
Agents, Applets, Applications, and Servlets
Java programs can take one of several forms, each with its own
characteristics. The differences between these forms can be summarized:
Java agents complement the familiar LotusScript agents and, to a large
degree, they can be used interchangeably when dealing with back-end
operations. Some reasons for choosing Java over LotusScript are: existing
programmer knowledge, multi-threading, a more fully featured language,
extensibility through (non-visual) beans, etc.
Applets allow a Notes developer to create a richer GUI environment for the
end user. Applets will be dynamically downloaded from the server and
executed on the client’s machine and will work with either Web browsers or
Notes clients. The functions of applets can vary widely, from simple news
tickers to complex database front ends. Java applets are subject to the Java
Sandbox security model, which prevents unauthorized applets from
accessing sensitive machine resources and from performing certain
operations. By default applets will not have access to the Notes back-end
classes. If this is required, then CORBA is needed (see the CORBA section

later in this chapter).
Java applications differ from applets in that they are not dynamically loaded
from the server, they are similar to traditional executables in this respect.
However, Java applications typically run outside the Java “Sandbox”
security model and can thus access machine and network resources denied
to an applet. A Java application can be loosely regarded as analogous to a
stand-alone application which accesses the Notes object model, for example
a C or Visual Basic program. By default applets and applications will not
have access to the Notes back-end classes, if this is required then CORBA is
needed (see the CORBA section later in this chapter).
Java servlets, as their name suggests, only run on the server. A servlet is
invoked by a client request and will respond directly to the client. Typically
a servlet will be used to provide a high performance link to a back-end
Chapter 11: Advanced Domino Programming 345
system and format the results back to the client as a HTML document.
However servlets are not restricted to serving just HTTP requests and may in
fact converse directly with any suitable client application (usually an applet).
Again a loose analogy can be drawn to the ability in Domino to invoke an
agent directly from a HTTP request (myagent?openagent&param1=value1).
The model for Java agents differs from Java applets in a number of ways:
• Java agents are written explicitly for Domino. Applets are often designed
be served up by any Web servers.
• Java agents behave in the same way as LotusScript agents but Java
applets behave like Java applets in any Web-authoring environment.
• Java agents only run within a Domino-supplied Java runtime
environment whilst Java applets run in both Domino-supplied Java
runtimes and browser-supplied runtimes.
• Java agents are structured in the same way as Java applications (not as
applets). They run within a Domino-supplied context as opposed to
applets whose context is provided in part by the browser and in part by

the codebase parameter specified as part of the applet tag. For agents,
CodeBase and DocBase are not meaningful ways of getting ahold of
additional classes. Instead, as with other Java applications, classes, and
resources are located within Jar files and the class path.
• Java agents can access Domino databases directly using the Java Domino
classes. Applets can only access Domino objects within Notes using
URLs. Note that nothing precludes a Java agent from using URLs to
access Domino objects in Notes.
• Agents do not have a UI (and consequently do not use resources as
much as applets). Java Agents run in a relaxed security environment like
Java applications do. You can wrap an application or agent in a
SecurityLoader, typically this would be used in a tightly controlled
secure environment when running a semi-trusted application. This
feature is being built into JDK1.2 but can be achieved in 1.1x.
Adding CORBA to the Picture
One of the major enhancements in the Domino R5.0 embrace of Internet
standards is the support for CORBA.
Common Object Request Broker Architecture (CORBA) is an open standard
defined by the Object Management Group (OMG). CORBA serves as middle-
ware for a distributed computing environment whereby clients can invoke
methods on remote APIs residing on other computers. CORBA uses Internet
Inter-ORB Protocol (IIOP) for communication over a TCP/IP network.
346 Lotus Domino Release 5.0: A Developer’s Handbook
CORBA/IIOP support enables Domino developers to create applets that can
be downloaded to the client and can be remotely invoked in Domino
services, for example, to initiate a workflow process. In addition, CORBA/
IIOP enables information to be processed efficiently over networks within an
open standards-based framework and to distribute work effectively between
clients and servers, ultimately lowering the cost of ownership.
Benefits of Using CORBA

Some advantages to using CORBA are:
• You can use Domino Object Model (DOM) back-end classes to support
CORBA.
• The client does not have to deal with issues such as networking or
security.
• CORBA allows many different clients to use the same objects (not copies
of the objects). The latest version of the object is always used.
• Client applications can be in different languages from the Server Objects.
• Java ORBs and Stubs can be downloaded to the client at runtime, which
means:
• Users don’t have to install the application on the client before running
it.
• Clients are always working on the most current version of the
application.
• Network computers are supported as clients as the application is
removed when the computer is turned off.
For a more detailed look at the CORBA internals look in the appendix.
How and When to Use CORBA
CORBA support can be easily added to Java applets and applications to
extend their reach into the Domino back end. In order to utilize CORBA you
must make some small changes to your server and Java programs.
Chapter 11: Advanced Domino Programming 347
A Java program using CORBA has the following requirements:
Server
• The server tasks HTTP and DIIOP must be running. Ensure that the
notes.ini file contains the following line:
ServerTasks=<any other tasks>,http,diiop
To enable an applet for CORBA, import your applet into a form and select
the appropriate properties from the applet InfoBox.
For performance reasons, when a CORBA enabled applet is loading in the

Notes client all the calls are transparently made to the Notes DLLs rather
than the Java classes.
Compiling and Running a Java Program
The new package, lotus.domino, which comes with Domino R5.0 supports
local and remote calls to the Notes object interface. This package contains the
same classes and methods as the lotus.notes package shipped with Domino
R4.6 plus new classes, new methods, and some other enhancements.
Note
The Domino R4.6 lotus.notes package is supported for backward
compatibility only.
A Java program using the Domino classes has the following requirements:
Server
• The server tasks HTTP and DIIOP must be running. Ensure that the
notes.ini file contains the following line:
ServerTasks=<any other tasks>,http,diiop
348 Lotus Domino Release 5.0: A Developer’s Handbook
Designer
• Ensure that the NOTES.INI file contains the following line:
ALLOW_NOTES_PACKAGE_APPLETS=1
• Include NCSO.jar and Notes.jar in your CLASSPATH environment, for
example:
set
CLASSPATH=<other>;<domino>\java\NCSO.jar;<domino>\Notes.jar
Notes.jar contains the high-level lotus.domino package, the
lotus.domino.local package for local calls, and the old lotus.notes
package. NCSO.jar contains the high-level lotus.domino package and the
lotus.domino.corba package for remote calls. Strictly, you do not need
NCSO.jar if you are not compiling remote calls and you do not need
Notes.jar if you are not compiling local calls or old calls.
Your class code must import the high-level lotus.domino package:

• import lotus.domino.*
Runtime Requirements
• A machine running a Java application that makes local Notes calls must
contain Domino R5.0 (Client, Designer, or Server) and must include
Notes.jar in the CLASSPATH.
• A machine running a Java application that makes remote Notes calls
need not contain Domino R5.0, but must contain NCSO.jar and must
include NCSO.jar in the CLASSPATH.
• A machine running a Domino R5.0 agent that makes Notes (Java) calls
must include Notes.jar in the CLASSPATH.
Note
A machine running an applet that makes Notes calls needs no
Domino software or CLASSPATH assignments.
• The server must be running when remote calls are made.
Remote Calls to lotus.domino Package
In order for a Java application for remote runtime access of
lotus.domino you must create a Session with the NotesFactory method
createSession(String IOR, String user, String pwd). NotesFactory is new with
R5.0 and the lotus.domino package.
The IOR (initial object reference) parameter is required to access a Domino
server remotely. It is a string contained in the file ior.txt in the notes
directory of the Domino server. The NotesFactory method getIOR(String
host) returns the IOR for a given host.
Chapter 11: Advanced Domino Programming 349
The second and third parameters must be a user name and Internet
password in the Domino directory on the server being accessed. If empty
strings are specified, anonymous access must be permitted by the server.
The application must not use the NotesThread method. NotesThread is for
local access only.
This example demonstrates an application using remote calls:

import lotus.domino.*; // replaces old lotus.notes package
public class platform3 implements Runnable
{
String host=null, IOR=null, user="", pwd="";
public static void main(String argv[])
{
if(argv.length<1)
{
System.out.println("Supply Notes server name");
return;
}
platform3 t = new platform3(argv);
Thread nt = new Thread((Runnable)t);
nt.start();
}
public platform3(String argv[])
{
host = argv[0];
if(argv.length >= 2) user = argv[1];
if(argv.length >= 3) pwd = argv[2];
}
public void run()
{
try
{
IOR = NotesFactory.getIOR(host);
Session s = NotesFactory.createSession(IOR,user,pwd);
String p = s.getPlatform();
System.out.println("Platform = " + p);
}

catch (Exception e)
{
e.printStackTrace();
}
}
}
350 Lotus Domino Release 5.0: A Developer’s Handbook
Applet Calls to lotus.domino Package
An applet intended for run-time access of lotus.domino extends AppletBase
and puts its functional code in the methods notesAppletInit(),
notesAppletStart(), and notesAppletStop(). AppletBase is new with Domino
R5.0 and the lotus.domino package. You do not have to distinguish between
local and remote access. AppletBase will make local calls if the applet is
running on a machine with Domino installed and remote calls otherwise.
Domino will automatically supply the IOR.
Here is an example of an applet:
import lotus.domino.*;
public class platformApplet extends AppletBase
{
java.awt.TextArea ta;
public void notesAppletInit()
{
setLayout(null);
setSize(100,100);
ta = new java.awt.TextArea();
ta.setBounds(0,0,98,98);
add(ta);
ta.setEditable(false);
setVisible(true);
}

public void notesAppletStart()
{
Session s;
try
{
// Can also do openSession(user, pwd)
s = this.openSession();
if (s == null) { //not able to make the connection, warn user
ta.append("Unable to create a session with the server");
return;
}
String p = s.getPlatform();
ta.append("Platform = " + p);
}
catch(Exception e)
{
e.printStackTrace();
}
finally
{
// this.closeSession(s);
}
}
}
Chapter 11: Advanced Domino Programming 351
Setting Security Options for Java Applets
You can now set security options for applets to prevent unauthorized access
to your Notes file system or to Notes Java classes. You create an execution
control list that identifies what people and groups you trust with access to
your Notes system. When an applet runs on your workstation, Notes checks

for execution rights of the person or group that signed the applet. If an
applet is signed by a person or group without the correct authorization,
Notes alerts you to the illegal operation. You can abort the operation and not
run the applet, trust the signer of the applet one time, or automatically add
the signer to the execution control list.
Note that this security model only applies to applets running on the Notes
client. Applications running on a Web browser must follow the security
model set by the browser.
To set applet security:
1.
Choose File - Preferences - User Preferences.
2.
Click the Security options button on the Basics page.
3.
Click Java applet security to display the security panel.
Enter a person or group name and assign access rights to the file system
and/or Notes Java classes. The Add button lets you enter a name or
choose one from a Public Address Book.
4.
Click OK and close the dialog box when you have completed your
entries.
Note
The implementation of this applet security system removes the
restriction on using Notes classes in Java applets.
Using the NotesThread Class
A stand-alone program must use the lotus.domino.NotesThread class, which
extends Java.lang.Thread. You can either extend NotesThread or implement
the Run-able interface. If you extend NotesThread, the entry point to the
functional code must be public void runNotes(). If you implement run-able,
the entry point must be public void run().

• A Domino or Domino agent program must extend the
lotus.notes.AgentBase class, which extends lotus.domino.NotesThread.
The class that contains the agent code must be public. The entry point to
the functional code must be public void NotesMain().
• The lotus.domoino.Session class is the root of the Notes back-end object
containment hierarchy. For stand-alone programs, use one of the
NotesFactory.createSession methods to create a Session object. For
agents, use the AgentBase method getSession().
352 Lotus Domino Release 5.0: A Developer’s Handbook
• System.exit must not be used to terminate a program using the
NotesThread class (and by extension the AgentBase class). In an agent,
System.exit throws SecurityException. In a stand-alone program,
System.exit may cause corruption problems.
• For foreground agents, System.out and System.err output goes to the
Java debug console. For locally scheduled agents, System.out and
System.err output goes to the Domino log.
Creating a Java Agent
Example 1: Java Agent
This example shows an agent that runs on newly created and modified
documents since the agent was last run. The program works on the
unprocessed documents, prints the form name of each document, and marks
each document as processed. The first time the agent runs, the agent returns
all of the documents in the database. Thereafter, the agent returns those
documents that updateProcessedDoc has not touched.
1.
Create an agent:
• Name the agent.
• Select When should this agent run = Manually from Actions Menu.
• Which documents should it act on = All documents in database.
• Select Java as your source code and write the agent code.

import lotus.domino.*;
import java.util.*;
public class myagent extends AgentBase
{
public void NotesMain()
{
try
{
Session s = getSession();
AgentContext ac = s.getAgentContext();
DocumentCollection dc =
ac.getUnprocessedDocuments();
Document doc;
int size = dc.getCount();
System.out.println("Count = " + size);
doc = dc.getFirstDocument();
while (doc != null)
{
System.out.println
(" *** " + doc.getItemValue("form"));
ac.updateProcessedDoc(doc);
Chapter 11: Advanced Domino Programming 353
doc = dc.getNextDocument(doc);
}
}
catch (Exception e)
{
e.printStackTrace();
}
}

}
• Save it.
Example 2: Using Java Notes Classes
This sample Java program is from Lotus Technology Learning Center. The
Java code is commented to help you understand how the Java Notes class is
implemented.
This program creates an instance of NotesThread, a class which extends the
Java Thread class. It allows Notes to properly initialize and terminate per
thread in a convenient way for the programmer.
This sample program does the follow things:
1.
Creates a new Notes session.
2.
Opens a database (in this case, the local Address Book).
3.
Accesses the People view.
4.
Searches the People view for the entered name.
5.
Accesses the document that matches the search criteria.
6.
Pulls the Spouse field out of the document.
7.
Prints the Spouse field in a message output.
To Run This Sample:
1.
Add a person John Smith and his spouse Mary Smith into the local
Address Book. John Smith will be used as a parameter to the command
to run the Java program.
2.

Write the following code into a Java program(.java), set your PATH and
CLASSPATH, for example, as follows:
PATH = c:\jdk1.1.3\bin;c:\notes\;
CLASSPATH = c:\jdk1.1.3\lib\classes.zip;c:\notes\notes.jar;
3.
Compile the Java program.
Note
We used Java JDK Version 1.1.3 from SUN. You can download it
from www.javasoft.com.
4.
Type the command:
javac myjavafile.java
354 Lotus Domino Release 5.0: A Developer’s Handbook
The output is a file named abe.class.
5.
Run this class file at a DOS command prompt:
C:\jdk1.1.3\bin> java abe.class John Smith
The output will be like this:
Creating Notes session
User name = CN = John Smith OU=CAM O= Lotus
Spouse of John is Mary Smith
Date Created : 08/15/97 16:00:00 PM EDT
The sample program is listed below for your information:
/* Copyright 1997, Iris Associates, Inc.
Sample Java program, for illustrative purposes only.
*/
import lotus.domino.*;
import java.lang.*;
import java.util.*;
class abe implements Runnable

{
public String g_name;
// if you run the class from the command line
public static void main(String argv[])
throws Exception
{
// print out a message, then exit, no args provided
if (argv == null || argv.length == 0)
System.out.println("Usage: java abe <user name>");
else
{
// create new instance of abe
abe t = new abe();

// store name to look up in the instance
t.g_name = argv[0];

// make sure the Notes lsx is loaded
NotesThread.load(true);

// create a thread instance for running abe, start it
NotesThread nt = new NotesThread((Runnable)t);

// start the thread, call our runNotes()
nt.start();
Chapter 11: Advanced Domino Programming 355
}
}
// this would get called if we ran it from java.lang.Thread
// instead

public void run()
{
runNotes();
}
public void runNotes()
{
int i;
try
{
System.out.println("Creating Notes session ");
Session s = NotesFactory.createSession();

// show off, print the current user's name
System.out.println("User name = " + s.getUserName());
// get db instance for the name and address db
Database db = s.getDatabase("","names.nsf");

// find the "People" view
View view = db.getView("People");

// search for the name provided
view.FTSearch(g_name);

// for now, ignore multiple matches
Document doc = view.getFirstDocument();

// look up contents of the "spouse" field
String name = doc.getItemValueString("Spouse");
System.out.println("Spouse of " + g_name + " is " + name);

// also print out the date the document was created
System.out.println("Date created: " + doc.getCreated());
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
356 Lotus Domino Release 5.0: A Developer’s Handbook
CORBA/IIOP
Domino R5.0 uses an architecture called Common Object Request Broker
Architecture (CORBA). This is an open standard defined by the Object
Management Group (OMG). CORBA serves as middleware for a distributed
computing environment whereby remote clients can invoke methods on
remote APIs residing on other computers. CORBA uses Internet Inter-ORB
Protocol (IIOP) for communication over a TCP/IP network.
CORBA/IIOP support enables Domino developers to create applets that can
be downloaded to the client and can be remotely invoked in Domino
services, for example, to initiate a workflow process. In addition,
CORBA/IIOP enables information to be processed efficiently over networks
within an open standards-based framework and to distribute work
effectively between clients and servers, ultimately lowering the cost of
ownership.
Benefits of Using CORBA
Some advantages to using CORBA are:
• You can use Domino Object Model (DOM) back-end classes to support
CORBA.
• The client does not have to deal with issues such as networking or
security.

• CORBA allows many different clients to use the same objects (not copies
of the objects). The latest version of the object is always used.
• Client applications can be in different languages from the Server Objects.
• Java ORBs and Stubs can be downloaded to the client at runtime, which
means:
• Users don’t have to install the application on the client before
running it.
• Clients are always working on the most current version of the
application.
• Network computers are supported as clients as the application is
removed when the computer is turned off.
Chapter 11: Advanced Domino Programming 357
CORBA Architecture
In order to understand how the CORBA/IIOP architecture works, we will
first take a closer look at CORBA.
The heart of CORBA is the Object Request Broker (ORB). This is the object
bus, i.e. it’s like a PC bus but instead of sending bits/bytes/instructions it’s
sending objects and is potentially distributed. The job of the ORB is to act as
a middleman, allowing objects to make requests of each other. Although the
ORB operates in a client/server environment, objects that the ORB works
with can function as either clients or servers, depending on the circumstances.
If an object is receiving and processing a request, then it is acting as a server.
If the object is making a request, then it is acting as a client.
The ORB handles these requests regardless of programming language,
operating system, or platform. The mechanism that allows ORBs to handle
requests transparently is the Interface Definition Language (IDL), which is
used to declare the boundaries and interfaces of an object. Much like an
independent arbitrator, the IDL is neutral and independent of the object and
the ORB, yet it binds providers of distributed object services to their clients.
CORBA IDL uses inheritance to encapsulate objects and so it is able to reuse

code very easily. Furthermore, the beauty of IDL is that you can concisely
define APIs, yet still have the freedom to define the IDL methods in any
programming language that provides CORBA bindings, for example,
COBOL, C, C++, Smalltalk, and Java.
To make IDL truly independent, CORBA uses an Interface Repository (IR),
the purpose of which is to store the method signatures of objects so that the
signatures can be dynamically retrieved and updated at runtime. In this
way, all objects in the enterprise system can learn about other objects’
interfaces, the methods the interfaces support, and the parameters the
interfaces require.
When you bring together the ORB, the IDL, and the Interface Repository,
you have a basic model of CORBA. The model doesn’t include all the pieces
of the architecture, but it gives you an idea of how heterogeneous objects
interact using CORBA.
Internet Inter-ORB Protocol (IIOP)
Internet Inter ORB Protocol is a protocol also developed by Object
Management Group (OMG), which enables CORBA solutions to
communicate over the World Wide Web (WWW). It enables browsers and
servers to exchange data (integers, arrays, and complex objects) unlike
HTTP, which only supports text transmissions.
358 Lotus Domino Release 5.0: A Developer’s Handbook
CORBA and Domino
In earlier releases, the Domino client and server could communicate together
using APIs, but meant that all APIs and objects which were needed had to
reside on the client’s disk. This was sometimes difficult, for example, where
many clients needed a particular application, and it also required additional
disk space on the client.
CLIENT
LOCAL API
SERVER

CLIENT
OBJECTS
PROTOCOL
In this environment, what happens if a non-Domino client wishes to utilize
these APIs and there are no local Domino APIs present? The Domino server
has server APIs to implement the DOM (Domino Object Model), but the real
issue is how can the user access these remote APIs from a browser?
SERVER
CLIENT
CLIENT
OBJECTS
??????
SERVER API
Chapter 11: Advanced Domino Programming 359
In earlier Domino versions specific challenges included the following:
• Within a Web browser, applets had limited access to the database on the
server via Java API calls to remote Domino information after loading.
Also, the DOM could not be directly accessed by browser clients but
only indirectly via Web agents, triggered on document load or save.
• Within a Notes client, applets could not use the Java Notes classes as
they made native calls to local DLLs and this could compromise Java
applet security. Also, these applets could not retrieve Domino
information after initial loading. Applet programmability options were
not seamless to mixed client audiences.
• Standalone Java applications required an installed Notes client to use the
4.6 Java classes as they made native calls to locally installed Domino
DLLs (the Java classes were a wrapper around the C++ core).
CORBA/IIOP support in Domino R5.0 solves these problems. As mentioned
earlier, CORBA serves as middleware and facilitates the design and
implementation of distributed systems by providing a transport trough for

distributed objects to locate and exchange data with each other and provide
language, operating system, hardware platform, and networking
interoperability.
The following figure shows how a browser can use the Domino database to
use CORBA:
SERVER
CLIENT
CLIENT
OBJECTS
C++ SERVER API
CORBA
(C ++)
CORBA
(Java)
IIOP
This allows Java programs on remote clients such as applets in browsers and
standalone Java applications to access the Domino Object Model (DOM) on
the Domino server. From an implementation standpoint, a remote client
instantiates and references DOM objects as if they were resident on the
client, but in fact the client is communicating with objects on the server.
360 Lotus Domino Release 5.0: A Developer’s Handbook
Thanks to CORBA/IIOP Domino is able to:
• Use applets that can create a permanent DOM session with the Domino
server and access the back-end objects as if they were in a Notes client.
Also, the browser programmability mode can now more closely resemble
the Notes client programmability model. You can now associate Java or
JavaScript with the W3C (World Wide Web Consortium) events and
access data either on or off the current document without refreshing or
submitting the current page. For an example of how to access the top
level Notes session object via JavaScript see Chapter 10.

• Switch the transport dynamically depending on context; if the applet is in
a browser, CORBA is used. If it’s in a Notes Client then the Notes API is
used because it’s more efficient. Security options in the User Preferences
can control which applets, signed by whom, can access the file system or
Notes Java classes. The same CORBA applet will use remote calls to the
server from a browser. This is seamless to the programmer as long as the
applet is designed specifically for CORBA. The most compelling example
of this technology is the ability to place a custom applet on a form and
have that applet access the DOM in both the Notes client and a browser.
• Use standalone Java applications which have access to the Domino
server directly via CORBA without a client being installed locally.
Note
CORBA is often only associated with Java, but the real strength of
CORBA is its support of heterogeneous programming environments. In the
real world many legacy systems and newly developed applications are
written in different languages and they need integration in order to work
together. Language inter operability allows objects running in heterogeneous
languages to make invocations to each other. A CORBA interface can be
mapped into a number of popular programming languages on the client or
server, for example, C, C++, Smalltalk, Ada, COBOL, and Java already have
CORBA interfaces.
Coding the CORBA Applet
This section gives you an example of how to use CORBA within a Domino
application.
An applet intended for CORBA run-time access of Domino needs to be
designed in a specific way.
Step 1
Import the lotus.domino package into your applet source file. This package
is contained in the NCSO.jar or cab file and is new to Domino R5.0. It
contains the new DOM classes and CORBA Client stub classes.

import lotus.domino.*;
Chapter 11: Advanced Domino Programming 361
Step 2
Your applet class must extend the AppletBase class.
This class already implements the standard applet methods init( ), start( ),
end( ), stop( ) as final methods, therefore you cannot create (or override)
these in your applet. Instead these final methods call the following methods
respectively notesAppletInit( ), notesAppletStart( ), notesAppletEnd( ) and
notesAppletStop( ). These methods are also contained in the AppletBase
class and are not final. If you wish to implement the functionality that you
would normally in the traditional applet methods, you must override the
respective notesAppletXXXX( ) method in your applet class. You do not have
to distinguish between local and remote access. AppletBase will make local
calls if the applet is running through the Notes client and remote CORBA
calls if it is running through a browser.
import lotus.domino.*;
public class myApplet extends AppletBase
{
public void notesAppletInit()
{
// Your Applet Init Code
}
public void notesAppletStart()
{
// Your Applet Start Code
}
public void notesAppletEnd()
{
// Your Applet End Code
}

public void notesAppletStop()
{
// Your Applet Stop Code
}
}
Step 3
To access a Session object within your applet you use the getSession( )
inherited instance method of the AppletBase class. As mentioned previously,
the getSession( ) method call will also instantiate and initialize the Client
Side ORB as well as request a remote Session object reference from the
Domino server. Each applet on a HTML page invoking the getSession
method will instantiate another Client ORB. This may not be desirable,
methods for inter-applet communication such as the InfoBus technology may
362 Lotus Domino Release 5.0: A Developer’s Handbook