bundles/org.eclipse.rap.doc/guide/articles/server-push.html - rap/org.eclipse.rap.tools - Git at Google

 <?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, 2020 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() {
   @Override
   public void run() {
     // do some background work ...
     // schedule the UI update
     display.asyncExec( new Runnable() {
       @Override
       public void run() {
         if( !label.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>
	<?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, 2020 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() {
	@Override
	public void run() {
	// do some background work ...
	// schedule the UI update
	display.asyncExec( new Runnable() {
	@Override
	public void run() {
	if( !label.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>