blob: dbe6b6048a74db98d4d741bda1bc6b6ab22673b7 [file] [log] [blame]
<div>
<h2>New Web Client Services</h2>
<p>
Based on the new Client API that has been introduced in M2, some existing API has been
transformed into client services.
</p>
<h3>JavaScriptExecutor service</h3>
<p>
This service can be used to execute a piece of JavaScript code on the client.
It replaces the internal class <em>JSExecutor</em>. Example:
</p>
<pre class="lang-java">
JavaScriptExecutor executor = RWT.getClient().getService( JavaScriptExecutor.class );
executor.execute( "alert( \"Hello World!\" );" );
</pre>
<h3>BrowserHistory service</h3>
<p>
Allows to use the browser's history for navigating within the application.
This replaces the <em>IBrowserHistory</em> interface and <em>RWT.getBrowserHistory()</em>.
Example:
</p>
<pre class="lang-java">
BrowserHistory history = RWT.getClient().getService( BrowserHistory.class );
history.createEntry( "main", "Main View" );
</pre>
<h3>ExitConfirmation service</h3>
<p>
Used to configure the confirmation dialog that can be shown before the user leaves the
application.
It is no longer possible to do this in a branding. Example:
</p>
<pre class="lang-java">
ExitConfirmation confirmation = RWT.getClient().getService( ExitConfirmation.class );
confirmation.setMessage( "Where do you think you're going?!" );
</pre>
<h2>New Event System</h2>
<p>
The event system in RWT has been completely re-written.
For historical reasons, the implementation was based on typed events like SelectionEvent with untyped
events built on top.
This “inverted” design caused several problems that are now fixed (see <?=bug(334028)?>).
</p>
<p>
With the new implementation, the design follows the structure of SWT.
Typed and untyped events work exactly like in the original.
This also allowed us to provide some missing API:
All typed events have a <code>time</code> field that reflects the time an event has occurred.
MouseEvent has a field <code>count</code> that allows to distinguish single and double clicks.
Custom widgets can now use the protected method
<code>Widget #removeListener( int, SWTEventListener )</code>.
</p>
<h2>Server Push (aka UICallBack) Improvements</h2>
<p>
The <em>UICallBack</em> is RAP's mechanism to enable “push” UI updates to the client.
The implementation of this mechanism has been simplified and made more robust
(see <?=bug(382613)?>).
As an effect of this change, the client will now be notified of a session timeout when
the UICallBack is enabled (<?=bug(388280)?>).
</p>
<h2>Resource Manager Rework</h2>
<p>
The resource manager (<em>IResourceManager</em>) is used to register static resources like
images or JavaScript files in RAP applications.
But it had also been equipped with additional functionality like JavaScript compression,
encoding conversion, etc.
These additional concerns made the resource manager complicated to use and to maintain.
We reduced the interface to the purpose of registering resources and simplified the
implementation.
In particular, the resource manager
</p>
<ul>
<li>
does not minify JavaScript anymore.
We removed the YUI Compressor from RWT because it turned out to be too resource-intensive.
All JavaScript resources used by RWT are minified at build time and we'd recommend that custom
component developers also minify their JavaScript files with a tool of their choice.
There are many free tools out there, such as
<a href="http://developer.yahoo.com/yui/compressor/">YUI Compressor</a>,
<a href="https://developers.google.com/closure/compiler/">Google Closure Compiler</a>,
or <a href="http://www.crockford.com/javascript/jsmin.html">JSMin</a>.
</li>
<li>
does not take the encoding of a resource into account anymore.
It now registers the bytes from a given input stream as is.
If you used to register text files with a charset other than UTF-8, you should make sure that
your client code reads the resources with the correct charset.
</li>
<li>
does not add version hashes to file names anymore.
This has been done to avoid caching problems.
We think that these issues are not that common anymore than they were in IE6 times.
If there is a need to add version hashes to URLs, applications can simply add a URL parameter
like "?nocache=4711" when requesting the resource.
</li>
</ul>
<p>
Moreover, the resource manager does not close input streams anymore after registering a resource,
as it did in 1.5 (<?=bug(347615)?>).
Please double check that you're closing your input streams correctly.
</p>
<h3>Affected API</h3>
<p>
The ResourceManager API has been reduced to the necessary minimum.
If you've used a method that has been removed, the advice above should help you to adapt your
code to use one of the remaining methods instead.
<p>
</p>
The <em>IResource</em> interface is now only used in the extension point
<em>org.eclipse.rap.ui.resources</em> and has therefore been moved to the bundle
<em>org.eclipse.rap.ui.workbench</em>.
The methods <em>getCharset()</em> and <em>getOptions()</em> have been removed because of the
changes described above.
</p>
<p>
For resources that are registered in an <em>ApplicationConfiguration</em>, the method
<em>Application.addResource(…)</em> now accepts a <em>ResourceLoader</em> instead of
<em>IResource</em>.
</p>
<h2>Dropped Support for entrypoints by name</h2>
<p>
Until now, entrypoints could be registered with a name in an entrypoint extension.
Those entrypoints had been available at a URL with the default servlet name “rap” and a URL
parameter “startup” pointing to this name, such as:
<p>
<pre>
http://hostname/webapp/rap?startup=foo &nbsp; (OBSOLETE)
</pre>
</p>
Since RAP 1.5, entrypoints can be registered by path.
For example, an entrypoint that is registered with the path <code>/foo</code> will be available
at:
</p>
<pre>
http://hostname/webapp/foo
</pre>
<p>
The old approach had a number of drawbacks. It lead to odd URLs, that follow a convention
you had to know. A typo in the entrypoint name resulted in an HTTP 500 instead of a 404.
Even if you mapped a custom path to the entrypoint in a branding, the “rap?startup=” URL
would still work.
</p>
<p>
Thus we decided to remove the support for entrypoints by name completely in RAP 2.0.
From now on, entrypoints can only be registered by path.
The default servlet name “rap” and the parameter “startup” are not supported anymore.
</p>
<h3>IEntryPoint</h3>
<p>
In your entrypoint extensions, use the attibute <em>path</em> to specify the URL path for the
entrypoint. The old attribute <em>parameter</em> is not supported anymore.
Here's an example <em>plugin.xml</em> snippet:
</p>
<pre class="lang-xml">
&lt;extension point="org.eclipse.rap.ui.entrypoint"&gt;
&lt;entrypoint id="example.entrypoint"
class="example.MyEntryPoint"
<strong>path="/example"</strong> /&gt;
&lt;/entrypoint&gt;
&lt;/extension&gt;
</pre>
<h3>IApplication</h3>
<p>
This change also affects applications that use <em>IApplication</em> as entrypoint.
To make an application available at a certain path, add a parameter named <em>path</em>
to your extension:
</p>
<pre class="lang-xml">
&lt;extension id="example.app" point="org.eclipse.core.runtime.applications"&gt;
&lt;application thread="main" cardinality="singleton-global" visible="true"&gt;
&lt;run class="example.Application"&gt;
<strong>&lt;parameter name="path" value="/example" /&gt;</strong>
&lt;/run&gt;
&lt;/application&gt;
&lt;/extension&gt;
</pre>
<h2>Branding</h2>
<h3>Entrypoint mapping</h3>
<p>
Since entrypoints are now always registered by path, there is no need for an entrypoint-to-path
mapping in a branding anymore.
Therefore, we removed the attributes <em>servletName</em>, <em>defaultEntrypointId</em>, and the
element <em>associatedEntrypoints</em> from the <em>branding</em> extension point.
A branding can now be bound to an entrypoint by setting the new attribute <em>brandingId</em>.
</p>
<pre class="lang-xml">
&lt;extension point="org.eclipse.rap.ui.entrypoint"&gt;
&lt;entrypoint id="example.entrypoint"
class="example.MyEntryPoint"
path="/example"
<strong>brandingId="example.branding"</strong> /&gt;
&lt;/entrypoint&gt;
&lt;/extension&gt;
</pre>
<p>
To bind a branding to an <em>IApplication</em>, add a parameter <em>brandingId</em> to the
application extension point.
</p>
<pre class="lang-xml">
&lt;extension id="example.app" point="org.eclipse.core.runtime.applications"&gt;
&lt;application thread="main" cardinality="singleton-global" visible="true"&gt;
&lt;run class="example.Application"&gt;
&lt;parameter name="path" value="/mail" /&gt;
<strong>&lt;parameter name="brandingId" value="example.branding /"&gt;</strong>
&lt;/run&gt;
&lt;/application&gt;
&lt;/extension&gt;
</pre>
<h3>Exit confirmation</h3>
<p>
For exit confirmations, the new client service <em>ExitConfirmation</em> should be used as
explained above.
The attribute <em>exitConfirmationClass</em> is no longer supported by the branding extension
point.
</p>
<h3>Branding API removed from RWT</h3>
<p>
With these changes, we also removed the branding API from RWT, namely the classes
<em>AbstractBranding</em> and <em>Header</em>.
We don't expect that anyone was using these classes.
In plain RWT applications, entrypoint properties can be used for branding.
</p>
</div>