Home Overview Demos/Webs News Download/Install Docs/Support Investors/Partners Commercial Tutorial: Simple ItsNat (Core) Application Tutorial: Simple ItsNat (Core) STATELESS Application Tutorial: Single Page Interface SEO Compatible Web Site With ItsNat STATEFUL Using HASHBANGS Tutorial: Single Page Interface SEO Compatible Web Site With ItsNat STATELESS Using HASHBANGS Tutorial: Single Page Interface SEO Compatible Web Site With ItsNat STATEFUL Using HISTORY API Tutorial: Single Page Interface SEO Compatible Web Site With ItsNat STATELESS Using HISTORY API Tutorial: Hybrid Client-Server Centric Programming
Tutorial: Simple ItsNat (Core) STATELESS Application

Last update: 2013, October 12  


Setting up
Let's to code
Online demo

Before version v1.3 normal operation mode was ever based on keep in server the state of client (stateful mode), ItsNat basically simulates a Java W3C browser on the server, the server keeps a copy of the DOM of the user page, DOM changes in server are propagated to client automatically to synchronize it with the server via JavaScript code generated on the fly normally as a result of AJAX requests (or <script> based requests), AJAX requests are usually fired by DOM event listeners registered in server nodes and propagated to the same node in the client side.

In the stateless mode introduced in v1.3 there is no such as copy of the DOM of the client page in server, the approach is very different, the initial page load is the same but the "copy in server" is lost, with some data sent to the server via custom AJAX requests is possible to partially reconstruct on the fly in the server the client state to be changed, generating the corresponding JavaScript DOM modifications sent to the client as result of the AJAX request. Because client state is no longer kept in server an ItsNat stateless application is scalable to multiple nodes without shared data in the user's session or without the need of server affinity/sticky sessions (of course your can save your custom data in session, this is still possible but is up to you).

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.

Setting up

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:

This document template will be the initial page of our micro Single Page Interface Stateless example, remember this template is registered with stateful remote events disabled, however watch this JavaScript code line:

We realize there is another kind of remote events: stateless events.

This method accepts three parameters:

  1. An event object: following the same conventions as in custom events seen before in this manual
  2. A transport mode: an integer with the same values of org.itsnat.core.CommMode constants. Most of the time you’re going to pass 3 parameter (XHR_ASYNC_HOLD = AJAX asynchronous queued events).
  3. Timeout in milliseconds

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:

  1. A new ItsNatDocument is created based on the specified template. This document instance is stateless no matter the template was configured (setEventsEnabled(false) is just recommended for clarity and to avoid stateful loads using conventional URLs)
  2. Document load processing is as usual with a radical difference: final DOM state when loading phase ends is not serialized as HTML and initial JavaScript code generated in this phase is ignored/lost.
  3. The global event listener registered in load phase calling ItsNatDocument.addEventListener(EventListener) is executed receiving a stateless event. DOM modifications performed in this phase are sent to the client as return of the event in a similar way of a stateful remote event.

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:

  1. To reconstruct fully or partially the DOM client state in server: this is the purpose of the load phase, the final DOM state/tree of the document after loading must match fully or partially the client state.
  2. Modify accordingly the DOM state of the document to generate the necessary JavaScript to bring the client a new state: this is the purpose of the event processing phase.

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:

We said before that the objective of the load phase when processing the stateless event is to bring the loaded document to the same DOM state than the client part we are going to change when processing the stateless event into the event listener. As you can see the text node has been updated with a new integer value, the necessary JavaScript code will be generated and sent to client to update the counterId element in client as the result of the stateless event processing.

More actions:

In this case there is nothing done in the load phase related to insertHereId element because we want to reinsert the same DOM into this element again and again and custom JavaScript code is easier to clean the current state in client (ItsNat stateless mode ItsNat is much more client centric and JavaScript knowledge is recommended).

This code requires more explanation, the document we are modifying was created based on the template with name manual.stless.example.eventReceiver, this template is similar but not the same as manual.stless.example, notwithstanding the JavaScript generated is sent to modify the later.

Let’s repeat again the important (dynamic) elements:

  • manual.stless.example
  • manual.stless.example.eventReceiver

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.

The locById attribute tells ItsNat to use the id attribute/property in generated JavaScript to locate the node just calling getElementById(). By using this trick you can make ad-hoc lighter templates with just the enough markup aligned with the client DOM state.

Some code remains to explain:

This conventional ItsNat code inserts a modified version of the markup inside of the loaded template manual.stless.example.fragment into the element insertHereId. The interesting detail of this code is most of the DOM modifications happen after insertion in document (remember that corresponding JavaScript DOM code is generated on the fly), any node involved, child1, child2 and textChild2, need to be located after insertion, are they located traversing the full tree from ?


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.

Online Demo

See running online. Online example includes more advanced cases, they are explained in Reference Manual.

Terms of Use Privacy Statement Contributor Agreement Add to deli.cio.us Single Page Interface logo ItsNat logo Innowhere logo