Genii Weblog

Branching out: Why the domino-db Document is not like NotesDocument

Thu 6 Feb 2020, 11:08 AM

by Ben Langhinrichs
Posts in this series: 
As a longtime Notes developer, I remember when Java classes were added to mirror the LotusScript classes in Notes/Domino. While they were not identical, they were damn near. Of course, as a LSX developer, I had a good idea why that was true. The latest LSX Toolkit (Version 3, I think) was released with the ability to add a thin layer of Java support around the classes defined for LotusScript. Since the backend classes were implemented internally very much like those created with the LSX Toolkit, the mapping between the existing NotesDocument class in LotusScript and the Document class in Java. You could see the direct mapping between LotusScipt and Java for every method and property. The NotesDocument.AppendTextValue method begat the Document.appendTextValue with little more than a camelcased name change.
So, when I heard that Node.js support was being added with classes for updating Domino data via JavaScript, I naively thought it would be the same. But I couldn't have been more wrong. If you look at the methods listed in the AppDev Pack documentation, it is surprisingly sparse, and even more notably, totally different.
Inline JPEG image
The first two are really just getters for properties, leaving seven methods total for manipulating the document. 
I must admit, my first instinct was that HCL had "cheaped out" and just not bothered. I'm not proud of that, but it all felt so minimal. But after working with the implementation, I realized that there were reasons, and I thought I might share those reasons. They help explain why we see what we do, but also set expectations about what we might see in the future. Caveat: I have no inside information. I haven't talked about this with anyone at HCL. They might even be happy to share information, as HCL is pretty open about things. If anybody wants to ask and share their comments, or anybody from HCL wants to chime in, the comments are open!
As I see it, this is a better way to look at things (for those who don't know, ≈ means "approximately equal"):
NotesDocument (LotusScript)  Document (Java)
Document (Node.js)  REST API (Domino Access Services) or Stateless Web App
To understand why this is, let's talk about thin vs. fat clients and also about the notion of stateless interactions.
Client/Server in the Notes/Domino sense
We are used to Notes, which is a very fat client. It takes  lot of disk space and a lot of memory because almost all the code from Domino is repeated in Notes, and then more is there for the GUI and frontend, etc. etc. It also takes a lot of memory to run, and assumes you have a lot of memory to play with. While communication between client and server is over NRPC (Notes Remote Procedure Call), that is deceptive with something like the NotesDocument. When a NotesDocument object in LotusScript or a Document object in Java reads in a document from a server-based database, it reads in the whole frigging thing. All of it sucked up into memory, because we have lots of that to play with, right? Then, all those interactions with the object, almost all the methods, and setting and getting all the properties, happens to the document in memory on the fat client. There are no NRPC calls back and forth, no matter how much is done, until you finally save the document "to disk", at which point the whole humongous glob is sent via NRPC back up to the server. 
  • Memory and processing is localized, so no matter how many different people are working on documents in memory, the server isn't feeling a thing
  • We can take our time working with a document which might be open for minutes or hours before we save
  • If the server goes down or the connection is broken, we can keep working and just save when it comes back.
  • While we are off working on one copy of the document, others could be working on other copies of the document, so save conflicts become an issue
  • Fat client means we need all the DLLs and everything on any client we use. Even skipping Eclipse, this is huge!
  • Every OS has to be supported natively. (This is lessening as HCL moves to Web Assembly, but still significant.)
Client/Server in the Node.js AppDev Pack sense
The domino-db classes are completely different. They are very small and quick, and operate by sending any read/write/whatever as a message up to the Proton task on the server. That means that almost none of the resources are localized. While it appears to us that we are "getting a Document" the same way we do in LotusScript, that is completely untrue. We are basically getting a link to a document, so that when we send a message to the server (via the Proton server addin), the document can be acted on.
  • While the Notes client takes 300MB+ disk space (a little less for Basic client), the entire domino-db module under 0.5MB (or up to 28MB for all dependencies, but many are common and shared with other Node.js packages so will already be there).
  • Very few local resources are required
  • Can run anywhere on any client or as part of any other module - totally standards-based
  • Even minimalist IoT devices could drive interactions.
  • Every update saves the documents
  • Very limited local functionality
  • Must reach out to server for every piece of information rather than getting it all at once.
What does all that mean? Will we ever get full Notes classes in Node?
We probably will, but their use will be limited. It is every bit as possible to put a thin skin around the base classes for JavaScript as it was for Java. HCL could fairly quickly recreate everything in the Java classes as Node.js classes. But if they do, the client will have to be as fat as it is now, the resources will all be localized, and much of the typical Node.js way of handling things will be out the window.
Of course, they could also do a half-and-half solution where everything was implemented via messages the way domino-db operates. This would be somewhat akin to adding sessions to the web, as all the resources would then be opened on the server. The client would still be fairly thin and flexible, but the load on the server would be a huge issue, and this would add all the issues of session-based web document but with massive memory requirements for the server. The longer a session is maintained, the harder on the server. Web-based sessions do not require the entire document to be in memory the entire time. Imagine a thousand clients with an open document, each of which might take a MB or more of memory, and suddenly you have GBs of RAM dedicated just to handling the objects in memory.
So, the practical way is to put the thin wrapper around the base classes, re-use the same libraries that the Java and LotusScript classes do, and not use that module on small phones or iOt devices. I can see why HCL would hesitate, but I think they'll do it eventually. Now, you'll at least understand why they weren't quick to jump on that bandwagon.
Vague side hint
There a third option which we are pursuing for an Exciton product-to-be-named-later. I don't think HCL will take that approach, but you never know.

Copyright 2020 Genii Software Ltd.

What has been said:

No documents found