Single Copy XPage Design – Some Learning and Why It's Not For Me

In a recent project I decided to use Single Copy XPage Design (SCXD). This is a seemingly useful technique that is in many ways similar to the concepts underpinning XPages on Bluemix: one database holds the data and it points to another database that contains the XPages-specific design elements – XPages, Custom Controls, StyleSheets, Themes, Images, custom Java code and third-party jars. (At this point, it’s worth stating that although the concept of two NSFs is similar, my understanding from the demos I’ve seen is that Bluemix is sufficiently different in its runtime to make me hopeful that the critical issue I’ve encountered will not be relevant on Bluemix.) So if you have lots of XPages applications, all sharing the same design, it makes sense to use SCXD to minimise memory and, so it would seem, ease deployment of changes to the XPages elements.

The explanation of SCXD in Mastering XPages Second Edition is focused on its benefits for XPages in the Notes Client and, as one would expect from a book on the topic, concentrates on the “how” rather than going into depth on the real world experiences of development and implementation. That’s not a criticism of Mastering XPages, it’s a statement of what to expect from any book that introduces technical advancements, and the same was true of what I wrote for XPages Extension Library book. When writing a book, you are getting to grips with the basics and don’t have the time to go through a whole project using it in a customer environment. Similarly, no blogger has blogged on real-life implementations of every single piece of technology in XPages Extension Library or Mastering XPages, nor would anyone reasonably expect them to. We blog about our experiences and learning, both so others can learn from our knowledge and so we can easily find it when, a year from now, we hit the same problem!

So here is my detailed experiences of a few obvious gotchas and a big problem I’m yet to find a solution for.

Firstly, in this blog post I will talk about:

• the master database, which is an NSF where the XPages-related design elements reside.
• the slave template, which is an NTF from which each slave database picks up its design.
• the slave databases, which are NSFs containing the data and any design elements required for data design and scheduled processing, e.g. Forms, Views, LotusScript Script Libraries, Agents etc.

A slave template is required. Trying to set or change the XPage Design Store Path in the Application Properties of a slave database doesn’t work – in my experience it will still look to its own design. Also, you can’t point a database to itself, so you can’t have a single template for master and slave. You have to split your design. If you try to point it to itself, the XPages runtime gets in an infinite loop, understandably. (I at least wanted to try this, because I was moving from a single database design to SCXD, and having several pointing to one instance would have minimised the changes I needed to make.)

The first thing to note when starting your development of the slave template is that it must have an XPage with the same name as the one in the launch properties. It doesn’t have to have the same design, and indeed I would strongly recommend having a different design, so it’s obvious if the SCXD settings are incorrect.

Initialising SCXD

If SCXD has never been used before, this is fairly straightforward.

1. No changes are required to the Master Database.
2. Open Application Properties in Designer on Slave Template.
3. Go to XPages tab.
4. Tick Single Copy XPage design and set XPage design store path. The format for the Master Database location in a folder is folder\filename.nsf.
5. Refresh the design of the Slave Databases.
6. If SCXD has not been in place before, there is no need to restart task http.

Things get trickier if you need to change the Master Database location or want to remove SCXD completely.

1. Open Application Properties in Designer on Slave Template.
2. Go to XPages tab.
3. Untick Single Copy XPage design (to remove) or tick Single Copy XPage design and set XPage design store path (to change).
4. Refresh the design of Slave Databases.
5. Issue restart task http command to console.

One reason you may need to change the Master Database location is if you have a different location on development / test / production servers. If no database could be found at the XPage design store path location, the design of the Slave Database will be used instead. This is a good reason for giving an informative message on the Home page.

The reason for needing to restart HTTP is that once any Slave Database is in use, the Master Template design is cached in the XPages Runtime for use. Some functionality, like changing the SCXD location, doesn’t force a reload.

In terms of development, changes to XPages, Custom Controls, CSS etc get picked up immediately. New Java methods or classes also get picked up immediately. However, changes to existing Java methods seem to be cached and are only picked up after an HTTP restart or after the Master Database is removed from memory, because all instances have timed out. As I mentioned on StackOverflow, I’ve been unable to find any way to reload the Master Database into memory. No actions taken upon it remove it from memory. Thanks to Eric McCormick, I also tried ticking Refresh entire application when design changes (xsp.application.forcefullrefresh=true), but that has no effect either. Issuing the console command tell http xsp help gives a whole host of useful XPages-related console commands, but none for reloading an application. There are commands for reloading OSGi bundles, but not NSF classes.

I haven’t yet worked out exactly how SCXD designs are cached differently from normal XPages applications. I have deduced that they must be, because cleaning the Master database has no effect for SCXD, whereas it works fine for a normal XPages application.

Similarly, if your applications use only SSJS, SCXD is a very useful approach.

But the problem becomes significant for deploying to a production environment when a View and XPage need to be amended, but also the Java controller class for that XPage: the view and XPage designs are used immediately after a refresh, but the application then throws unexpected errors because the backend Java method cannot be found, because the cached version of the Java class is used until an HTTP restart. Obviously on a production server, where that has to be scheduled, it causes problems for deployment.

Currently, my approach has been to move everything back into a single template. It means more effort during deployments, refreshing the design of more databases. Longer term, I may use SCXD again, but move the Java classes into a plugin, since that can be reloaded independently of the rest of the runtime. It means an extra element in deployment, but changes to XPages only will require deployment to two places instead of fifty.