DominoDIIOP

Oh what fun I've had with DIIOP (Domino Internet Inter-Orb Protocol)! It all started with this weblog post but here are some additional notes for you if you're just starting up with it (apologies if some are obvious -- also note that all relate to Windows):

Basic set-up

Switch on the DIIOP task! Set up authentication options in the Server document (under 'Ports / Internet Ports / IIOP /Authentication Options'). Make sure you have the necessary permissioning in the server document for the server you're attempting to connect to (security tab under 'Java/COM restrictions Who Can...') Make sure you are listed in the 'Run unrestricted methods and operations:' field (Security Tab) of the server document on the server you are running the agent from. In Domino 6, ensure your agent's Security Tab (key icon on properties box when agent is open) is set to 2. Allow restricted operations or 3. Allow restricted operations with full administration rights. You will get the error 'java.lang.SecurityException?: <server name you are connecting to>' if these settings don't allow unrestricted operations. Make sure you include the JavaUserClasses? variable in the notes.ini of the server from which you are running the agent. The JavaUserClasses? variable should be set to the NCSO.jar file.

eg JavaUserClasses? C:\Program Files\domino\data\domino\java\NCSO.jar

If you are running your agent manually, ensure the NCSO.jar file is declared in the notes.ini of your notes client session.

If this is not set, you get the error 'java.lang.NoClassDefFoundError?: lotus/domino/cso/Session'.
Bounce the task as required after making changes to the Server document

Testing

You test your DIIOP set-up by entering this address in your browser: http://SERVER_NAME/diiop_ior.txt Use the server's IP address if your organisation is like mine, with extremely naff DNS.

Bob Balaban

Bob created the Domino Pool Manager which addresses those pesky session leaks in remote Java. He also wrote Tips for Working with Domino Objects (January 2001)

Code

All being well, you can move on to accessing Domino resources via DIIOP. Make sure you trap everything in try... catch blocks. Note that the <samp>NotesException?</samp> class documentation only details error codes up to 4469. Yet there are more... Here are some of the undocumented ones I found:
  • public static final int NOTES_ERR_INVALID_USERNAME_PASSWD = (int)(4486);
  • public static final int NOTES_ERR_INVALID_USERNAME = (int)(4487);
  • public static final int NOTES_ERR_SERVER_ACCESS_DENIED = (int)(4488);
  • public static final int NOTES_ERR_NO_SERVER = (int)(4489);
  • Make sure you're attempting to authenticate with the corresponding user id and internet password as specified in your person document.

    Config & getting IIOR

    Server commands for developers with memories like sieves and no admin experience:

    load http
    load diiop
    tell http quit
    tell diiop quit
    tell diiop refresh
    tell http restart

    On Domino servers, the IOR is a file named diiop_ior.txt in the domino\html subdirectory under the Domino data directory. The IOR is a string encoding of an object that contains identifying information for CORBA access to the server. A client decodes the string IOR and uses it to establish the remote session.

    By default, a remote client requests the server IOR through the Web server port (which normally services HTTP requests), then makes the session request through the DIIOP port. You can perform the requests separately. For example:

    String ior = NotesFactory.getIOR('myhost.east.acme.com');
    Session s = NotesFactory.createSessionWithIOR(ior);

    is equivalent to:

    Session s = NotesFactory.createSession('myhost.east.acme.com');

    In the <samp>NotesFactory</samp> calls, you can specify the host port for getting the IOR by appending a colon and the port number to the host name or IP address. You can use this mechanism to service the HTTP request for the IOR through the DIIOP port if, for example, the Web server is not running, for instance:

    String ior = NotesFactory.getIOR('myhost.east.acme.com:63148');
    Session s = NotesFactory.createSessionWithIOR(ior);

    However, the two-step coding sequence is not necessary. You can simply say:

    Session s = NotesFactory.createSession('myhost.east.acme.com:63148');

    You cannot use the DIIOP port to get text files other than diiop_ior.txt.

    If you get the IOR through the Web server port (or at all, in releases prior to Domino 6.x), Anonymous access must be allowed. In the Server document in the Domino Directory, go to the Ports tab, then the Internet Ports tab, then the Web tab. Ensure that the Anonymous field under Authentication options is set to Yes.

    The ability to specify the DIIOP port to get the IOR is new with Notes/Domino 6. You can now use remote calls without having to allow Anonymous access on the Web server or without running the Web server at all.

    You can also get the IOR by other means and use createSessionWithIOR. For example, you can copy the file diiop_ior.txt from the server computer to the client computer.

    Be aware that the IOR settings can become stale. Any of the following changes on the server obsoletes a diiop_ior.txt file on a client:

    • Changing a DIIOP port number
    • Enabling or disabling a DIIOP port
    • Changing the TCP/IP address
    • You can eliminate the last bullet by specifying the server host name rather than the server's TCP/IP address. In the Server document, go to the Internet Protocols tab, then the DIIOP tab. Specify the Internet host name for the server in the Host name/Address field.

      Running with Sites

      It's important that if your Domino server is set up to run with Internet sites that all four of the site documents (Website, IIOP, LDAP and SSO Configuration) are all have the same Organisation set, otherwise you will get a 'Cookie is Invalid' error when you try and authenticate even if you can see the diiop_ior.txt file.

      Server debug settings

      DEBUG_OUTFILE=debug.txt
      DIIOP_DEBUG=1
      DIIOP_DEBUG_INVOKE=1
      DIIOP_DISABLE_IP_CHECKING=1
      DIIOP_DEBUG_COOKIE=1
      DIIOP_DEBUG_REFDATA=1
      DIIOP_DEBUG_CONNMGR=1
      DIIOP_DEBUG_USEROBJ=1
      DIIOP_DEBUG_SSLCERT=1
      DEBUG_ORB_OI=1
      DEBUG_ORB_SOCKETS=1
      DEBUG_ORB_PARAMS=1
      DEBUG_ORB_THREADS=1
      DEBUG_ORB_SHRED=1
      DEBUG_ORB_SERVER=1
      DEBUG_TCP_ALL=1

      Further reading

      Wikipedia page on DIIOP
      Mikkel Heisterberg, DIIOP_IOR_HOST