What is DIIOP?
Domino is able to allow external programs to execute on the server through the DIIOP task. DIIOP stands for Domino Internet Inter-ORB Protocol. DIIOP is Domino's implementation of CORBA.
Configuring security settings
The rights to execute a program that uses DIIOP is controlled by security settings on the Security tab of the server document:
Under Server Access, "Access server," "Not access server," "Create new databases," and "Create replica databases" must be set to provide the ID executing the code the necessary server access rights.
Under Programmability Restrictions, "Run unrestricted methods and operations" and "Run restricted LotusScript Java agents" must be set to allow the ID executing the code the necessary rights to run the Java program.
Configuring the DIIOP port
In order to connect to Domino, the DIIOP port must be enabled on the server. This is set on the server document on the Ports - Internet Ports tab. If the server is set to use internet site documents, a DIIOP site document is used instead of the server document for each internet site requiring access over DIIOP.
Controlling the DIIOP task
The DIIOP task is started like any other Domino server task - you can add it to the ServerTasks= line of the server's notes.ini if you wish the task to load at server startup. You can start the task manually with the console command "load diiop", stop the task with "tell diiop quit", and restart the task with "restart task diiop"
Creating Java programs that use DIIOP
A program that uses DIIOP makes a connection to the server with a call to the NotesFactory createSession method. One the session is established, the Java program can access Domino objects on the server as if they were local to the program.
NotesFactory class documentation in Domino Designer Help
For an overview of coding Java programs that use DIIOP, there are many good references:
"Java access to the Domino Objects" IBM developerWorks http://www.ibm.com/developerworks/lotus/library/ls-Java_access_pt1/index.html
"Examples: Running a Java program" Domino Designer Help, example DIIOP programs start with Example 7 http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=%2Fcom.ibm.designer.domino.main.doc%2FH_EXAMPLES_COMPILING_AND_RUNNING_JAVA.html
"Writing standalone Java code that connects to IBM Lotus Domino" Domino wiki http://www-10.lotus.com/ldd/dominowiki.nsf/dx/06082009125716amweb7tu.htm
Retrieving the IOR
The IOR is a file named diiop_ior.txt that is created automatically in the server's data/domino/html directory by the DIIOP task. Before a Java program can run over DIIOP, it must retrieve the IOR from the server. This is done automatically by the createSession method through a connection to the server's HTTP port. However, this cannot be done over SSL through the HTTPS port.
If using Internet Sites, the IP address or host name of the site providing the IOR may need to provided by setting DIIOPIORHost in the server's notes.ini. See http://www-10.lotus.com/ldd/dominowiki.nsf/dx/diiopiorhost and http://www-01.ibm.com/support/docview.wss?uid=swg21236597
SSL and IOR retrieval
If the HTTP port is set to redirect all traffic to SSL, (seton the server document's Ports - Internet Ports tab) you must do one of the following:
- Explicitly connect to the server with the createSession method using the DIIOP port, which is by default set to port 63148. The DIIOP port can be used instead of the HTTP port to retrieve the IOR.
- or -
- Connect to the server using the getIOR method first, and then create the session using the method createSessionWithIOR, for example:
String args = new String;
args = "-HTTPEnableSSLSecurity";
String ior = NotesFactory.getIOR(host,args);
s = NotesFactory.createSessionWithIOR(ior, userName, password);
Program execution over an SSL connection
If an SSL connection is required for DIIOP, the external code must reference the TrustedCerts.class, which is found in the server's domino/java directory. Copy the file from the server to a location which can be accessed by the external program. Domino Designer Help provides the documentation on this requirement.
For remote (IIOP) applications, the client must have access to the server's trusted root certificate, stored in TrustedCerts.class in domino/java in the server's data directory. This file is generated by the DIIOP task when it starts and is enabled to listen on the SSL port specified in the server document. The HTTP task delivers TrustedCerts.class to applets. For other applications, ensure that TrustedCerts.class is on the classpath.
Data on pressing by the DIIOP task can be written to the console log by enabling debug notes.ini parameters. It is necessary to restart the DIIOP task for these settings to take effect.
The following setting will write all DIIOP operations to the server console and the console log
To reduce the amount of data logged, you may wish to use a less verbose setting. DIIOP_DEBUG_ALL is a shortcut equivalent to setting the following debug notes.ini parameters:
Accessing a configuration summary
You can determine the server's current configuration for the DIIOP task by issuing the console command "tell diiop dump config" A text file containing all server DIIOP settings will be written to diiopcfg.txt, which will be in the data directory of the server.
If you need to contact a support professional for a DIIOP issue, you should be prepared to provide the console log, the Java program, the server's notes.ini, and the DIIOP configuration.
Domino's DIIOP task opens a wide range of possibilities to fully exploiting your Domino's server potential. We hope this guide makes your use of it as easy and effortless as possible.