<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="copyright" content="Copyright (c) 2007, 2013 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <title>Server Push</title>
  <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
</head>
<body>

  <h1>Server Push</h1>

  <p>
    Sometimes it's necessary to “push” UI updates from the RAP server to the RAP client.
    As an example, imagine a chat application that notifies the user of a chat request from a peer.
  </p>
  <p>
    HTTP is not designed to actively push data to the client.
    A RAP server can only answer requests from a
    <a href="client.html">client</a>, but it cannot actively send any message
    to the client. In RAP the UI is typically updated
    within a request caused by a user interaction, in which case this restriction is not an issue.
    However, when the UI is <a href="threads.html#asyncexec">updated from a background thread</a>,
    there's usually no request that could fetch the UI updates from the server.
    In this case the UI changes would not be rendered until the next HTTP request is triggered.
  </p>

  <h2>The Solution</h2>

  <p>
    Using the so-called Comet (or “long polling”) approach, the server is able to notify the client
    <em>immediately</em>. The basic idea is that the client sends a request to the server that is
    not answered until the server needs to notify the client of a change.
  </p>
  <p>
    RAP provides an implementation of this mechanism which can be used via the
    <em><a href="../reference/api/org/eclipse/rap/rwt/service/ServerPushSession.html">ServerPushSession</a></em>
    API.
    <strong>Before</strong> starting a background task, create an instance of <em>ServerPushSession</em>
    and call
    <em><a href="../reference/api/org/eclipse/rap/rwt/service/ServerPushSession.html#start()">start</a></em>.
    When the background task has completed and no longer needs the
    server push mechanism, call
    <em><a href="../reference/api/org/eclipse/rap/rwt/service/ServerPushSession.html#stop()">stop</a></em>.
    Example:
  </p>
<pre class="lang-java">
final ServerPushSession pushSession = new ServerPushSession();
Runnable bgRunnable = new Runnable() {
  public void run() {
  // do some background work ...
  // schedule the UI update
  display.asyncExec( new Runnable() {
    public void run() {
      if( !widget.isDisposed() ) {
        // update the UI
        label.setText( "updated" );
        // close push session when finished
        pushSession.stop();
      }
    }
  } );
};
pushSession.start();
Thread bgThread = new Thread( bgRunnable );
bgThread.setDaemon( true );
bgThread.start();
</pre>
  <p>
    A UI session may create and start any number of <em>ServerPushSession</em>s in parallel.
    The framework will keep the server push enabled as long as there are any active push sessions.
    That is, for multiple push sessions, there is only a single request needed.
  </p>
  <p>
    Note that unlike
    <em><a href="../reference/api/org/eclipse/swt/widgets/Display.html#asyncExec(java.lang.Runnable)">Display#asyncExec()</a></em>,
    <em><a href="../reference/api/org/eclipse/swt/widgets/Display.html#timerExec(int, java.lang.Runnable)">Display#timerExec()</a></em>,
    does <em>not</em> require an explicit <em>ServerPushSession</em>,
    as RAP creates one automatically in this case.
  </p>
  <p>
    More technical details of the ServerPush implementation can be found on the
    <a href="http://wiki.eclipse.org/RAP/Server_Push" target="blank">RAP Wiki</a>.
  </p>

</body>
</html>