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