ShowTable of Contents
The XPages2Eclipse feature described in this article works similar to a technique called "XAgents", covered by blog posts of Chris Toohey and Stephan Wissel:
Such an agent is useful when there is a need to programmatically create web content, e.g. web pages in a Domino based Content Management System, Office documents and spreadsheets, captcha graphics for authentication or to implement your own REST service.
So if there already is such a mechanism, why did we develop our own?
Well, when working with those XPages based "agents", we faced several issues that our implementation addresses:
Call code in other databases
This works fine on the web, because you can request content of other databases without problems as long as the current user has sufficient access rights.
But unfortunately it's not possible with XPages in the local Notes Client (XPiNC). There you can only call XPages in the currently open database. You would need to move all your configuration code into the application database to make this work, which messes up your architecture, because that code only belongs to the configuration database.
Parallel execution of requests
Routing many requests through a single XAgent XPage leads to bad application performance. The reason is that, up to Lotus Notes/Domino 8.5.2, code in an XPage runs sequentially for a single user. So if you let one XPage do a long running operation (e.g. output a large file or process many documents as part of a REST call), other XPages for the same user will wait until the operation is done (for experts: the XPage code is synchronizing on the HttpSession object while your code is invoked).
Our implementation in XPages2Eclipse does not need such a synchronization. Code execution occurs in parallel, only limited by the number of HTTP threads in the web server. You get maximum throughput.
Cache control for developers
As an XPages developer, you probably have experienced the issue that changes you make in Domino Designer sometimes are not visible after a page reload in the browser. The reason is that the XPages runtime caches the code for performance reasons and you often have to do a "restart task http" on your development server (which also restarts the JVM running XPages). This might be ok for web development on a local Domino server, but it's a real pain for XPiNC development. In that case, you have to restart the Notes client including Domino Designer!
Access to Notes Client APIs
In such a scenario, you could feed your UI elements through your own REST API and also implement the whole application logic as REST calls - a very clean approach, because the UI is completely separated from the backend code and can be replaced at any time.
For security reasons, it's disabled by default and can be enabled globally and on a per database basis.
Activation on Notes Client/Domino server
As mentioned before, the feature is disabled on a Domino server by default.
You need to add a Notes.ini variable in order to make it work. To enable the feature for a single database with filepath "path/to/database.nsf", simply define the following variable:
If we cannot find this variable in the server's Notes.ini, we check if the feature is enabled globally with the following line:
For performance reasons, the result of the variable lookup is cached and not read again until a server restart.
Unfortunately, in the local Notes client, we had to tweak a bit with the syntax, because the client's servlet engine does not allow the same syntax as on the web:
We provide a small Java class in order to make it easier to generate the right servlet URL syntax in your code:
<?xml version="1.0" encoding="UTF-8"?>
Please note that we had to tweak a bit in this sample and created an absolute URL (including hostname and port) from the current context URL to avoid that the XPages runtime automatically adds the prefix of the current database path to the URL when the page is rendered.
-Highly optimized for performance
-SSJS library contents, Java class files and resources cached in memory
-OSGI commands to flush caches
x2ejs drop all
x2ejs drop -n-
x2ecl drop all
x2ecl drop -n-
-code checks design element signature for all included libraries