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.

6 thoughts on “OpenNTF Domino API: New Release and Serializing Databases / Documents”

  1. “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.”

    I have some stuff stubbed out in a few of the helpers to make this easier. Serializing the entire metaversalid for a collection of documents is kind of wasteful since they will most likely only be in a handful of NSFs. So I’m doing some index mapping of that and then compressing the UNIDs to byte[16] structures instead of char[32].

    DominoUtils might already have compress/expand unids now that I think about it. I’d check myself but I’m in the middle of something. 🙂

  2. Sweet stuff. Nice work. I was thinking about how to use the MetaversialID and figured it would be nice to use this to produce SEO friendly human readable URL:s (among other things 🙂 – that is if it’s possible to encode/decode the meta id in the current release? similar to what we wan do with unids)

    When moving to separate a separate client/server install what is the preferred way to install the API? (osgi/drop jar in lib/ext ?)

    1. Adding a jar in lib/ext won’t work any more, as far as I know. Adding to an Update Site for the server is recommended. If you have a local server and want to debug, it’s worth pulling down the source from GitHub and adding to Eclipse, so it’s available with the Domino Debug plugin. For a small number of developers, installing the client update site manually is fine. For more developers, it’s worth using policies to push out as a widget, so it’s automatically added for install.

    1. The current eclipse build process is configured to compile JARs for an update site only.
      You cannot use these JARs for agents (by putting them into the lib/ext dir) or for standalone programs.
      You can try to export the “org.openntf.domino” and the dependent projects (org.openntf.formula/com.ibm.commons) as JAR by right clicking on the project in your eclipse designer and select “export/JAR file”
      (I did not try this, but it should work… at least in theory 🙂

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.