You can call the Domino Objects from a Java program by importing the lotus.domino package. The program can be coded as an application, a Domino agent, an applet, or a servlet. Local calls access run-time code on the local computer, which must have Domino installed. CORBA-based remote (IIOP) calls access run-time code from a remote Domino server; in this case, the local computer need not have Domino installed. Compilation must be on a computer with Domino Designer installed.

Note Notes/Domino Release 7 supports the Sun Java(TM) 2 Platform, Technology Edition, v 1.4.2. To avoid incompatibilities: do not run Java agents compiled under Release 7 on earlier Domino servers or Notes clients; do not use Release 7 Java archives (Notes.jar, domtags.jar) on Java platforms earler than v. 1.4.2.

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 backward compatibility only; it does not contain the new classes, methods, and other enhancements.

Requirements

Server requirements

CORBA-based remote (IIOP) calls require access to a Domino server.

The HTTP task is not required to be running for DIIOP to be used. Ensure that the server notes.ini file contains the following line:

ServerTasks=<any other tasks>,diiop

Or you can start the task later with the load console command.

Note The JavaMaxHeapsize should not be decreased below a value of 64M, or a runtime error will occur when attempting to execute nhttp.exe. If a value for JavaMaxHeapsize is not set in the server notes.ini file, a value of 64M will be used.

The server document in the Domino Directory (under Server\Servers) must permit and restrict remote calls as desired. Right-click on a field description to display an extended description.

• Under Security:
  • Under Server Access, fill in "Access server," "Not access server," "Create new databases," and "Create replica databases" as desired.
  • Under Programmability Restrictions, fill in "Run unrestricted methods and operations" and "Run restricted LotusScript Java agents" as desired. These fields apply to all programmable interfaces and must be filled in for remote access.
  Note These settings are new with Release 6.
  • Under Internet Access - For "Internet authentication," specify a more inclusive or less inclusive view for validating user names.
  Note This verification is new for Release 5.0.1.
• Under Ports:
  • Under Internet Ports - For "IIOP," indicate whether access is permitted by name and password, and whether anonymous access is allowed.
• Under Internet Protocols:
  • Under HTTP R5 - For "Basics," indicate whether HTTP clients can browse databases. A "no" specification disallows DbDirectory.getFirstDatabase for the database.
  Note This verification is new for Release 5.0.1.
  • Under IIOP, specify the number of threads to be allocated for handling remote calls.
  Note This restriction does not apply as of Release 6.

SSL security for CORBA-based Domino Object applications/applets builds on the Web Server SSL security. You must first set up the Web server security using the "Domino R5 Certificate Authority" application.

Designer requirements

Compilation of a Java program using the lotus.domino package requires installation of Domino Designer Release 5 or greater.

For stand-alone applications, include Notes.jar from the appropriate Java library subdirectory of the Notes program directory and domino\java\NCSO.jar or domino\java\NCSO.cab from the Notes data directory in the classpath. For example:

set CLASSPATH=.;c:\notes\jvm\lib\ext\Notes.jar
set CLASSPATH=.;c:\notes\data\domino\java\NCSO.jar

Notes.jar contains the high-level lotus.domino package, the lotus.domino.local package for local calls, and the old lotus.notes package. The NCSO archive contains the high-level lotus.domino package and the lotus.domino.cso package for remote calls. Strictly, you do not need the NCSO archive if you are not compiling remote calls and you do not need Notes.jar if you are not compiling local calls or old calls.

The two NCSO archives have identical content but differ in the archiving technique:

• NCSO.jar uses the JDK JAR utility with compression.
• NCSO.cab uses the Microsoft CABARC utility.

  Note Earlier releases used NCSO.jar (uncompressed) and NCSOC.jar (compressed).

import lotus.domino.*;

Run-time requirements

A computer running a Java application that makes local Domino calls must contain Domino Server, Domino Designer, or Notes Client, and must include Notes.jar in the classpath.

A computer running a Java application that makes remote Domino calls need not contain Domino or Notes, but must contain one of the NCSO archives and must include it in the classpath.

A computer running a Domino agent that makes Domino calls must include Notes.jar in the classpath.

A computer running an applet that makes Domino calls needs no Domino software or classpath assignments. The applet must be loaded from a computer containing a Domino server.

Note Do not use NCSOW.jar in the classpath for executing remote (IIOP) calls in a WebSphere® environment. NCSOW.jar is no longer kitted as it was starting with Release 5.0.4. You can continue to run programs that use NCSOW.jar on R5 servers, but not on Release 6 servers. The NCSO archives work with both R5 and Release 6 servers.

Memory management for Java objects

When Java is used to create an object, two objects are created, a Java object and Notes back-end (C++) object. If the Java object is set to null, flagging it for garbage collection, the C++ object is not affected. To have both the Java object and the C++ object marked for garbage collection, you must use the recycle method.

If objects are created from within a Java agent, all created objects (both Java and C++) are destroyed when the agent ends. However, you should consider using the recycle method for long running agents or agents that create a large number of objects. When using servlets, JSPs or stand-alone Java applications, the recycle method must be used to remove the back-end objects.

Recycling a parent, such as a document, will recycle all of its children, such as items. Recycling the session will recycle every object that has been used from it.

Calling the lotus.domino package

The following guidelines apply to Java programs calling into the lotus.domino package:

• An application or servlet that makes local calls uses the NotesThread class, which extends java.lang.Thread. You can extend NotesThread, implement the Runnable interface, or use the static NotesThread methods sinitThread() and stermThread(). If you extend NotesThread, the entry point to the functional code must be public void runNotes(). If you implement Runnable, the entry point must be public void run(). If you use the static NotesThread methods, be sure to call stermThread exactly one time for each call to sinitThread. An application that makes remote calls does not use the NotesThread class. See the examples for clarification.

  Each thread of an application making local calls must initialize a NotesThread object. This includes AWT threads that access the Domino Objects. Listener threads must use the static methods because they cannot inherit from NotesThread.

  See "Multithreading issues" under the NotesThread class.

• An agent extends the AgentBase class, which extends the NotesThread class. The class that contains the agent code must be public. The entry point to the functional code must be public void NotesMain(). See the examples for clarification.
• An applet extends AppletBase and puts its functional code in the methods notesAppletInit(), notesAppletStart(), and notesAppletStop(). You do not have to distinguish between local and remote access in the main code. AppletBase makes local calls if the applet is running through the Notes client and remote calls if it is running through a browser. Remote calls go to the Domino server on the computer that loaded the applet.

  If an applet creates a thread containing Domino calls, the thread code must use NotesThread for local Domino calls but not remote (IIOP) calls. Use AppletBase.isLocal() to determine the environment. Use NotesThread.sinitThread for initialization and NotesThread.stermThread for termination. Thread creation includes handling AWT events.

  See the examples for clarification.

  For applets stored in a Domino database, "Applet uses Notes CORBA classes" under Java Applet - Java Applet Properties must be checked.

• The Session class is the root of the Domino back-end object containment hierarchy. For applications making local calls, use the method NotesFactory createSession(), createSessionWithFullAccess(), createSession(null, null, String pwd), createSessionWithFullAccess(String pwd), createSession(null, String user, String pwd), or createSession(null, "", "") to create a Session object. For applications making remote calls, use the method createSession(String host, "", "") or createSession(String host, String user, String pwd). For agents, use the method AgentBase.getSession(). For applets, use the method AppletBase.openSession() or openSession(String user, String pwd) and closeSession(Session session). See the examples for clarification.

  The user and pwd parameters of NotesFactory.createSession and AppletBase.openSession must be a user name and Internet password in the Domino Directory on the server being accessed. If a name and password are not specified, anonymous access must be permitted by the server.

  For Single Sign-on to a Domino or WebSphere server, use createSession(String host, String token), createSession(String host, org.omg.SecurityLevel2.Credentials token), createSession(String host, null), or createSession(String host, HttpServletRequest request).

  Note Single Sign-on is new with Release 5.0.5.

  To enable SSL (Secure Sockets Layer), use NotesFactory.createSession(String host, String args[], String user, String pwd) and specify "-ORBEnableSSLSecurity" for args(0).

• 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.
• For output to Web browsers from agents (but not applets), you must assign a java.io.PrintWriter object with the getAgentOutput() method of AgentBase, and write using the println method of the PrintWriter object. This method works for output to Notes clients as well. See the examples for clarification.
• 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 an application, System.exit may cause corruption problems.

The lotus.domino classes allow you to access named databases, views, documents, and other back-end objects. The following lotus.domino classes are for direct, public use:

• ACL represents a collection of all the access control list entries for a database.
• ACLEntry represents a single entry in an access control list.
• AdministrationProcess represents the administration process.
• Agent represents the attributes of an agent.
• AgentContext represents the context of the current agent if the program is running as an agent.
• ColorObject represents a color.
• Database represents a Domino database.
• DateRange represents a range of dates and times.
• DateTime represents a Domino date-time.
• DbDirectory represents the database files on a server or the local computer.
• Document represents a document in a database.
• DocumentCollection represents a collection of documents.
• DXLExporter represents the conversion of Domino data to DXL (Domino XML).
• DXLImporter represents the conversion of DXL (Domino XML) to Domino data.
• EmbeddedObject represents embedded objects, links, and file attachments.
• Form represents a form in a database.
• International represents the international settings in the operating system.
• Item represents an item of data in a document.
• Log represents actions and errors that occur during execution of a script.
• MIMEEntity represents an item of type MIME (Multipurpose Internet Mail Extensions).
• MIMEHeader represents a MIME header.
• Name represents a user or server name.
• Newsletter represents a summary document that contains information from, or links to, several other documents.
• NoteCollection represents a collection of Domino design and data elements in a database.
• Outline represents an outline.
• OutlineEntry represents an entry in an outline.
• Registration represents the creation or administration of an ID file.
• Replication represents the replication attributes of a Domino database.
• ReplicationEntry represents the replication settings for a pair of servers in a database.
• RichTextDoclink represents a doclink in a rich text item.
• RichTextItem represents items that contain rich text.
• RichTextNavigator represents a means of navigation in a rich text item.
• RichTextParagraphStyle represents rich text paragraph style attributes.
• RichTextRange represents a range of elements in a rich text item.
• RichTextSection represents a collapsible section in a rich text item.
• RichTextStyle represents rich text style attributes.
• RichTextTab represents rich text tab attributes.
• RichTextTable represents a table in a rich text item.
• Session represents the context of the current program. This class is the root of the Domino database objects.
• Stream represents a stream of binary or character data.
• View represents a view or folder in a database.
• ViewColumn represents a column of a view.
• ViewEntry represents an entry in a view.
• ViewEntryCollection represents a collection of view entries.
• ViewNavigator represents a view navigator.

Java Classes Coding Guidelines

Glossary