You can call into the object interface 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 machine, which must have Domino installed. Remote (IIOP) calls access run-time code from a remote Domino server; in this case, the local machine need not have Domino installed. Compilation must be on a machine with Domino Designer R5 installed.

Note The lotus.domino package has the same content as the R4.6 lotus.notes package plus new classes, methods, and other enhancements. The R4.6 lotus.notes package continues to be supported for backwards compatibility only; it does not contain the new classes, methods, and other enhancements.

Requirements

Server requirements

Remote calls require access to an R5 Domino server.

The server tasks HTTP and DIIOP must be running. Ensure that the server notes.ini file contains the following line:

ServerTasks=<any other tasks>,http,diiop

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

The server document in the Domino Directory (under Server\Servers) must permit and restrict remote calls as desired:

• Under Internet Protocols - IIOP, specify the number of threads to be allocated for handling remote calls.
  
  
• Under Ports - Internet Ports - DIIOP, set up the TCP/IP port for non-encrypted transfers and the SSL port for encrypted transfers. Indicate whether access is permitted by name and password, and whether anonymous access is allowed.
  
  
• Under Security - Server Access, fill in Access server, Not access server, Create new databases, and Create replica databases as desired.
  
  
• Fill in Security - DIIOP Restrictions as desired.
  
  

A server refreshes its cache of security options approximately every half hour. The console command "tell diiop refresh" forces an immediate refresh.

Designer requirements

Compilation of a Java program using the lotus.domino package requires installation of Domino Designer R5.

Ensure that the notes.ini file of the Designer machine contains the following line:

ALLOW_NOTES_PACKAGE_APPLETS=1

For stand-alone applications, include domino\java\NCSO.jar and Notes.jar from the Notes directory in the CLASSPATH environment variable. For example:

set CLASSPATH=.;c:\notes\domino\java\NCSO.jar;c:\notes\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.*;

Run-time requirements

A machine running a Java application that makes local Domino calls must contain Domino R5 (Client, Designer, or Server) and must include Notes.jar in the CLASSPATH.

A machine running a Java application that makes remote Domino calls need not contain Domino R5, but must contain NCSO.jar and must include NCSO.jar in the CLASSPATH.

A machine running a Domino R5 agent that makes Domino calls must include Notes.jar in the CLASSPATH.

A machine running an applet that makes Domino calls needs no Domino software or CLASSPATH assignments.

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.
  
  
• 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 (IIOP) calls if it is running through a browser.
  
      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.
  
  
• The Session class is the root of the Domino back-end object containment hierarchy. For applications making local calls, use the method NotesFactory.createSession() to create a Session object. For applications making remote calls, use the method NotesFactory.createSession(String host) or NotesFactory.createSession(String host, String user, String pwd). For agents, use the method AgentBase.getSession(). For applets, use the method AppletBase.openSession() or AppletBase.openSession(String user, String pwd) and AppletBase.closeSession(Session session). See the examples for clarification.
  
      The user and pwd parameters of NotesFactory.createSession(String host, String user, String pwd) and AppletBase.openSession(String user, String pwd) 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.
  
      To enable SSL (Secure Socket 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.
  
  

Using the lotus.domino classes

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.
  
  
• Agent represents the attributes of an agent.
  
  
• AgentContext represents the context of the current agent if the program is running as an agent.
  
  
• 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 machine.
  
  
• Document represents a document in a database.
  
  
• DocumentCollection represents a collection of documents.
  
  
• 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.
  
  
• Name represents a user or server name.
  
  
• NewsLetter represents a summary document that contains information from, or links to, several other documents.
  
  
• 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.
  
  
• RichTextItem represents items that contain rich text.
  
  
• RichTextParagraphStyle represents rich text paragraph style attributes.
  
  
• RichTextStyle represents rich text style attributes.
  
  
• RichTextTab represents rich text tab attributes.
  
  
• Session represents the context of the current program. This class is the root of the Domino database objects.
  
  
• 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.