OpenNTF Domino API: New Release and Serializing Databases / Documents

Nathan has uploaded a new release of OpenNTF Domino API. There are a few significant differences in the upload this time.

Firstly there is a separate install for Designer Client and Domino Server. That’s to minimise the footprint for the server. Those who have used M4.5 may have noticed the Javadoc support was lost, because we were packaging org.openntf.domino as a jar and incorporating that in the plugin. That meant Domino Designer “couldn’t see” the source files, from which to see the Javadocs. Consequently the Designer install includes the source files for org.openntf.domino and other jars. But the server install just includes the jar files

Secondly, it’s been called RC1 – Release Candidate 1. Every release in the past has resulted in subsequent point releases to address feedback. We’d like to keep the full releases clean, so this is a release candidate and if there is nothing identified in the near future, that same code will be promoted as M5.

I will be uploading a release of the demo database in the near future. That will include a number of new pages, including one showing a XOTS tasklet in action. Nathan previously blogged about XOTS and it’s something that is very exciting. Currently XOTS is set up just for triggered actions – so kicking off a task on the server without waiting for it to complete. But it does allow named sessions, so triggering server-based activity to run under a specific named user. The core code has annotations for denoting a schedule, but the code to load that schedule to the server and act on it is not quite there yet. But it’s a high priority.

Recycling has been significantly overhauled and is quicker than before. This highlights the work of a newer member of the tean, Roland Praml. Devin Olsen has also contributed some code for managing names which includes some interesting functionality.

Please note that Javadoc comments are currently available only for the new methods added to the core Domino code. The help files are not open sourced, so we can’t just load those. We can’t point to them with a link, because the port number varies from install to install, otherwise we could nicely add a link out to Domino Designer’s help files. As you can appreciate, there are a lot of methods that need commenting.

One of the interesting but subtle enhancements, and the main focus of this blog post, is a new method for storing database or docuemnt references. If you’re only accessing the current database, that’s probably not a huge issue. If you’re in a suite of databases, you need to reference one another. You may also need to access documents from other databases. And potentially that could be on another server.

For databases, there is the API path. I’ve blogged about getApiPath() before. This basically gets the location of a database as Server!!FilePath. That’s standard for many XPages controls, but it also means all the relevant information about how to locate a database can be stored in a single field of a document, a single scoped variable or a single bean property. There is also the corresponding method – session.getDatabase(String) – for using the API path to retrieve the database.

For documents, it’s even more granular. Core Domino gives us the Universal ID. The OpenNTF Domino API brings the metaversal ID. Via Document.getMetaversalID() you get an ID that comprises the database replica ID followed by the document UNID. Document.getMetaversalID(String servername) goes further and prefixes the core metaversal ID with Servername!!. There are corresponding methods – session.getDocumentByMetaversalID(String metaversalId) and session.getDocumentByMetaversalID(String servername, String metaversalId). The former allows you to pass a metaversal ID, with or without the server name portion, and get the relevant document from the relevant database from either the relevant server in the metaversal ID or from the current server if not specified in the metaversal ID. The second method will only accept a metaversal ID that does not include the server name, allowing you to specify the server from which to retrieve the document.

Personally, these methods excite me quite a bit as a new way to serialize database and document references and retrieve the relevant object very easily.