Running a Java™ program

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.

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.

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

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).

Your class code must import the high-level lotus.domino package:

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.

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.

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.
• 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.