One of the basic challenges of XPages development is how to effectively conduct initial tests on the applications you build. Unlike classic Notes development, where each change can immediately be seen in both local and server-based applications, XPages require a build & compile process in order to see the results of your work. Even in the case of classic Domino development for web browsers, it is still possible to see somewhat accurate results with the built-in preview capabilities of Designer.
However because XPages have their origins in Java Server Faces (JSF), and are closely bound to the run context of the Domino server, it is much more difficult to see what resulting behavior is in any other context than a running Domino server.
Let’s look at the options available today…
From the application design, select “Preview in Notes.” This activates the XPages-in-Notes-Client (XPiNC) interface for the application and displays it inside the Notes client itself. There are two basic problems with this rendition of the page: 1) the embedded XPages client is actually XULRunner 1.9.2, which is the equivalent of Mozilla Firefox 3.6, released in January of 2010 and officially out of support in April of 2012; 2) when running in the Notes client, the XPages servlet engine is executing within the context of the Eclipse framework, accessing HTTP content through an extended-port loopback connection, even when the NSF being viewed is itself on a server. This servlet does not support user credentials, nor does it have any of the plugins, databases or other runtime capabilities of an actual Domino server.
In a local NSF, select “Preview in Web Browser” from the application design. This again activates a local Domino server, this time listening on the HTTP-standard port 80. This local server does not support user credentials, so the application can only be viewed as Anonymous, and again does not have any of the runtime capabilities of an actual Domino server.
In a server-based NSF, select “Preview in Web Browser” from the application design. This approach will, at last, present a preview experience based on the code executing on the Domino server. Unfortunately, this may or may not represent the change that the developer intended, depending on whether he remembered to perform the Build command after saving his changes.
Of course, one way to work around this is to turn on the “Build Automatically” switch in Designer. This switch causes XPages applications to be built & compiled after each save of a relevant design element. While this might sound like a great convenience, it turns out that in real world applications, it can be prohibitively expensive, particularly when saving a change to a database on a remote server.
Additionally, let’s suppose that the server housing the NSF is a typical development server that might be shared by several developers at once. When the page is previewed and run on the server, it is then executing the code in the server’s context, which means it has the opportunity to affect all the other developers as well. Even a simple accidental loop can trigger a server hang and force a restart of the http service or even the entire server. All other developers must stop work until this restart is complete.
So local previews within the Notes client are not accurate renditions of Xpages. Web previews of local NSFs are not accurate. Web previews of remote server NSFs are accurate, but require lots of bandwidth, are fragile in practice, and can significantly reduce productivity of developers.
What, then, is the solution? Our recommendation at Red Pill is for each developer to run a local Domino server dedicated to hosting local versions of their applications. This gives them the ability to:
- Point Domino Designer to the local server for their design versions;
- Leave Build Automatically turned on, since they will have guaranteed high bandwidth throughput to the local server;
- Recover easily from catastrophic smoke test failures such as infinite loops or out of memory errors;
- Login as different users to test aspects of the application;
- Easily add OSGi plugins to the server for testing of advanced capabilities like the Xpages Extension Library;
- Easier access to error and trace log files for diagnostics.
This Domino server can be in the native operating system or in a hosted VM.
This is the standard development approach for other platforms such as Jboss, Websphere and Tomcat. And IBM recently announced at the IBM Connect conference that it will soon be releasing a developer virtual machine image to support exactly this mode of operation.
The Rabbit Hole 
as I was reading this, I saw this “This is the standard development approach for other platforms such as Jboss, Websphere and Tomcat.” its like you took my comment right out of my mouth
LOL. Yeah, when I hear people talk about working on XPages “on our development server” I always wonder if they’ve ever talked to people building for any other platform.
To be fair, though, you’re supposed to have a Domino license to run a server. So until IBM has the VM available with the licensing rules for it, you either have to spend a bit for each developer, or you have to be out of compliance.
..unless you have the software access option through partner world which I believe allows you to run any number of servers for dev purposes
to be fair though most Java Web Developers use some kind of “lite” server on their box like Tomcat or Glassfish or WS Liberty Profile, these integrate into eclipse well and some have many of the same admin-ey type things available like Domino.
Great post. Very timely as I’m just about to setup a local domino server for this very reason. I’m assuming then you’d need to use something like git if you’re part of a multi developer project though to sync back these multiple designs. I’m trying to figure out how best to organise that at the moment as we’re looking to move away from working against a central dev server to local ones. Am picturing a dev copy of the app on a central dev server linked to a git master branch, then local copies on local servers (one per dev) linked to different branches. the central dev copy then is a true reflection of the master branch. that sound sensible?
Martin, I’d actually suggest doing it a little differently, but I don’t have time to write up the complete detail yet. The short version is that you want to take replication completely out of the equation. Use SCM to sync a *template* between multiple developers. Then let each developer build and apply that template to non-replica test NSFs on their local servers.
All other methods I’ve seen in use result in replication colliding with SCM and pretty much disaster resulting from there.
Yep sorry I meant each developer would have a copy (not replica) of the db where the design is managed via SCM
What I initially struggled to get my head around was data. Unless it’s a really simple app a developer is unlikely to be able create their own copy of a db from a template and have something useable unless they can work with a sample data set. On the flip side if they have their own complete data copy that’s a lot of data maintenance as you can’t then get updates via replication if significant data changes occur.
Current thinking to tackle that is to try and create the app design where all references to documents/views etc are via settings doc which holds the server and dbname, even if it’s a single nsf app. That way a developer could temporarily point his local copy at the central db copy for data to do a ‘local’ preview of a his changes, but using the common server based data set. Not sure I’m explaining that well. Haven’t done it in practice yet but it works in my head. Would rely on the local server(s) all being part of the same domain as the dev server or cross certified etc which may result in other issues. Am going to trial it
And thanks for explaining to me of to cross-certify your main ID to use on that local server. For anyone who doesn’t already know http://www.intec.co.uk/making-your-local-domino-server-work-like-you-want/
Hi, the boss/admin has setup a domino server for me to use as a development server (not a web server) and I have access as the admin of the server. I’m using Notes, Designer, and admin 9 edition while the server is 32-bit 8.5.3 FP4 with extlib 9.0 install. Now, my admin ID is Administrator while the server is domsvr (short for domino server). Anyway when I try to preview a XPages application running on the server into my web browser (I use IE, FF, and chrome for testing), it always fail to preview and the link is something like domsvr:8080/MyApp.nsf/index.xsp. I change the port to 8080 because something is using 80 in that machine. Then, I change the domsvr part to 192.168.56.102 (which is the ip address of the machine), try previewing it, the browser ask for a credential and I enter Administrator and the password and voila it worked! But the only problem is whenever I have a computed field that displays session.getCommonUserName(), it always end up to be the name of the server ie: domsvr. Why is that?
Several points of note:
1) Using port 8080 is fine.
2) Instead of referring to 192.168.56.102, you should use 127.0.0.1 or the name “localhost”
3) Even better, go to your \windows\system32\drivers\etc\hosts file and add an entry for “domsvr” that points to 127.0.0.1.
4) When you’re running on the server, getCommonUserName() returns the server’s name because that’s the ID file in use at the time. Remember, your code is running ON the server. So what you want to use is session.getEffectiveUserName().
This is a great example of one of the differences between running a local preview or XPiNC versus running on an actual Domino server. It illustrates my original point perfectly, so thanks for that.
[…] There’s an excellent blog post by Nathan Freeman explaining the finer points here. […]