Build servlets in JavaScript

Abstract

ShowTable of Contents

HideTable of Contents

1 Introduction
2 Motivation

2.1 Call code in other databases
2.2 Parallel execution of requests
2.3 Cache control for developers
2.4 Access to Notes Client APIs

3 Activation on Notes Client/Domino server
4 Servlet URL syntax
5 Code and data Caching
6 Advanced features
7 Security

Introduction

The XPages2Eclipse feature described in this article works similar to a technique called "XAgents", covered by blog posts of Chris Toohey and Stephan Wissel:

IBM Lotus Notes Domino REST Web Services via XPage XAgents

Web Agents XPages style

In short, XAgents are an XPages version of classic Domino web agents or HTTP servlets: a piece of code which is called via a URL from the web browser and which produces content by writing text or binary data into an output stream. For XPages development, this code is written server side JavaScript (SSJS).

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.

Motivation

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

Let's say you have an application that consists of at least two databases, one application database and one that stores configuration data. For a clean architecture, you would like to put all configuration related code into the configuration database, including a REST API that you want to call from client side JavaScript code in the application, e.g. to read configuration data or store user preferences.

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.

The implementation we picked for XPages2Eclipse has a different approach: It uses its own servlet implementation to handle a HTTP request and pass it to your JavaScript or Java code. It supports calling code in other databases (stored locally or on a server), making sure that it can only be called by code in an XPages application and not from a local browser.

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!

XPages2Eclipse provides (OSGi) console commands that you can use to clear the caches we use: one for SSJS library content (which we execute for our JavaScript servlet technology) and another one for any custom Java class that your code is using. This makes it easy to develop and test an application in a short amount of time.

Access to Notes Client APIs

Originally, the first idea behind our "JavaScript servlet" implementation was to make the XPages2Eclipse APIs accessible for developers who are not using the normal Dojo/Ajax request mechanism of XPages to call server side code from UI code (e.g. IBM's "XSP" JavaScript library), but prefer other frameworks like Ext.JS or JQuery. As you may know, Dojo and XPages client side runtime code can be disabled with a database property "xsp.client.script.libraries=none", as mentioned in this blog posting:

XPages without javascript - disabling dojo

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.

We support this approach by making an "eclipseconnection" object available as a global variable to your JavaScript code when it is run in the local Notes Client. Use it in your JavaScript code as if you had created the connection regularly with X2E.createConnection().

Since we found out that the JavaScript servlet technology would also be very useful for Domino applications on the web and not just locally (even without the "eclipseconnection" object), we decided to add a Notes.ini switch to make the feature work on Domino servers as well.
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

Javascript servlets are enabled by default in the local Notes client, protected by security mechanisms so that only code coming from an XPages application can invoke them.
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:

mndX2ERPCEnabled_path_to_database_nsf=true

If we cannot find this variable in the server's Notes.ini, we check if the feature is enabled globally with the following line:

mndX2ERPCEnabled=true

For performance reasons, the result of the variable lookup is cached and not read again until a server restart.

Servlet URL syntax

For technical reasons, the URL syntax to access the JavaScript servlet on the Notes client is different than the syntax on a Domino server.

For the Domino server, just append the string "/x2erpc/js" to a database url, followed by the name of a SSJS library and the name of a JavaScript function:

http://-hostname_of_server-/-path_to_database-/x2rpc/js/-name_of_ssjs_lib/-name_of_js_function_in_lib

for example:

http://www.mindoo.com/office/address.nsf/x2erpc/js/restapi/service

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:

http://127.0.0.1:1234/x2erpc/Server1%5cMindoo!!office%5caddress.nsf/restapi/service

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
    xmlns:xpages2eclipse="http://www.mindoo.com/x2e">
    <xpages2eclipse:apiinit id="apiinit1"></xpages2eclipse:apiinit>

    <xp:link escape="true" text="Link to Javascript servlet" id="link1">

    <xp:this.value><![CDATA[#{javascript:var url = context.getUrl();
var baseUrl=com.mindoo.xpages2eclipse.tools.URLHelper.getRpcUrl(database);

url.setPath(baseUrl+"webrpc/doget/test");
return url.toString();}]]></xp:this.value></xp:link>
</xp:view>