5.3 Accessing Domino data from portlets using Java and CORBA

---

5.3 Accessing Domino data from portlets using Java and CORBA

You can access data residing in a Domino server from a portlet using Java language, where CORBA serves as a middleware distributed environment for a Domino Object Model (DOM) back-end classes. In practice, you will implement this through the set of Java interfaces contained in the lotus.domino package.

Overview

Figure 5-6 on page 248 illustrates the components of portlet integration to Domino.

Figure 5-6: Overview of integration from portlet to Domino data

• You have to enable single sign-on (SSO) between the Domino server and the Websphere Application server. Details about implementing SSO are in the Lotus Domino Administrator 6 Help database.

• The Domino environment consists of Domino Object Model, such as session, database, views, documents. Protocols (DIIOP and HTTP) are used in implementing physical connection between Domino and the Portlet. You need to configure your Domino server to use DIIOP.

• In the Portal, you have a Java environment to develop portlets using Portlet API, and Domino Java API for accessing Domino Objects and rendering Domino data to the portlet.

We describe these components in more detail in this section to make this integration technique clear.

Important: 

The set of Java interfaces contained in the lotus.domino package will implement integration from the portlet to Domino.

Java

Java is one of the most important and commonly used programming languages, and as we have already mentioned, portlets are built with Java language.

Domino offers you the option to write your applications in Java. Domino 6.0 and later supports Java programs written in JDK 1.3 and SDK 2.0. (These tools are discussed in more detail in 6.1, "Software and tools used" on page 306.

CORBA

CORBA, or Common Object Request Broker Architecture, is an open standard defined by the Object Management Group (OMG). CORBA serves as middleware for a distributed computing environment whereby clients can invoke methods on remote APIs residing on other computers. CORBA uses Internet Inter-ORB Protocol (IIOP) for communication over a TCP/IP network.

CORBA/IIOP support enables developers to create portlets that can be remotely invoked in Domino services. In addition, it enables information to be processed efficiently over networks within an open standards-based framework and to distribute work effectively between clients and servers, ultimately lowering the cost of ownership.

Advantages to using CORBA are:

• You can use Domino Object Model (DOM) back-end classes.

• The client does not have to deal with issues such as networking or security.

• CORBA allows many different portlets to use the same objects (not copies of the objects). The latest version of the object is always used.

DIIOP

DIIOP, or Domino Internet Inter-ORB, is the Domino task that allows external CORBA programs to attach to, and manipulate Domino databases. Most notably this allows Java programs, or portlets to connect to Domino. The remote methods use CORBA classes included in the file NCSO.jar/NCSOW.jar shipped with Domino and require that the DIIOP task is running on the server where the session object is to be obtained.

Attention: 

Portlets can use DIIOP to access objects located in Domino.

Local or remote access to Domino

Domino supports both local and remote access using virtually identical object models. Both options are available through the identical set of Java interfaces contained in the lotus.domino package. The only difference is the .jar file you put in your portlet development environment: notes.jar for local access, or ncso.jar for remote access. Ncso.jar is for all Java environments except WebSphere; there you should use ncsow.jar. All of these files are shipped with Domino server.

The coding is the same whether your objects are on the same machine (local) as your Portlet Java code (or JSP), or on some other machine on the network (remote). This is a big win in terms of development simplicity.

Keep in mind the following issues related to thread management:

• When using the local Domino classes from any Java program, you're essentially calling through a thin layer of Java code into the Domino back-end code, which is implemented in C++. The Java wrapper classes use a standard Java-to-C calling mechanism, known as Java Native Interface (JNI), to access the real Domino classes in the product's .dlls (or whatever the platform-specific equivalent of a .dll is). The Domino code is loaded "in process" in the Java Virtual Machine (JVM), which is great from the point of view of performance: You're getting the best possible speed out of the hook-up between the Java and C code-everything is right there in the computer's memory. On local use you need to manage threads, and initialize and terminate them properly.

• If you use the remote object library for Domino (the CORBA classes), you aren't accessing any Domino C/C++ code from within the JVM's process space, and there aren't any special requirements for thread initialization or termination. You can instantiate a Session object (or any object in the Domino hierarchy) and keep it around for re-use later. This is a real advantage, although there is a performance hit by having all calls remote across a network.

  Even if you're using the CORBA classes to communicate with a Domino server on the same machine as your WebSphere program, you still pay for having all method invocations processed remotely. Extra time is used for: marshalling the arguments, formatting data according to the IIOP wire protocol specification, transmitting the call, de-marshalling the parameters, finding the remote object to invoke, and so on. The bytes may not actually go out over the network, but they have to travel through your network adapter card and be processed on both ends of the conversation as if there were a network cable in between.

In a real-life production portal environment you probably will never face an actual case where you have installed WebSphere Portal server together with Domino Server on the same machine. However, this may be the case in a very small production environment or in a testing and development environment. From a performance point of view it's not ever recommend to install them on the same machine.

To summarize:

• Local access has much faster access to Domino calls, but does things more repetitively.

• Remote access is a "cleaner" architecture, requiring fewer actual calls.

Mechanism of the CORBA sessions for Domino

When CORBA is used to access the Domino server, the objects that are instantiated in your portlet code do not contain any functional methods in the same way as local objects do.

The portlet is the client, and the CORBA objects are the Session, Database, View, and Documents that the portlet creates at various times.

When CORBA objects are created, what you actually get is a stub to manipulate on the client. A second object-the real one if you like-is created on the server and linked with your stub. This stub contains all the same methods that the real object contains, but instead of the same functional code, they simply contain code to serialize the method call over the network so that the actual method is executed on the server by the real object.

Figure 5-7: Mechanism of CORBA, stub of object versus real object

For example, the Session instance hangs around until you recycle it, or until the connection to Domino times out. All Domino objects created using this Session likewise resides on the remote Domino machine. Any method invocations you make are sent over the network to the server and executed there. What look like local Java object instances are really just instances of proxy objects, whose only job is to communicate with the real objects over on the Domino server. Recycling is a really important issue when you are using Domino Java API. For more information, see "Recycling Domino objects" on page 257.

Enabling Domino server for DIIOP connection

DIIOP can be loaded manually at the server console by typing load diiop, or it can be started automatically by including it in the line in notes.ini which starts with ServerTasks=. It can also be started through the Domino Administrator client on the Server tab.

DIIOP needs some slight configuration changes in the server document to ensure that it can bind to the port specified (63148 by default) on the local host machine. The DIIOP settings are shown in Figure 5-8.

Figure 5-8: DIIOP settings in the server document

The fully qualified host name of the server in the server document must also be resolvable to the machine's IP address. You may need to add a line in the hosts file of the server's operating system (/etc/hosts on most UNIX/Linux machines, or c:\winnt\system32\etc\drivers\hosts on Windows).

You have to also specify access control for the DIIOP. This can be done on the Security tab of the server document. Enter the required user names to the fields shown in Figure 5-9.

Figure 5-9: Setting up ACL for DIIOP in server document

More information about how to configuring DIIOP for Domino is found in the Lotus Domino Administrator 6 Help database.

When loaded at the Domino server, the DIIOP task creates a file named DIIOP_IOR.TXT in the HTML directory, under the Domino directory. The file should be in ASCII format. DIIOP provides to the client an IOR number that is basically readable, but may make no immediate sense. The starting signature is "IOR:". IOR numbers presents information about the Domino server; you can also use this IOR number to create a session to Domino instead of using the server name.

DIIOP appears to need DNS for name resolution. This was more apparent on the iSeries™ and zSeries® machines. When using a Host file or no known name resolution, loading DIIOP may respond that it is starting on host.domain.root, then end with the error "Cannot determine hostname or host ip address." If this happens, fix your DNS resolution and try again.

DIIOP-related console commands

The Tell commands defined in Table 5-1 relate to DIIOP tasks. You can issue them from the Domino Server console.

Table 5-1: DIIOP-related console commands

Command	Result
Tell DIIOP Dump Config	Provide a list of the configuration data that DIIOP is using from the Domino Directory. Using dump, the configuration is written to the file diiopcfg.txt in the server's data.
Tell DIIOP Show Config	Provide a list of the configuration data that DIIOP is using from the Domino Directory. Using show, the configuration is displayed on the server console.
Tell DIIOP Log=n	This command determines the amount of information the DIIOP will log about it's operation. Valid values for n are as follows: 0 Show Errors & Warnings only 1 Also show informational messages 2 Also show session init/term messages 3 Also show session statistics 4 Also show transaction messages The setting of this command is saved in the NOTES.INI variable DIIOPLogLevel. Any change that is made to the DIIOP log level will be used the next time the server is restarted.
Tell DIIOP Refresh	Use this command to reload the configuration data that DIIOP is using from the Domino Directory and from notes.ini. By default DIIOP incorporates changes from the Domino Directory every 3 minutes, or as often as specified in the NOTES.INI parameter DIIOPConfigUpdateInterval. The Refresh command will force DIIOP to look for changes in the configuration and apply them immediately.
Tell DIIOP Show Users or Tell DIIOP Show Users D	Show all the current active users known to the DIIOP task. This list is similar to the server console command show tasks but it includes more information. Appending D to this tell command means the list of current users will also include the databases the user has open, along with a count of objects that are in use. Example: tell diiop show users d UserName ClientHost IdleTime ConnectTime SessionId Anonymous 9.95.74.178 0:00 0:00 SN00048DE22 perf/user1.nsf Objects in use: Databases: 1 Views: 0 Documents: 0 Items: 0 Others: 0 Users: 1, NetworkConnections: 1 IOP Show Users D

DIIOP debugging methods

If you are have problems while working with DIIOP, there is a set of debug parameters which might help you to solve them.

• DIIOP_DEBUG=1 sets the server to report verbose information about DIIOP.

  You can also debug in certain sections inside of the debug task like this:

      diiop_debug_connmgr=1    diiop_debug_cookie=1    diiop_debug_cwbase=1    diiop_debug_leaks=1    diiop_debug_objmgr=1    diiop_debug_refdata=1    diiop_debug_sslcert=1    diiop_debug_userobj=1 

• Other debug parameters you might find useful when working with CORBA are:

      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 

DIIOP transactions

Another good way to administer DIIOP is to look at transactions the server may already have done with DIIOP. This is done by typing SH STAT DIIOP from the server console. The server will display the following for each type of transaction:

• Total number of NRPC transactions (Count)

• Minimum duration of the transaction (Min)

• Maximum duration of the transaction (Max)

• Total time to perform all transactions (Total)

• Average time to perform the transaction (Avg)

All times are reported in milliseconds. This command identifies transactions that require excessive amounts of time. An example of the output from this command is in Figure 5-10.

Figure 5-10: DIIOP transaction information

---