XPiNC development insights

I am developing a rather large XPiNC application for IBM internal use. One application and parameter database pushes data around 10 backend databases. Part of the databases might be local (depending on the user), some might be on the server and not all users have access to all databases. Most of my business logic lives in Java code, both in classes, beans and managed beans. In the course of the development I stumbled over a series of insights a XPiNC developer should be aware of. Here it goes, in no specific order:

• FacesContext.getCurrentInstance() might return null when called in your Java class, depending on when you call it. I had calls to the FacesContext in some of my managed bean property calls which failed on page load with a Error 500 that the standard error page couldn't trap. You need the FacesContext to resolve any variable e.g. getting a handle on a different managed bean. In conclusion I rearchitected my beans to have only one managed bean per context modeled as Facade pattern that provides a single access point to all classes needed
• The ExtlibUtil.getCurrentSession() uses the FacesContext under the hood, so there is a distinct risk of getting a null session. So using the dependency injection pattern all calls requiring a NotesSession have a NotesSession as calling parameter. This requires a bean design that is populated elsewhere (e.g. DataContext, ObjectDataSource), so you can have getters and setters without parameters
• Longer running operations (stuff we typically do in an agent) will time out. You don't have the luxury in XPiNC to use agent.runOnServer(), so you need a different approach (and anyway I despise mixing XPages and agents). With the help of a friend and the ever impeccable Dublin team I figured a way to run Notes backend accessing code as a thread (subject to another story)
• Debugging is way less comfortable than in XPages. You have to put the whole client into debug mode, not just connect to the http task. So I tend to start my Notes client with -RPARAM -consoleso I see what System.out and System.err are producing. I also tend to keep my code in Java to make it more testable easily
• The XPages Debug Toolbar works well in XPiNC
• There is no way to restart the XPiNC task like you can restart the http task or the web preview task in Designer. When you use external jars and update them, you have to restart your client to test it successfully
• In a data source you can specify databases by replica id. This is nice since you might not know where a local replica is located. However you only can specify the replica id and unless NotesDatabase.openByReplicaId() not the server. So you never know which database you might get (local or one of the known server). So I compute once (and keep it in the sessionScope) the actual filepath, trying local first, and use server/filepath instead of replica id for data sources
• The Java Collection framework is your friend. You can use them nicely as source for a repeat control. Just keep in mind: a list will give you the entry in your instance variable, while a map will give you they key only. Of course a key can be any Java object, so some creative key creation goes a long way
• A very popular way in Notes applications was the use of NotesDocument.computeWithForm(). When connecting to existing applications you will be tempted (or actually required) to use it too. When the computeWithForm tries to trigger some UI interaction in the @Formula, your XPiNC tab will lose focus to a native tab (I haven't figured out which one gets selected) and a externalContext.redirect() will simply not happen
• In an XPiNC application sessionScope and applicationScope are local to the current user. So status exchange via applicationScope won't work in XPiNC. After all you run a local JEE server instance in your local Expeditor framework (a.k.a Notes client). This even applies when you load a server based NSF (hardly a good idea in XPiNC). This changes when you configure XPiNC to run on the server, then the applicationScope is for all users.
• Since XPiNC applications load all Java classes from the NSF into the JEE server memory, its best to load them from a local NSF, even for applications that need to have current data for all users. Here XPages' ability to use data from a different database comes in handy and you would load your data NSF from the server - I'll prepare some code snippets for future posts

As usual YMMV