What is the difference between the "NotesXspDocument" and "NotesDocument" class?
The XPages data sources are working with Java objects created using the regular Domino Java backend API. For this, the XPages runtime creates a Java session object for the user when a request comes in, and recycles it right after the request has been fully processed. This is mainly because HTTP is a stateless protocol, which implies that the server cannot sustain opened sessions between requests. As a result, all the backend objects used when the page was processed are discarded, and must be recreated when another request comes in.
To keep track of the changes that happened to a document, the XPages runtime is creating some "wrappers" on top of the backend objects. These wrappers record all the changes and when a new request comes in, and those changes are reapplied later when a new request comes in . This is what the NotesXspDocument is for.
Let's look at the document life cycle. On a typical example, a user will launch a form, edit the data, and submit the result to the server.
1 - The initial request
The user enters a URL in the browser and hits the form. On the server side, a new NotesDocument is created and wrapped within a NotesXspDocument. Some fields might be initialized, then the HTML is generated and sent to the browser. The NotesXspDocument is kept on the server, while the actual NotesDocument is discarded.
2 - Submitting the results
The user hits a button that forces a server roundtrip. In that case, the NotesXspDocument is restored and a new NotesDocument is created. The changes that have been recorded in the NotesXspDocument are applied to the newly created NotesDocument. Changes are made, recorded by the NotesXspDocument, and the response is sent back to the browser.
The NotesXspDocument is again kept on the server, while the NotesDocument is again discarded.
The actual, transient, NotesDocument is available to the user by calling NotesDocument.getDocument().
This function also features a parameters that tell the NoteXspDocument to apply the changes before returning the document.