Clean AJAX Anatomy

At first point we would like to brief explain the Clean anatomy, to give you an overall understanding about the approach used by the project to deal with asynchronous requests.

As described latter Clean is inspired on the Java Message Service (JMS), that is a technology, present on the Java Enterprise Edition (JEE) specification, used to enable applications to exchange messages (asynchronously or synchronously) using a Message Oriented Middleware (MOM).

The core of Clean is to represent AJAX requests as messages, which offers a well established model to deal with asynchronous communication. Is important to note that in Clean both messages' producer and consumer are on the client-side. Clean's messages are not consumed at the server-side, but they request some server-side processing and bring the response back to a consumer at client-side.

A message producer will be always some JavaScript function or object. The message consumer can be again some JavaScript function or object and also a DOM element, it depends on the onChange event handler present in each message.

Messages offer a very flexible model, where we are able to combine plain attributes to get many different behaviors at request and/or response. The sequence diagram presented bellow shows the generic scheme used by Clean to establish communication with server-side using messages.

As we can see messages offer also an event model that can be used to override or extend the message behavior. Clean provides a message event model composed by three events - onChange, onComplete and onError.

The onChange event notifes a message that the request state have changed, it is used as the onreadystatechange listener of the embedded XMLHttpRequest object used by the message to perform a request to the server-side. All messages must have a handler to this event, in fact Clean provides a default built in onChange event handler that is automatically applied to any message that don't have an onChange event handler.

The onComplete event notifies a message that the request is finished, it receives as parameter the XMLHttpRequest object used to perform the request .

The onError event notifies a message that an exception has occurred, it receives as parameter the exception occurred.

Messages also offer the concept of state, that may vary during its life cycle. The state diagram presented bellow explains the possible states of a message on Clean.

As we can see a New message is a message that have been ever sent, when this occurs the message id attribute is defined and it becomes Active. When the message is complete, the message becomes Finished. A Finished message can be resend and becomes Active again in a process that can be repeated indefinitely until message destruction.