Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "RAP/Server Push"

< RAP
(Session Expiration)
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The UICallback is RAP's mechanism to push UI-changes to the client.
+
'''NOTE: The UICallback mechanism has been reworked in RAP 2.0 into the ServerPushSession. This article does not yet reflect these changes.'''
It's based on the so-called [http://en.wikipedia.org/wiki/Comet_(programming) Comet] approach (specifically "XMLHttpRequest long polling"), i.e. it uses a long-standing request that is answered only in case of server-side updates.
+
  
=== Request Types ===
+
The UICallback is RAP's mechanism to push UI-changes to the client. It's based on the so-called [http://en.wikipedia.org/wiki/Comet_(programming) Comet] approach (specifically "XMLHttpRequest long polling"), i.e. it uses a long-standing request that is answered only in case of server-side updates.
There are two different types of requests involved:
+
  
* UI requests: normal Ajax requests that synchronize client and server.
+
=== Request Types  ===
  
* Callback requests: long-standing Ajax requests for server notifications to the client.
+
There are two different types of requests involved:  
  
=== Activation ===
+
*UI requests: normal Ajax requests that synchronize client and server.
  
The UICallback mechanism is activated and deactivated on the server.
+
*Callback requests: long-standing Ajax requests for server notifications to the client.
When the activation state changes, the property ''uiCallbackActive'' is updated on the client.
+
  
When the property ''uiCallbackActive'' is true, the client ensures that there is an active connection to the server.
+
=== Activation  ===
  
=== Callback requests ===
+
The UICallback is activated and deactivated on the server. When the activation state changes, the property ''uiCallbackActive'' is updated on the client.
  
After processing the response to a ui request, the client sends a new callback request if the ''uiCallbackActive'' property is true and there is no current callback request standing.
+
When the property ''uiCallbackActive'' is true, the client ensures that there is an active connection to the server.  
  
When a callback request fails, the client sends a new callback request to re-establish the broken callback connection. To avoid unnecessary load on the client, retry requests are sent with a suitable delay.
+
=== Callback requests ===
  
In the response to a callback request, the server can advise the client to send a ui request if needed.
+
After processing the response to a ui request, the client sends a new callback request if the ''uiCallbackActive'' property is true and there is no current callback request standing.  
Because every ui request must synchronize client and server, this ui request must contain any pending changes on the client.
+
This request does not differ from requests that are sent as a result of a user interaction.
+
  
The diagram below illustrates the interaction between client and server
+
When a callback request fails, the client sends a new callback request to re-establish the broken callback connection. To avoid unnecessary load on the client, retry requests are sent with a suitable delay.
 +
 
 +
In the response to a callback request, the server advises the client to send a ui request. Because every ui request must synchronize client and server, this ui request contains any pending changes on the client. This request does not differ from requests that are sent as a result of a user interaction.
 +
 
 +
The diagram below illustrates the interaction between client and server  
  
 
[[Image:Rap-uicallback-diagram.png]]
 
[[Image:Rap-uicallback-diagram.png]]
  
=== API Calls that affect the UI Callback ===
+
=== API Calls that affect the UI Callback ===
 +
 
 +
The following actions cause a standing callback request to be responded to.
 +
 
 +
==== UICallBack#activate() / deactivate()  ====
 +
 
 +
UICallBack#activate() enables the UICallback system. This method must be called inside of a ui request.
 +
 
 +
UICallBack#deactivate() causes a standing callback request to return if no other instance requires the UICallback system.
 +
 
 +
When the activation status changes, the next returning ui request will update the ''uiCallBackActive'' property.
 +
 
 +
==== Display#(a)syncExec()  ====
  
The following actions cause a standing callback request to be responded to.
+
The runnable that is passed to (a)syncExec() is put in a queue and executed in the next call to Display#readAndDispatch().  
  
==== UICallBack#activate() / deactivate() ====
+
If Display#(a)syncExec() is called outside of a ui request, it causes a standing callback request to return and trigger a new ui request. If a ui request is currently running, the (a)sync runnable is being processed by this ui request. In this case, the callback request is not released.
  
UICallBack#activate() enables the UICallback system. This method must be called inside of a ui request.
+
==== Display#wake() ====
  
UICallBack#deactivate() causes a standing callback request to return if no other instance requires the UICallback system.
+
If Display#wake() is called outside of a ui request, it causes a standing callback request to return and trigger a new ui request. If this method is called while a ui request is processed, it does nothing.  
  
When the activation status changes, the next returning request (either a ui or a callback request) will update the ''uiCallBackActive'' property.
+
=== Session Expiration  ===
  
==== Display#(a)syncExec() ====
+
Some servlet engines do not let sessions terminate while there is a request running. This would cause sessions to never expire while the UICallback is active. To prevent this, callback requests are released when they are standing longer than the session timeout interval.
  
The runnable that is passed to (a)syncExec() is put in a queue and executed in the next call to Display#readAndDispatch().
+
Regardless of how the servlet engine behaves are all active UI callbacks released when the session terminates.  
  
If Display#(a)syncExec() is called outside of a ui request, it causes a standing callback request to return and trigger a new ui request.
+
=== Display#timerExec() ===
If a ui request is currently running, the (a)sync runnable is being processed by this ui request.
+
In this case, the callback request is not released.
+
  
==== Display#wake() ====
+
Since version 1.5 M4, calling timerExec() causes the UICallback to be activated. Once the runnable given to timerExec() is executed, the callback is deactivated.
  
If Display#wake() is called outside of a ui request, it causes a standing callback request to return and trigger a new ui request.
+
=== Alternative: Polling  ===
If this method is called while a ui request is processed, it does nothing.
+
  
=== Session Expiration ===
+
This solution is to make the client issue requests at a steady interval. If any changes have occured to the UI on the server, the server will send the UI updates in response. The shorter the interval, the more network load is added by sending unnecessary requests frequently. This can be achieved in RAP, but is not officially supported. The code to enable polling looks like this:
Some servlet engines do not let sessions terminate while there is a request running. This would cause sessions to never expire while the UICallback is active. To prevent this, callback requests are released when they are standing longer than the session timeout interval.
+
  
Regardless of how the servlet engine behaves are all active UI callbacks released when the session terminates.
+
  String code =  "window.setInterval( function() {\n"
 +
                + "  org.eclipse.swt.Request.getInstance().send();\n"
 +
                + "}, 20000 );"; // polling interval in ms
 +
  JSExecutor.executeJS( code );
  
=== Display#timerExec() ===
+
Please note that this code makes use of internal API which may change without notice.
Since version 1.5 M4, calling timerExec() causes the UI callback to be activated. Once the runnable given to timerExec() is executed, the callback is deactivated.
+

Revision as of 09:28, 18 December 2012

NOTE: The UICallback mechanism has been reworked in RAP 2.0 into the ServerPushSession. This article does not yet reflect these changes.

The UICallback is RAP's mechanism to push UI-changes to the client. It's based on the so-called Comet approach (specifically "XMLHttpRequest long polling"), i.e. it uses a long-standing request that is answered only in case of server-side updates.

Request Types

There are two different types of requests involved:

  • UI requests: normal Ajax requests that synchronize client and server.
  • Callback requests: long-standing Ajax requests for server notifications to the client.

Activation

The UICallback is activated and deactivated on the server. When the activation state changes, the property uiCallbackActive is updated on the client.

When the property uiCallbackActive is true, the client ensures that there is an active connection to the server.

Callback requests

After processing the response to a ui request, the client sends a new callback request if the uiCallbackActive property is true and there is no current callback request standing.

When a callback request fails, the client sends a new callback request to re-establish the broken callback connection. To avoid unnecessary load on the client, retry requests are sent with a suitable delay.

In the response to a callback request, the server advises the client to send a ui request. Because every ui request must synchronize client and server, this ui request contains any pending changes on the client. This request does not differ from requests that are sent as a result of a user interaction.

The diagram below illustrates the interaction between client and server

Rap-uicallback-diagram.png

API Calls that affect the UI Callback

The following actions cause a standing callback request to be responded to.

UICallBack#activate() / deactivate()

UICallBack#activate() enables the UICallback system. This method must be called inside of a ui request.

UICallBack#deactivate() causes a standing callback request to return if no other instance requires the UICallback system.

When the activation status changes, the next returning ui request will update the uiCallBackActive property.

Display#(a)syncExec()

The runnable that is passed to (a)syncExec() is put in a queue and executed in the next call to Display#readAndDispatch().

If Display#(a)syncExec() is called outside of a ui request, it causes a standing callback request to return and trigger a new ui request. If a ui request is currently running, the (a)sync runnable is being processed by this ui request. In this case, the callback request is not released.

Display#wake()

If Display#wake() is called outside of a ui request, it causes a standing callback request to return and trigger a new ui request. If this method is called while a ui request is processed, it does nothing.

Session Expiration

Some servlet engines do not let sessions terminate while there is a request running. This would cause sessions to never expire while the UICallback is active. To prevent this, callback requests are released when they are standing longer than the session timeout interval.

Regardless of how the servlet engine behaves are all active UI callbacks released when the session terminates.

Display#timerExec()

Since version 1.5 M4, calling timerExec() causes the UICallback to be activated. Once the runnable given to timerExec() is executed, the callback is deactivated.

Alternative: Polling

This solution is to make the client issue requests at a steady interval. If any changes have occured to the UI on the server, the server will send the UI updates in response. The shorter the interval, the more network load is added by sending unnecessary requests frequently. This can be achieved in RAP, but is not officially supported. The code to enable polling looks like this:

 String code =   "window.setInterval( function() {\n"
               + "  org.eclipse.swt.Request.getInstance().send();\n"
               + "}, 20000 );"; // polling interval in ms
 JSExecutor.executeJS( code );

Please note that this code makes use of internal API which may change without notice.

Back to the top