blob: 02ba67aeb2306cb50f03a69606eaa68b5db5fa05 [file] [log] [blame]
<div>
<h2>New Java API for Custom Widgets</h2>
<p>
With RAP 2.0, it's becoming a lot easier to write custom widgets or other add-ons for RAP.
We've published a new Java API to synchronize server-side objects with their related objects
on the client.
This API is built on the new <a href="http://wiki.eclipse.org/RAP/Protocol">RAP protocol</a>
and it lets you send updates directly to the client
(and receive updates from the client in turn) without diving too deep into RAP's internals.
In particular, you don't have to write any so-called LifeCycleAdapters (LCAs) anymore.
</p>
<h3>RemoteObject</h3>
<p>
The central interface, called <em>RemoteObject</em>, is used to communicate with the client-side
counterpart of an object, the <em>remote</em> object.
First you need to create this object, then you can start sending updates to it
by simply calling the remote object's <em>set</em>, <em>call</em>, etc. methods.
</p>
<p>
The following snippet shows how to create a remote object of the type
<em>example.CoffeeMachine</em> and set the property <em>sugar</em> to the value <em>false</em>.
That's all there is to do to send a <em>create</em> operation to the client with the initial
property included.
</p>
<pre class="lang-java">
Connection connection = RWT.getUISession().getConnection();
RemoteObject remoteObject = connection.createRemoteObject( "example.CoffeeMachine" );
remoteObject.set( "sugar", false );
</pre>
<h3>OperationHandler</h3>
<p>
To receive updates from the client, you have to add an operation handler to the remote object.
This operation handler has <em>handle…</em> methods for all relevant protocol operations.
</p>
<pre class="lang-java">
remoteObject.setHandler( new AbstractOperationHandler() {
@Override
public void handleNotify( String event, Map&lt;String, Object&gt; properties ) {
// react on the event, notify listeners ...
}
} );
</pre>
<p>
The new API lives in the package <em>org.eclipse.rap.rwt.remote</em>.
It's still considered provisional, but already used by a couple of widgets and services in RAP
itself.
It's expected to evolve over the next release, but we don't expect big changes.
</p>
<h2>New JavaScript API for Custom Widgets</h2>
<p>
For the first time ever, RAP provides public JavaScript API.
There's now an object named <em>rap</em> in the global namespace of the JavaScript client.
All methods contained in this object are documented in the
<a href="http://download.eclipse.org/rt/rap/doc/2.0/guide/reference/jsdoc/index.html">RAP API reference</a>
together with their return types.
The most important methods are <em>registerTypeHandler</em> and <em>getRemoteObject</em>.
</p>
<p>
This API can also be used in JavaScript code added by the JavaScriptLoader, the
JavaScriptExecutor, or the ClientScripting add-on.
</p>
<h3>Registering type handler</h3>
<p>
A type handler defines how protocol messages for a specific <em>type</em> should be handled.
At minimum it defines a <em>factory</em> function that is used to create an object of this type
when the server sends a <em>create</em> operation.
It can also define the name of a <em>destructor</em> function, and a list of supported
<em>properties</em>, <em>events</em> and <em>methods</em>.
A typical type handler might look like this:
</p>
<pre class="lang-js">
rap.registerTypeHandler( "example.CoffeeMachine", {
factory : function( properties ) {
return new CoffeeMachine( properties );
},
destructor : "dispose",
properties : [ "sugar", "power" ],
events : [ "Ready" ]
} );
</pre>
<p>
The created object is stored by the framework under its object id.
This object has to implement setter methods that match the properties defined in the handler,
which will then be called when the server sends a <em>set</em> operation for a given property.
</p>
<h3>Remote Object (client)</h3>
<p>
Just like the server, the client provides a <em>RemoteObject</em> that represents the
server-side counterpart of a client object. It has a very similar API, with <em>set</em>,
<em>call</em> and <em>notify</em> methods.
If, for example, the custom widget wishes to inform the server that the value of the property
<em>text</em> changed, it could look like this:
</p>
<pre class="lang-js">
var remoteObject = rap.getRemoteObject( this );
remoteObject.set( "text", this.getText() );
remoteObject.notify( "Modify" );
</pre>
<h2>Simplified EntryPoints</h2>
<p>
To reduce the code required to implement an <em>EntryPoint</em>, we provide an abstract base
class called <em>AbstractEntryPoint</em> with a skeletal implementation of the interface.
It creates a display and a main shell and starts the SWT event loop when in SWT mode–you
don't have to care for these things anymore.
</p>
<p>
We recommend to use this base class for all entrypoints rather than implementing the interface
itself.
The following code snippet shows a minimal but complete entry point:
</p>
<pre class="lang-java">
public class HelloEntryPoint extends AbstractEntryPoint {
@Override
protected void createContents( Composite parent ) {
parent.setLayout( new GridLayout() );
Button button = new Button( parent, SWT.PUSH );
button.setText( "Hello World!" );
}
}
</pre>
<p>
The main shell is full-screen by default, but this can be changed by overriding another method,
<em>createShell()</em>.
</p>
<p>
<img class="framed" title="Simplest EntryPoint" src="images/SimplestEntryPoint.png" />
</p>
<h2>RAP Tools</h2>
<h3>RWT Launcher</h3>
<p>
The RWT Launcher has got new options to configure the session timeout and the context path,
just like the RAP Launcher.
</p>
<p>
<img class="framed" title="RWT Launcher" src="images/RWTLauncher-ServerOptions.png" />
</p>
<h3>New Basic Template</h3>
<p>
For lightweight RAP applications, we recommend to implement an EntryPoint and an
ApplicationConfiguration instead of using the Workbench and its extension points.
To get you started quickly with a minimal application, we added a new very basic
<em>Hello World</em> template to the RAP Tools.
This template uses declarative services to register an ApplicationConfiguration.
It replaces two old Eclipse Workbench-based templates.
</p>
<p>
The popular <em>Mail</em> template remains as an example for an application that uses the
Workbench stack, IApplication, advisors, views and a perspective, etc.
</p>
<p>
<img class="framed" title="RWT Launcher" src="images/HelloWorld-Template.png" />
</p>
</div>