New ODA Release and Design API Updated

  |   Blog   |   No comment

This week two new releases of ODA came out on OpenNTF and also published to OpenNTF’s artifactory repository, for those wanting to use ODA via Maven. They covered a host of new developments and some minor fixes from over the last few months since Domino FP8 was released. On ODA, it’s worth pointing out there is a short url for accessing the project on OpenNTF –

4.1.0 is the next FP8 release, the release notes are on the Release page on OpenNTF. Except for critical fixes, we’re not expecting to release updates for this, but there is a separate branch for this, develop-FP8.

4.2.0 is the corresponding release for FP9, covering all the additions in 4.1.0 and one additional core Domino API method, EmbeddedObject.getFileEncoding().

There have been a host of Javadoc updates, thanks to new contributor Jan Krejcarek. Nathan has done quite a bit of work around the Graph API. There have been a number of tweaks for Java 8 compiler compliance. The updates from XPages OpenLog Logger M7 have been incorporated into this ODA release. Some additions for getting the server name as a NotesName and in the abbreviated format have been included. And I’ve made a host of developments have been made around the Design APIs.

First, to address a question that has been raised about Java 8 and the improved date/time handling that it adds. It would make sense to use these when interacting with Domino dates, because they better handle timezones. However, there are complications (and I may be mis-remembering all the complications, so apologies if any of this is not correct). The core API only allows a DateTime to be instantiated from a Java Date or Java Calendar. There is a method in a DateTime for getTimeZone(), but not a setter – it can’t be set programmatically. The convertToZone() method, if I remember correctly, just adjusts the time. The timezone is set as the server timezone. In the underlying object, it’s stored using a complex set of abbreviations. But in addition to this, the timezone doesn’t capture whether it’s daylight savings or not. As I say, it’s all complicated, but from my investigations at the start of the year, in order to support the new DateTime classes in Java 8, we would need to convert the time to the server timezone, store it in a DateTime object, then convert the timezone and set daylight savings as appropriate (which can vary depending on how up-to-date the Java version is, because countries have been known to cancel or change daylight savings dates at late notice). And then there are a lot of new classes to use. I think to have a best practice, most reliable solution, it would be best if the core Session.createDateTime() methods and DateTime.toJavaDate() extensions could accept appropriate Java 8 date and time classes.

Another area that has been extended with this release is build-time tests. For a long time we’ve had various tests that can be run from Eclipse using the TestRunnerUtil class. But a while ago Jesse Gallagher added in a tests plugin and a small test that runs during builds. It creates an empty database in the temp folder, and that database can be interacted with (as long as the file isn’t encrypted, I eventually realised!). So for this release I added build tests running through the Database Property getters and setters. (This is what highlighted a quirk with the setters, which is elaborated on below.) Over time, as and when appropriate and possible, we’ll be expanding on these tests so they run whenever a build is performed, allowing us to minimise the risk of regression bugs.

Design API

The work done on the Design API has primarily been driven by two considerations. Firstly, some work we’ve been doing internally at Intec and will be announcing shortly covering database forensics. Secondly, the round table I ran at Engage on Domino Next Gen IDE, which is also relevant for XPages applications or OSGi plugins where the data NSF is separate from the application. This is relevant because for an OSGi plugin or XPages application, you may need to deploy design changes to the data NSF. But the refresh process for the data NSF is not necessarily the same as for the application. An OSGi plugin requires a restart of HTTP, but it may not be possible to make the changes to the design of the data NSF at a different time, and it may be difficult to ensure they’re refreshed from a template at the same time. The intention here is to be able to programmatically make the changes via an “upgrade” event when the application next starts up or triggered by an admin user at an appropriate time.

Although there is still work to do – there will always be more work to do – this release constitutes the first step on that journey. Full documentation has been added to ODA’s area of the OpenNTF Wiki. Ability to add / update / remove ACL roles and entries has always been part of the core Domino API, as well as ability to set maximum internet access and enforcing consistent ACL. There are settings to create a new blank database on the server or at a specific filepath. Full CRUD access is available via Java to Views, Folders and their corresponding Columns. All database properties that can manually be set via Notes Client are now accessible programmatically.

There are a very small number that were missed from the releases – setting the number of hours soft deletions expire in, setting the expiry for CSS, JavaSript, Image and files (which is set via Domino Designer Application Properties). Also, with 4.1.0 and 4.2.0, setting the DASMode has to be done via the Icon note, the corresponding setter was missed from DatabaseDesign class. But these are edge cases and unlikely to be critical. If there is a significant need, I can issue a point release with the functionality.

The functionality to create new Forms was missed also from this release. But Forms are not necessarily required for an application and are really nowadays documentation alone. Functionality is there to add and swap fields on an existing Form, but creating a new Form, removing fields, managing subforms is not yet supported.

Two key points are worth being aware of. When running tests directly from Eclipse, I’ve had problems accessing the DatabaseDesign if the server is running. I think this is to do with managing the DXL. However, I’ve had no problems running from XPages and consequently wouldn’t expect to have any issues running from an OSGi plugin.

The other key point is that it appears to Icon Note is cached by the Session. That confused me a lot, but it meant that when I ran tests that updated Database Properties that are stored in the Icon and then checked in the same test whether the value had changed, it looked like they hadn’t. But if I ran the check from a new test, it showed it had actually updated. Of course in a real world environment, it’s never going to be a problem, because you’ll update the properties from an XPages request or a REST service request, at the end of which the Session will be destroyed. And when the next request happens to actually use the properties, it will find they have been updated. But it’s worth being aware of if you’re keen to test your updates have actually happened.

A useful next step for all of these Design APIs will be to expose them as REST service CRUD endpoints, so that Angular or React or other JavaScript developers can manage the design, providing they are performing the update with the relevant authority. (In theory, I think security levels required would come down to Designer or above ACL access for the user the Session is running as, I don’t think they would be affected by Maximum Internet Access setting on the ACL). If you have any specific feelings around security aspects of this, by all means include them on the OpenNTF Slack’s ODA channel.

AUTHOR - Paul Withers

Paul Withers has been an IBM Champion since 2011, has been an OpenNTF Board Member since 2013, has worked with XPages since 2009, co-authored XPages Extension Library and was technical editor for Mastering XPages 2nd Edition. He is one of the developers on OpenNTF Domino API as well as contributor to a variety of other OpenNTF projects.

No Comments

Post A Comment