Tutorial: Simple ItsNat (Core) STATELESS Application
Last update: 2013, October 12
This new mode does not make full use of ItsNat capabilities, however many powerful features are still present ready to be used in this mode like pure markup templating, powerful DOM manipulation for view logic and rendering based on components (without AJAX/script events).
To fully understand this example, the stateless mode and how it is different with stateful mode, read first about ItsNat normal mode (stateful) for instance
reading the tutorial Simple ItsNat (Core) Application.
We are going to create a very simple Single Page Interface (using AJAX) STATELESS web application using the "core" part of the framework (without components).
First of all you need to download and decompress the ItsNat distribution and create a new web application with your favorite IDE, the name is not important, we will use "itsnat" in this tutorial. Follow the instructions explained in the download section, specifically the section "What does any new ItsNat based web application need?"
Let's to code
First of all we create a new servlet named servletstless, use your IDE and replace code with this:
The following code snippet registers the template of the initial page:
Note the setEventsEnabled(false) call, this configuration method call disables client to server stateful remote events, because there is no need of a ItsNatDocument kept in server to receive events, ItsNat does not kept the document in memory or in session, this setting is necessary if you want a true stateless document.
The stless_example.html file:
We realize there is another kind of remote events: stateless events.
This method accepts three parameters:
Transport mode and timeout parameters should be familiar to you because they are typically provided for configuration of a stateful document template.
This line is interesting:
ItsNat recognizes this standard “document load” parameter also in a stateless event, when received this stateless event in server, ItsNat server behavior is the following:
Used to the conventional, stateful mode of ItsNat, this stateless behavior seems non-sense, however, it has a lot of sense…
The main purpose of stateless event processing is:
As you easily can figure out, fully reconstructing the client state per-event may be very costly, in general stateless ItsNat mode is more costly on server processing than stateful, but it has the benefit of the unlimited scalability of stateless, adding more nodes and distributing events between nodes with no problem of data sharing or server affinity (this is an ItsNat point of view, use of session for your own custom data is up to you).
Fortunately you do not need to fully reconstruct the client page in server, you just can reconstruct only the parts being to be changed by the concrete event, furthermore, ItsNat stateless mode is exceptional for injecting new markup to the client page.
Continuing our example, Java code to generate the initial page:
This code is just an excuse to show how the initial page is a conventional ItsNat-generated page (but stateless), nothing especial here.
The interesting stuff starts with stless_example_event_receiver.html template registered with the name manual.stless.example.eventReceiver going to process stateless events:
Before continuing with the associated Java code, let’s stop to compare the initial page template:
and this template:
Both pairs of elements have the same id, this is not casual, for instance the containing of the insertHereId element of the initial page template is going to be the same as the “event processor” template, as you can see only the tag name (div) and the id attribute are the same, note how both elements are located in a different place (markup order related to body element) in the page, further we will explain this is the reason of the ItsNat attribute locById set to true.
The Java code associated to this template:
In summary this code updates the counterId element with the current value in page and inserts a template with name manual.stless.example.fragment into the element with id insertHereId, into the document loaded for processing the stateless event. Later we will see that this insertion finally happens into the final client page.
The markup of the template registered with manual.stless.example.fragment is:
Because this template is inserted calling docFragTemplate.loadDocumentFragmentBody(itsNatDoc) ignore everything but the content.
Let’s study the following code:
This check avoids trying to load this document, designed for processing stateless events, as a conventional page specifying a URL containing the itsnat_document parameter with the name of the template. The method ItsNatDocument.isCreatedByStatelessEvent() only returns true when the document has been loaded as part of processing of a stateless event.
Another more important use of ItsNatDocument.isCreatedByStatelessEvent() is to distinguish when the document was created to load a page as usual or to process a stateless event, because as you can easily figure out, in this very simple example the template for the initial page is so light than it also could be used for processing stateless events, thus this method could be used to separate the initial page load code (the presentation element construction) from the document load phase code when processing a stateless event (in this case registering the template-level event listener to receive the stateless event).
Note we are receiving a parameter counter with the current integer into the counterId element:
With this code we “reconstruct” the DOM state of the counterId element in client.
Finally in the load phase:
It registers “this” document object as the event listener to process the stateless event causing the load of this document. After the phase load, this listener will be immediately called and the stateless event passed.
This cast sounds familiar, ItsNat extends DOM Events with other kind of ItsNat-defined events, in this case stateless events are a new kind of “extended DOM event”.
The interface ItsNatEventDOMStateless inherits from ItsNatEventStateless, an object implementing ItsNatEventStateless interface is “a stateless event”. Later we will see a case of stateless event implementing ItsNatEventStateless but not ItsNatEventDOMStateless.
Now is time to really enter into the stateless approach of ItsNat:
Let’s repeat again the important (dynamic) elements:
As you know ItsNat node localization is based on “counting nodes in the tree” from to the concrete node, of course node localizing is smart and automatic caching happens to avoid traversing the tree from the root node. Anyway in some occasion full traversing happens, according to previous localization of elements in the first template is not the same as the second template, unless we explicitly avoid top-down traversing from root. This is the reason of ItsNat attribute locById.
Some code remains to explain:
As said before, location caching avoids fully traversing the tree from top, for instance ItsNat looks for parent nodes already in tree and cached, in this case the node insertHereId is the candidate, or any other child node cached when inserted. These techniques provide a powerful server centric Java based manipulation of the client DOM tree beyond simple one-time insertion.
We have finished our first ItsNat Single Page Interface Stateless web application!!
Stateless ItsNat applications/web sites are different to stateful, you must keep in mind there is no state in server and you must rebuild the needed client state when custom events are processed in server, if the client is replicated (only the parts going to change) you can use the magic DOM server to DOM client automatic synchronization, by this way you can render and change big parts of your web site/apps still using pure HTML templates and full view control.
See running online. Online example includes more advanced cases, they are explained in Reference Manual.