WGA Publisher, version 2.2.1, offers access to Domino databases via CORBA interface. This provides several new options for publishing of Web content out of Lotus Domino.

General information about CORBA and Lotus Domino

All Domino databases have so far been connected to WGA using the so-called "native interface". This interface is a non-network-based communication accessing the programme libraries of Lotus Domino directly via process requests. This is why a local installation of Lotus Domino is necessary for this interface.

CORBA is a standard developed by "Object Management Group" that enables programmes to supply internal objects to other programmes via the network. Lotus Domino starting with R5 has a CORBA interface for Java programmes for export of typical Domino objects such as databases and documents. With the release of R6.5 this interface is now efficient and fast enough to supply data to systems that depend on high performance publishing on a wide scale. WebGate Anywhere, version 2.2.1 upwards, now supports not only this native interface but also the integration of Domino databases using the CORBA interface.

This feature is very useful for customers who want to integrate data from Domino servers that are not running on the same machine as their J2EE server. It might also make sense to switch existing Domino implementation from the native to the CORBA interface as the following paragraph about the differences between the two approaches shows.

Difference between native and CORBA access in WebGate Anywhere
Beyond the fact that CORBA access is network-based, there are further differences compared to the native interface in WGA. Many of the differences described as follows are a result of our measures to increase the performance. Thus, WGA manages the CORBA connections in an internal connection pooling and starts all database sessions only with the master login (as opposed tothe native interface that starts the database sessions with the user logins).

Restrictions of the CORBA interface compared to the native interface:

• Additional reader and author fields that might exist in content documents will no longer be effective. Only the standard field "reader" that can be found in the content properties of the document is still valid. Regarding all other reader or author fields all users have the rights given by the master login that is managed in the WGA manager.
• Formulalanguage cannot access WebTML-Variables, when the evaluating Domino-Database is connected via CORBA
• User releated functions in formula language will not return data of the user that is currently logged in, but of the master login user
• The use of "Default" login as master login is no longer recommended for WGA 2.2 going forward and is not available for CORBA access.
• The use of memory will grow due to intensive caching. Administrator should see to an efficient maximum heap size for the J2EE server.
• The CORBA interface can only be used on Domino servers version 6.5.1 upwards.

Benefits and options of the CORBA implementation:

• J2EE-Server and Domino server can run on different machines. No Domino or Notes installation is necessary on the machine the J2EE server is running on .
• When using the native interface the only source for authentification (i.e. the directory of available logins) is the Domino directory. Using the CORBA access the Domino directory is still the standard source of authentification but other sources can be used as well. Thus, it is possible to define the available logins in a XML database, to read them from an LDAP server or to get them from any other Domino server that does not have to be the one that contains the published databases.
• Anonymous access to the Domino server can be de-activated but anonymous browsing in WGA can still remain possible.

Configuration of a Domino database for CORBA access

The integration of a Domino database in WGA is quite easy. The preferences are:

• It has to be a Domino server R 6.5.1 upwards.
• The DIIOP task of the Domino server must be enabled.
• The access must be enabled with name and password in the server document (Ports->Internet Ports->DIIOP).
• The name of the host must be typed in the server document ("Internet Protokols->DIIOP")
• The JAR file "NCSO.jar" has to be implemented in the class path of the J2EE server. The JAR file can be found in the sub-directory "domino/java" of the Domino data directory. In order to avoid possible class loading conflicts we recommend to switch all Domino connections from native to CORBA interface and to delete the JAR file "Notes.jar" from the class path as it is then no longer necessary. Otherwise the simultanous use of both JAR files can cause problems depending on the class loader architecture. This could result in necessary classes not being loaded.
  

Server document, "Internet-Protokols->DIIOP"

Please proceed as follows to configure the database for CORBA access:

• Start WGA manager. When you want to switch an existing database connection to CORBA access, look for its entry in the tab "content". Otherwise create a new database connection in the same tab.
• In the field Database type you find two entries, one for "WGA Content Store for Lotus Domino" and one for "Custom Lotus Domino Database". One entry ends with "(native access)". This is the described native interface to Lotus Domino. The other entry ends with "(CORBA access)" for the new implementation. Please choose the last one.
• In the field Database path you can enter the path to the database as usual. In front of this path, please enter the host name of the Domino server, separated with a semicolon. Please do not use loopback addresses such as "localhost" or "127.0.0.1". For best results enter the same host name you typed into the server document ("Internet Protokols->DIIOP").
• Enter a Domino login with user name and (Internet-) password as master login that
  • a) has manager rights in your database and
  • b) - when it is a WGA Content Store - has the user role [ADMIN] and
  • c) has the right to run "unrestricted methods and operations" (see server document, "security").
    
    The default login cannot be used as described before.

A Domino database configurated for CORBA access.

For personalization, too, there are now two types of databases. On the one hand the native one and on the other hand the one based on the CORBA interface. The configuration of the personalization databases on basis of the CORBA interface is the same as described above.

Optimizing the performance of publishing- cached queries

Although the speed of the CORBA interface has increased a lot in R6 some more steps are necessary to achieve appropriate performance when using this interface. One efficient tool is another new feature in WGA 2.2.1: cached queries.

Previously every time a <tml:query> tag was rendered in WGA, a request to the database was processed in the background even though the same request had been processed a hundered times before.This might be very ineffective as the results of many requests remain the same as long as the data in the databases has not changed. A simple request in formula language _news="y" only brings unique results as compared to the same prior request when a document has been created new, or has been modified or deleted and thus has changed the number of documents with the field "_news" and its content "y".

For this kind of requests stored queries have been integrated in WGA. Stored queries can easily be activated for existing <tml:query> tags by adding the attribute "cache":

<tml:query db="products" type="formula" cache="true">_news = "y"</tml:query>

This addition activates a temporary caching of the results of the request. All following queries of the same requests will then be supplied with the cached result without further access to the database. This is processed in this way until the content of the database has been modified which automatically leads to a deletion of the cache.

Requests with variable text using a parameter can be cached as well, e.g.:

<tml:query db="products" type="fulltext" cache="true"><tml:urlparameter name="searchFor"/></tml:query>

In this case for every variable of the search text a single cache is stored and managed. Thus, this function does NOT cache per query tag but it caches per search text.

Requests with criteria that are not based only on data from the database are not suitable for caching. One example is the first request of a current date in the request:

<tml:query db="products" type="formula">_showMeUntil < @Today</tml:query>

As the result of this request changes every minute and as it is not only dependant on changes in the database it does not make sense to cache it.

Optimizing the performance - TMLScript instead of formula language

The basis for all methods for increasing performance of the CORBA implementation is minimizing database access. One stepstone for this is the disclaimer of formula language in WebTML conditions and evaluation tags. As WGA itself cannot execute formula language it has to forward every single formula to the database and to request a result in return. This process leads to essential network traffic using the CORBA implementation which slows down the result.

Zusammen mit anderen Limitierungen der Formelsprache bei CORBA-Zugriff (Kein Zugriff auf WebTML-Variablen, Keine Abfrage der Benutzerdaten) bedeutet dies, dass die Formelsprache in diesem Fall sehr unattraktiv ist und generell durch TMLScript ersetzt werden sollte.
Together with other limitations of the formula language when using CORBA access (No acccess to WebTML variables, wrong user data) this means that formular language is generally unattractive in this case.

The use of TMLScript as an expression language brings a number of essential advantages:

• Generally it is faster than formula language as the codes do not have to be parsed every time.
• It can be interpreted by WGA itself. No access to the database is necessary just to execute the code.
• It makes use of every available cache in WGA when processing the data of the database. This reduces the access to the database as well.

You can switch the expressions in your existing database step by step from formula language to TMLScript in order to gain one small increase of performance after the other. It is even worth the effort to disclaim formula language completely as you can then disable the support of formula language which leads to an additional increase of performance. You can do so by using the following option:

FormulaSupport := false

Once the support for formula language is disabled, further steps inside WGA can be taken to optimize performance.

NOTE: The methods for optimization in this chapter do not refer to requests in formula language but only to formula language in conditions and evaluation tags. The disabling of formula language with DB option "formula support" does not lead to a disabling of formula language in requests.

Managing anonymous access to the Website

One advantage of using the CORBA interface is the fact that the Domino server does not have to allow anonymous connections for the WGA site to be browsable without authentification. It is still necessary to manage anonymous access to the WGA site i.e. it is still necessary to prevent it if it is not wanted. This can be done using the following option:

AnonymousAccessLevel := NOACCESS / READER / AUTHOR / EDITOR / MANAGER

This option manages the access level for anonymous access. The standard setting is READER. If you do not want to allow anonymous access to your website, choose NOACCESS.

Optional sources for authentification - optional Domino server

As mentioned before, using the CORBA implementation allows for sources for authentification other than the Domino directory. Source of authentication can be every application that can verify names and passwords. In WGA this source of authentication manages which logins the database accepts. This source can be configurated in the DB options in the WGA manager.

As default, the CORBA implementation authenticates itself against the Domino directory of the Domino server where the published database is stored. This authentication can easily be switched to the Domino directory of any other server. Only the following DB options are necessary:

auth.module := domino
auth.host := myother.dominoserver.de

The new authentification server has to be prepared for accepting CORBA connections via DIIOP task.

Optional source of authentification - XML File

Authentification can be based on a XML file as well. Only the following DB options have to be set:

auth.module = file
auth.file = C:\path\to\file.xml

The authentification module accepts the following XML format for definition of user logins and groups:

<users allowanonymous="true">
<user name="CN=Firstname Lastname/O=Organisation" password="thepassword" mail="the@emailaddresse.com" aliases="Firstname Lastname, vn"/>
<user .... >
...
<group name="[admin]" members="John Public"/>
<group ...>
...
</users>

Using this simple format you can name users and groups. Please note that all optional names that might be used in user fields (i.e. reader field in content documents) must be listed in the attribute "aliases". The attribute "allowanonymous" in the root tag manages the availability of anonymous connections.

It is striking that there is a group named "[admin]". As there are no roles in XML authentification, groups are equal to roles. Thus, you can grant certain content store access rights, normally managed via ACL, to the user by using role names as group names.

A cascade of groups (groups that have other groups as members) is not possible.

Optional source of authentification - directory services

In addition to described options you can use an LDAP server as source of authentication. This option is based on the "Java Names Directory Interface" (JNDI). It can use any JNDI source that accepts a login as the source of authentificaton. Due to the several possible options an authentification via JNDI is much more complicated to configure then the sources described so far.

The following DB options for exemple configure the authentication against the LDAP task of a Domino server:

Option	Value
auth.module	jndi
jndi.contextfactory	com.sun.jndi.ldap.LdapCtxFactory
jndi.path	ldap://my.dominoserver.de:389
jndi.objectclass.group	dominoGroup
jndi.attribute.mail	mail
jndi.nameattributes.people	cn,uid
jndi.nameattributes.groups	cn
jndi.dominonames	true

Please contact the Innovation Gate Support Team for configuration of a JNDI-based source of authentification.

Traps

Some problems you might run into and what causes them:

NoClassDefFoundError: lotus/domino/cso/Document (or similar classes)
The JAR file "NSCO.jar" is not stored to the class path or there is a loading conflict with "notes.jar". In the latter case you should either
a) switch all WGA connections to Notes databases to the CORBA interface and then delete the file "notes.jar" form the class path.
or
b) make sure, that Notes.jar and NSCO.jar are access via the same class loader. Some J2EE servers, like Websphere, have special functions for such a configuration.

NotesException: Could not get IOR from Domino Server: java.net.ConnectException: Connection refused: connect
No connection to the DIIOP server could be established. There can be several reasons:

• The host name in the database path is not correct.
• The DIIOP task of the server is disabled.
• The Domino server does not accept DIIOP connections under this host name as it is not equal to the host name in the server document ("Internet protokols > DIIOP".
• Port 63148 used by the CORBA connection is caught by a component of the network, e.g. by a firewall.
• The Domino server does not supply an IOR (some kind of network address for the CORBA connection) to above-mentioned port. This can be a the case with older Domino servers or with certain configrations. A work around may be to start the Domino HTTP task and to enter the port of this task together with the host name, e.g.:
  hostname:80:path/to/db.nsf

Please also check the comments on the Domino console that might help in analyzing the problem.

Instability of the CORBA connection, of the DIIOP task, resp. of the Domino server
The CORBA interface used to cause multiple problems in early R6 releases. We recommend the use of R 6.5.1 as it has proven stable in several testings of the WGA CORBA interface.