RAP 1.5 includes a new API to define and start RAP applications programmatically (up to RAP 1.4, this was only possible using Eclipse extensions or web.xml properties). With this new API, RAP can also be used for leightweight applications based on OSGi, but without the entire Eclipse stack, even with other OSGi containers like Apache Felix. Also traditional web applications, that use RWT as a library without OSGi, benefit from the new API.

This API contains a couple of interfaces that we had trouble to find suitable names for. If you’ve used this API already you know that there were two interfaces side-by-side in the same package with almost the same name: ApplicationConfigurator and ApplicationConfiguration. Even though these names seemed to be correct, it turned out that they were hard to tell apart, and if mixed up in a service declaration, the application did not start, without any warning.

So we reviewed the case and eventually came up with better names for the interfaces without changing the structure. Let me explain the new API and our reasoning behind it.

Implementing an ApplicationConfiguration

A RAP application consists of various parts, such as entrypoints, URL mappings, themes, service handlers, etc. All these parts constitute an ApplicationConfiguration. The configuration is like the blueprint for an application. Based on an ApplicationConfiguration, the framework can create and start an application instance. There can be more than one application instances at runtime, e.g. running on different network ports or different servlet contexts.

Hence, when you write a RAP application, you have to provide an ApplicationConfiguration.

An ApplicationConfiguration is used to configure an application before it is started. For this step, RAP follows a callback approach to leave the responsibility for creating and starting the application with the framework. Therefore, the configuration must actively configure the application. To do so, it has one method configure( Application ). The framework provides a reference to the created Application as a parameter to this method. Here’s how a simple implementation looks like:

public class SimpleConfiguration implements ApplicationConfiguration {
 
  public void configure( Application application ) {
    application.addEntryPoint( "/simple", SimpleEntryPoint.class, null );
    application.addEntryPoint( "/other", AnotherEntryPoint.class, null );
  }
}

Registering the ApplicationConfiguration

When using OSGi, the ApplicationConfiguration can be registered as a service. I’d recommend using OSGi declarative services (DS) like this:

<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0">
   <implementation class="com.example.SimpleConfiguration"/>
   <service>
      <provide interface="org.eclipse.rwt.application.ApplicationConfiguration"/>
   </service>
</scr:component>

The bundle org.eclipse.rap.rwt.osgi will automatically start this application on every available HttpService. When using Equinox, don’t forget to also include the org.eclipse.equinox.ds bundle. You can find an example of a simple RAP application using DS on github.

When using RWT as a library in a traditional web application, i.e. without OSGi, you can register your ApplicationConfiguration in the web.xml by adding a context-param with the fully qualified class name of the implementation:

<context-param>
  <param-name>org.eclipse.rap.applicationConfiguration</param-name>
  <param-value>com.example.ExampleConfiguration</param-value>
</context-param>

You can always look up the param-name in the constant ApplicationConfiguration#CONFIGURATION_PARAM. The RAP FAQ has a complete example.

Starting an Application

When an ApplicationConfiguration has been registered as described above, the application is automatically started by the framework. Alternatively, it can also be started explicitly using an ApplicationRunner:

ApplicationConfiguration configuration = new SimpleConfiguration();
ApplicationRunner runner = new ApplicationRunner( configuration, servletContext );
runner.start();

There’s a saying that there were only two hard things in computer science, cache invalidation and naming things. I don’t happen to know what’s so tricky about cache invalidation But I can hardly remember any technical problem that caused me as much of a headache as these few names did. I hope that after so many discussions, this new API will prove to be simple to understand and to use.

Thanks to Frank, Rüdiger, Holger and Jordi for great discussions and especially to Frank for contributing this new API to RAP!

The changes are part of RAP 1.5M7, published this Friday, May 11.

Tags: api, juno, new & noteworthy, OSGi, rap

Whenever we talk about server-side apps and RAP mobile, one topic always comes up: how to access native functionality like Geolocation or the Camera. With this post I want to show you how we access this functionality on the server-side. At writing, we’ve implemented Geolocation Support, and more additions are planned for the near future.

I have to point out one thing first.  When you take look at RAP mobile from a very abstract view, it is nothing more than an object synchronization mechanism. That is, if a button (or any other widget) is created on the server it also needs to be created on the client. This is exactly the same for native functionality. When the server needs the location of the client it has to tell the client that it needs the location. Then, the client has to tell the server the location and this cycle starts over again. The challenge in this approach is to hook the location to the right session. Fortunately, RAP’s server side has solved these issues a long time ago, and it’s pretty easy to hook this information together.

One issue that remains is that SWT has no API for native access because it was made for the desktop. So, a new API is required that needs be an abstraction for all devices. But wait a minute – this sounds like a well known problem that has been solved already. I’m referring to Phonegap/Cordova. This technology created a JavaScript abstraction for accessing native functionality within HTML5 Apps. And, IMHO, these guys did a really great job and there is no need to reinvent the wheel. We decided to take the Phonegap API as a template and created a very similar Java API. Our first result is the Geolocation API which is located in the RAP mobile server code. As mentioned in previous posts, everything on the server side is open source, including this API. The RAP mobile server code is located in the com.eclipsesource.rap.mobile*.jar and is included in the demos target. You can also take a look the Geolocation API here at github.

We have created a demo for the Location API, which you can see in the videos linked below. The source code for this demo is also located on github. To conclude, I can proudly say that with RAP mobile it’s now possible to access the Geolocation API of iOS and Android from Java by writing the code only once!

Tags: android, geolocation, iOS, rap, rap mobile, server-side apps

Once again we are releasing a new version of RAP mobile. This latest release 0.5.7 brings with it a very cool new feature that we call the “Client Canvas”. This extension of the classic SWT Canvas allows you to draw freehand on your screen with your stylus or even your finger.

Additional Features and API

Client Canvas

The client canvas provides you with basic freehand drawing options, allowing you to sketch with your stylus or your finger.  Like a regular drawing program, you can choose your color, brush size and opacity. And, you can step through the history of your drawings to undo/redo certain steps. To implement this feature we built upon the SWT Canvas object that allows us to change the pen properties via the established Canvas API. To get started with drawing you’ll just need to instantiate the com.eclipsesource.rap.mobile.widgets.ClientCanvas instead of the regular SWT Canvas. To demonstrate the Client Canvas we have created a sample where you try out a little draw-by-numbers.

Android

Browser

The RAP mobile Android client is catching up with iOS on browser support. We now support the SWT Browser widget, allowing you to show full websites or custom HTML snippets inside your RAP mobile application. We also support the Browser.evaluate() and Browser.execute() methods to execute javascript in the browser on the Android device and to make it possible to send execution results back to server. The screenshot to the right shows examples that display a full website, an HTML snippet and the execution of a custom javascript function.

Support for various SWT Shell style flags

SWT offers many ways to customize the appearance of a shell via the style flags passed to the Shell constructor. These flags are also important to create SWT Dialogs. We now support the additional SWT shell styles TITLE, BORDER and *_MODAL. The following screenshots demonstrate the various style combinations.

Bugfixes

We are constantly working towards a high level of stability and solid performance, and in this release, we squashed some bugs which deserve special mention:

• Fixed an issue where selecting elements inside a vertical ScrolledComposite was not possible
• The GraphicalContext used android APIs not available on the supported basline version android 2.1 (API level 7).

iOS

You’re probably already enjoying the browser support on our RAP mobile iOS client, and can now also take the Client Canvas for a test drive.  Two other things that you might notice in this release are a new UI hint to show how to enter the developer SystemMenu and improvements to modalShell rendering and animation.

Tags: android, browser, canvas, dialog, iOS, mobile, rap, rap mobile, shell

In my last post I gave you an overview of server-side apps and how they relate to RAP mobile. In this post I want to dive into some technical details. I’ll assume that you are a Java programmer and that you are familiar with servlets and tomcat. Not necessary but really helpful is some knowledge of OSGi.

So, let’s get started. To create RAP mobile Applications you’ll write Java Code only. This of course means you will have some dependencies. The basic dependencies that result from using RAP mobile are two open source jar files. One is the widget toolkit which includes the SWT API for writing UIs and some other server stuff. The widget toolkit is part of the Eclipse RAP project and is called RWT (RAP Widget Toolkit) and it’s jar file is named org.eclipse.rap.rwt_VERSION.QUALIFIER.jar. The second jar file is the RAP mobile jar itself. It’s called com.eclipsesource.rap.mobile_VERSION.QUALIFIER.jar and contains additional API and other mobile-related stuff. Of course these two jars have dependencies too. These are javax.servlet, org.json and a few others. They are included in the RAP mobile target (see the target definition file in the examples) and can also be consumed manually or via Maven.

Once you have set up your Java Project and dependencies (you can use this template) the first thing you’ll need to write is an ApplicationConfiguration. It can look like this:

public class Configuration implements ApplicationConfiguration {
 
  public void configure( Application application ) {
    Bootstrapper.bootstrap();
    application.addEntryPoint( "/my-app", MyEntryPoint.class, null );
  }
}

You may notice that the really interesting stuff happens in the configure method. This method will be called by the framework and is used to configure your environment. You’ll use the configure method most often to add IEntryPoints. An IEntryPoint marks the entry point of your UI code and can look like the following MyEntryPoint.  (If you want to go into more depth on the UI Code,  take a look at the SWT resources and the examples.)

public class MyEntryPoint implements IEntryPoint {
 
  public int createUI() {
    Display display = new Display();
    Shell shell = new Shell( display, SWT.NO_TRIM );
    shell.setLayout( new GridLayout( 1, false ) );
 
    Button button = new Button( shell, SWT.PUSH );
    button.setLayoutData( new GridData( SWT.BEGINNING, SWT.CENTER, false, false ) );
    button.setText( "Hello World" );
 
    shell.open();
    return 0;
  }
}

In the configure method of the ApplicationConfiguration you need to connect the entry point to a path, e.g. “/my-app”. This will make your application available using this URL http://SERVER:PORT/my-app. Next, you need to hook your ApplicationConfiguration Implementation to the framework.

At this point you need to make a choice between two RAP mobile operating modes. The easiest mode to use is RAP mobile together with plain servlet technology. For this variant you’ll write a web.xml to hook the framework to your application, similar to the example below:

<!--?xml version="1.0" encoding="UTF-8"?-->
 
org.eclipse.rwt.Configurator
my.Configurator
 
org.eclipse.rwt.engine.RWTServletContextListener
 
    rwtServlet
    org.eclipse.rwt.engine.RWTServlet
 
    rwtServlet
    /*

The more advanced operating mode is to use it together with OSGi, which I prefer because I like modularity much. But this requires that you have basic knowledge about OSGi and the service model. Hooking the ApplicationConfiguration in this scenario is pretty straight forward. All you have to do is register your implementation as an OSGi service and starting one more bundle called org.eclipse.rap.rwt.osgi. In an activator it can look like this:

public class Activator implements BundleActivator {
 
  private ServiceRegistration registration;
 
	public void start(BundleContext bundleContext) throws Exception {
	  Configuration configuration = new Configuration();
	  registration = bundleContext.registerService( ApplicationConfiguration.class.getName(),
	                                                configuration,
	                                                null );
	}
 
	public void stop(BundleContext bundleContext) throws Exception {
		registration.unregister();
	}
 
}

Now you can simply launch your OSGi framework – but, don’t forget the HttpService (it is in the org.eclipse.osgi.services bundle).  And now, the fun part. Point your mobile client to the url of your server and enjoy the mobile UI which should look like the advanced one below!

If you haven’t tested the clients already, don’t hesitate to request them here. We have also created some examples which can be found at github.  In upcoming posts, we’ll provide a more detailed tutorial for both operating modes.

Tags: android, iOS, rap, rap mobile, server-side apps

You may have read the title of this post and are asking yourself, “what the heck is a server-side app?”. Let me try to explain. When an app works with sensitive data there is always a security risk in storing the data on the device. If the device is lost or stolen the sensitive data is lost or worse, no longer confidential.  A server-side app can prevent this. Data is stored on the server and the client displays and manipulates it, but no data is stored locally. I think you’ve got it: server-side apps are nothing more than a thin client approach adopted to the mobile/app sector.

When you’re confronted with this problem, you’ve probably either started by designing the server application or are porting an existing server application to be accessible by mobile devices. So, your next step will be to plan how to visualize the server-side app on the clients. The most common approach is to build an App for iOS, Android and so on and render the data in a more or less generic UI. You’ll invest a lot of effort in creating and securing the communication between server and client to get your server-side app ready. And, you’ll have joined the club of developers, including me, who have reinvented the wheel once more.

This is the problem we are solving with RAP mobile. RAP mobile consists of a server and generic clients, with the server based on standard servlet technology and a kick-ass OSGi integration. The server’s open source and hosted within the Eclipse RAP project. The generic clients currently exist for iOS and Android, and in both cases, all the clients do is talk to the server and display a UI. But, every other server-side app does this too. What’s special here?

With usual server-side apps you have to couple the client to the server. The data and message contents are defined and the client needs to understand them, resulting in a more or less a tight coupling between these two all created by yourself. With RAP mobile, the work on communication is done by the framework for you. The server produces JSON based messages that the RAP mobile clients can understand. The messages contain information like “Create a Window, create a Button, set the text of the button to …”, (I think you get it). When you sketch this out it looks like this:

This approach allows us and you (because the server’s open source) to come up with any client as long as it understands JSON. I think the major benefit RAP mobile brings is that you can concentrate on the server-side and your domain requirements, instead of programming a generic UI for every platform.

When you’ve read this far you might now be asking yourself, “When everything is on the server side and I don’t have to write a native UI for the mobile devices, eg. in Objective-C, how does the native UI get created?”  And now the Eclipse open source project comes into the game with Eclipse RAP. RAP provides a widget toolkit which is based on SWT, which means that you write your UI completely in Java. When RAP was created the goal was to enable a developer to create a desktop and a web application with the same code base. As a result, the RAP developers solved problems like multi-user awareness, clustering support, styling and many many more. In the meantime, we’ve gone even further and extended this idea to the mobile space. (And, we’re making good progress, because on the server side we’re working with a mature technology.) In short, it means that when you write a RAP mobile app for iOS, Android and so on, you don’t have to worry about the native client, but you can write your UI in plain Java and run it in the server.

If you’re hungry for more , visit the RAP mobile website, watch the demo videos, clone the examples and run your own app. To join the developer preview, you’ll need to complete a short form but, in a few months we will move into an open beta. I hope you will have fun with this as much as I do. Any feedback is welcome.

Tags: android, iOS, rap, rap mobile, server-side apps

RAP mobile is progressing. In this post we’d like to give you a quick update on the latest features in the RAP mobile clients for iOS and Android.

Android

Graphical Context

For drawing arbitrary graphical elements in a widget, RAP mobile now supports the Canvas and GC (graphical context) API. This enables a variety of options for designing individual UI elements. The graphical context also lays the foundation for the development of custom widgets.

iOS and Android

Non-UI Objects

As we all know, mobile devices are equipped with local sensors and other hardware-based capabilities. With the current release, RAP mobile is ready to handle client side non-UI objects to model the local capabilities of your phone or tablet. In our first example, we developed a geolocation object to support the GPS receivers in mobile devices. In an upcoming blog post, we’ll explain the additions to the API in more detail.

Demos

The latest demos on the RAP mobile website give you a quick look at our latest development efforts. The demos contain videos of both the iOS and the Android platform as well as some code snippets. Follow the links to GIT hub if you want to take a look behind the scenes.

New demo “Dashboard”

We have created a new interactive demo called “Dashboard”. Derived from an open information project from a German publisher, the demo graphically displays information about delays in national rail traffic.

New demo “Geolocation”

The “Geolocation” demo uses RAP mobile’s new object handling feature to interact with your mobile device’s hardware and determines your current location.

Tags: android, iOS, rap, rap mobile

In this post we’d like to give you a quick overview of the latest in RAP mobile, version 0.5.5.

Android

Support for UI Callback

The UI callback mechanism enables a RAP client to automatically update the UI without user interaction. With this feature we can support progress indicators or updates to displays that are triggered by events on the server side. Watch for examples in the upcoming releases.

Label Alignment

Labels and buttons now follow the SWT alignment styles SWT.LEFT, SWT.LEFT, SWT.CENTER.

Bug fixes

• Rotating a device now correctly re-positions a scrolled composite.
• The vertical alignment of text in a label is now updated correctly when a relayout is triggered.

iOS

Automatic Discovery of Entry Points

To make it easier to access the different entry points of a RAP mobile application running on the server, the iOS client now supports automatic EntryPoint discovery. To list all available EntryPoints, navigate the native client to the server url followed by a “/index.json”. The following URL on the RAP demo server provides you with an example: http://rap.eclipsesource.com/demos-0.5.5/index.json

Property to control idle display

You can now choose to have the display automatically switch off in idle mode or remain on.

Bug fixes

• Animated widgets are now more stable (they sometimes “jumped” when the animation was playing).
• We’ve made significant improvements to memory management.
• TabFolders now support the style argument SWT.TOP.
• We’ve improved reliability when reloading a session.
• Centering TITLEs in a ToolBar is now easier – the SWT.SEPARATOR is no longer required.

Tags: android, iOS, rap, rap mobile

The RAP team started working on a new feature called ClientScripting. It’s still in it’s infancy and will not (yet) be part of the core framework , but its already very useable. The goal is to allow adding pieces of behavior to the client-components of RAP widgets. This makes it possible to have swift, dynamic user feedback in situations that require a certain amout of logic – so far a problematic scenario for RAP applications. It can be considered an alternative to custom widget development in many cases, and might also save some network traffic. We currently focus on the scenario of validating text input while typing, and will expand from there. Interactions between widgets are not yet possible, but is planned.

As you can test for yourself, the difference between server-side and client-side validation is quite noticeable.

When using ClientScripting, you will need to know very little JavaScript, and all API is as close to SWT as possible. The project has a wiki page with all further information you might need (including where to get the code). Note that you need RAP 1.5M6 or newer to use it. If you try it out, please consider giving some feedback, report bugs or file enhancement requests.

Tags: ajax, ClientScripting, demo, javascript, juno, news, rap

The RAP 1.5 M6 milestone build is packed with new features, especially for Trees and Tables. But most notably, you can now use HTML markup in Tables, Trees, and also in Labels:

Just enable the markup support for a certain widget (see below), then you can make its text bold, italic, yellow or … no, not blinking! Actually, RAP will validate the markup and allows only a selection of tags (no <script> tags, please!). But since the <img> tag is in that list, you can add a smiley instead .

Table table = new Table( parent, SWT.BORDER );
table.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
TableItem item = new TableItem( table, SWT.NONE );
item.setText( "Some <em>text</em> with <strong>markup<strong>" );

This also means that you don’t have to break your neck anymore just to add an HTML link to your RAP UI. You can now place real links in any Label or CLabel:

Label label = new Label( parent, SWT.NONE );
label.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
label.setText( "<a href=\"http://eclipse.org/rap\" target=\"_blank\">RAP project page<a>" );

Don’t like the setData() programming? We don’t like it either. But for now, it’s the simplest way to expose additional functionality without changing the SWT API. For RAP 2.0, we plan to come up with some better API for our extensions.

Try out the markup support in our updated online demo! BTW, did you notice that this is a deep link into the demo application? Yes, there was a bug preventing them from working in RAP for long, and it’s now finally fixed! You can now use the BrowserHistory to navigate to a certain point in your application right on startup. Here’s the link to an example page that shows markup in a Table.

And there are more Table and Tree enhancements, such as the fixed columns support that lets you exclude one or more colums from horizontal scrolling. Check out the full list of changes in the New & Noteworthy.

Get it while it’s hot, this milestone is a must have

Tags: juno, milestone, new and noteworthy, rap

If you ever need a WYSIWYG editor in your RAP application, look no further.

I originally implemented this as an example of how JavaScript applications can be embedded in RAP as custom widgets. So if you have a similar scenario, you could also use this project as a template. The editor is fairly customizable, read the README for details. You can get the code on GitHub.

Tags: ajax, CKEditor, Custom Widget, javascript, rap, Rich Text Editor