Roadmap for Restlet Framework 2.1

Introduction

The goal for version 2.1 of the Restlet Framework is to develop a small, incremental version in a short time-frame of about 6 months. The basic Java 5 requirement won't change and the following major features will be added:

Easier hypermedia

HATEOAS

As Roy T. Fielding explained in this blog post, REST APIs must be hypermedia-driven, especially on the client-side if you really want to loosely couple web clients with web servers. We will help Restlet users to respect and leverage this core REST principle. See this specifications page for more details.

Multipart forms

The support for composite representations such as multi-part forms, on both the client and the server side is a recurrent need expressed by users, we should address it directly in the API, with support by the internal connector.

Currently, users rely on the FileUpload extension on the server-side and on alternative HTTP clients such as Apache HTTP Client 3.1 on the client-side. It would be much better to have a built-in consistent solution.

There will also be a focus on facilitating the validation of form submissions based on this specifications document.

Eclipse integration

Eclipse is more than an IDE and now provides a comprehensive runtime platform via the Eclipse RT project. In addition, OSGi and model-driven technologies developed by the Eclipse foundation nicely fit with the Restlet Framework. In version 2.1, we will help developers to bridge the Restlet and the Eclipse worlds.

Model-driven REST

Based on our experience with customers, we believe that the combination of Restlet and the pragmatic model-driven technologies developed by the Eclipse Modeling project adds a lot of value. In version 2.1, we will add those new related extensions:

• EMF extension : to convert EMF representation beans into XML, XMI or HTML representations
• ATL extension : to convert EMF representation beans into other EMF representation beans, like XSLT for XML representations
• Acceleo extension : to convert EMF representations into textual representations, similar to FreeMarker and Velocity template representations

Those extensions will be directly usable or via the enhanced converter service described below. The new demo built for 2.1 (see below) should have a version based on EMF developed.

Integration with Equinox/OSGi

We will continue to mentor/support the ongoing Google Summer of Code project for integrating Restlet with Eclipse Equinox (OSGi runtime), and hope to have this project accepted for incubation by the Eclipse Equinox community.

Eclipse update site

In addition to our Maven repository, Zip archives and Windows installers, we want to add a possibility to install and update Restlet modules and dependent libraries via the Eclipse IDE directly. For this we will provide an update site. Restlet modules are already OSGi bundles so this should be straightforward. See the related issue #191.

Eclipse IDE tooling

In order to facilitate the usage of the Restlet Framework withing Eclipse IDE, we would like to start providing tooling support such as wizards to facilitate the creation of Restlet applications, filters, resources, etc. See this wiki page for details.

Enhanced converter service

The current converter service supports the serialization of objects into representations or the deserialization of representations into objects. This works fine and uses a plugin mechanism for extensions such as XStream, Jackson, JAXB, JiBX and a few more. We want to go beyond in 2.1 and support three other scenarios.

From representation to representation

This is based on a transformation document (typically a template or skeleton of the result document). An example case is the usage of XSLT to automatically convert a WADL representation or a XStream/JAXB/JiBX XML representation into HTML representations. A mechanism to register or discover the transformation documents should be provided, based on the source and result media types.

From object to representation using a template document

An example is an object returned by a @Get annotated Java method) that needs to be converted into a result representation (for example an HTML document). There are currently two ways provided by the framework to do that via the FreeMarker and Velocity extensions. This idea would be to simplify the usage of those extensions and their TemplateRepresentation classes via the ConverterService.

It would also be useful to be able to select a different template based on a query parameter or any attribute actually, for example to display a read-only HTML document or an HTML form capable of editing the resource.

This would be pluggable so other template mechanisms such as Acceleo (generates text from EMF beans) could be supported. A mechanism to register or discover the transformation documents should be provided (for example based on the qualified class name of the source object in a base directory of templates).

From object to object using a transformation document

Third, the conversion of a source object into a result object should be supported. This could be leveraged by technologies such ATL (transforms source EMF beans into result EMF beans). A mechanism to register or discover the transformation documents should be provided, based on the source and result qualified class names.

Data binding in presentation layer

Even though we already support data binding via conversions between representations and objects, we should look into new applications of this feature, especially at integration with presentation technologies such as GWT, GXT or RCP.

Conneg service

Content negotiation has always been a strong feature of the Restlet Framework. In version 2.0, its implementation and negotiation algorithm is fixed in the Restlet Engine. In this new version, we want to make it customizable via a new ConnegService.

We also want to facilitate conneg based on other dimensions than representation metadata. For example the "account.html.ftl.ie" file could be mapped to the HTML media type, decoded using the FreeMarker template engine and returned only for Internet Explorer. The "vary" HTTP header (Response#dimensions property) should also be updated properly. Example of new dimensions that could be taken into account:

• user agent type (ex: Firefox)
• user agent version
• user preferences
• IP address and domain name (ex: UI branding, white-label)
• authentication state (ex: anonymous version)
• authorization state (ex: user role)
• usage mode (ex: Retrieve | Update | Delete | Create | Move | etc. or combinations of the previous modes)

Restlet editions

Pure JavaScript edition

Due to the emergence of HTML 5 on all sorts of browser platforms (mobile), the improvement of JavaScript engines such as Chrome V8 and the overall convergence with REST and Restlet/Java on the server-side, it seems like a good time to push for a more RESTful JavaScript client API, reusing the Restlet API semantics in pure JavaScript. Eclipse 3.6 also improved its support for JavaScript developments

Of course, we already have the GWT edition of Restlet which provides a nice solution, but there seems to be room for a more hypermedia driven/document oriented solution, combining AJAX and UI libraries such as jQuery, Ext JS, YUI to name a few.

The goal for version 2.1 is to develop an initial client-side version based on this specifications document.

Size optimizations

Restlet editions for Android and GWT required special adaptations in version 2.0 to run in those restricted environements. In version 2.1, we want to go further into the customization effort, with a special focus on footprint.

Regarding Android, the core org.restlet.jar for Android contains the internal Restlet HTTP connector (client and server), but in many cases, we could just leverage the client connector based on Apache HTTP Client, especially because it is part of the Android runtime. We should therefore provide an addition org.restlet.jar file, without the internal connector but preconfigured to leverage Apache HTTP Client, resulting in a smaller footprint.

Regarding GWT, we added support for annotated interfaces and client proxies in version 2.0 with automatic serialization and deserialization, generated using GWT's deferred binding mechanism. When using those proxies, we rely on the whole Restlet Core (GWT edition) for the actual implementation, but this is mostly transparent unless the user needs to modify the underlying ClientResource for advanced use cases (authentication is a classic case). In order to not add the footprint of the Restlet Core in simple cases, we could (optionnally) generate a lighter proxy relying directly on GWT's lower-level HTTP API.

Scalable internal connector

Non blocking NIO

In version 2.0, we have added support for asynchronous processing of calls as a preview feature, including provisional responses (1xx status code in HTTP). This feature is currently only usable with the internal HTTP connector that is part of the Restlet engine (org.restlet.jar file). It relies of message queues to support asynchronous handling but its IO processing is still done in a blocking manner and requires two threads per connection which limits its scalability, even if persistent connections and pipelining and now supported.

A few month ago, we have started work on a new NIO version of this internal connector that leverages the non-blocking features of NIO to support a large number of concurrent connections and messages with only a single IO thread! The first results in the Restlet incubator are promising and we want to complete this connector in version 2.1 to replace the current internal connector with a lighter and more scalable one.

SIP connector

SIP is a core protocol for Voice of IP (VoIP) to control multimedia session. It has been designed based on the HTTP protocol, using the same syntax for request and messages and with a similar processing flow, leveraging a lot provisional responses. We explored over the past months the possibility to provide a SIP connector based on the same internal connector that we use for HTTP and already we have a prototype working in the Restlet Incubator.

For version 2.1, we want to complete this initial work and make sure its works and scales properly on top of the new NIO based connector mentioned above. This will ship as an org.restlet.ext.sip extension. We also plan to explore a higher-level SIP application API that would provide a  REST-minded alternative to the SIP Servlets.

Better documentation

Restlet in Action book

We will finish writing the Restlet in Action book for Manning (already available in early access) and make sure that the printed version is available at the same time as the 2.1.0 release.

Complete example

So far our documentation has been rather technical, with first steps documents, tutorials, user guide and even the book. We now need a more user oriented level of documentation that would help understand the potential of the technology with a sensible use case, a complete end-to-end example including persistence and UI. This would also give a way to share best practices and illustrate usage scenarios of the technology such as:

• open web API
• cloud migration and portability
• mobile web sites and services
• unification of web sites and web services

One idea suggested is to provide an example comparable to Seam Hotel Booking one.

Miscellaneous

Beyond the above mentionned features, here are some additional ones that we are considering:

• Removal of deprecated artifacts in the API, engine and extensions to reduce size
• Consider a Composite class, parent of Component and Application
• Server-side resource proxies based on Restlet annotated interfaces that would allow a POJO to become a stateful REST resource. Those objects would be thread-safe all potentially called by several threads at the same time.

Conclusion

After version 2.1, we will likely continue with another incremental 2.2 version. For a more detailed and up-to-date roadmap, you can always check this page and browse the listed issues that will be updated to reflect the plan above.

If you see a feature you would like to help us with, please jump in and contribute to make it happen sooner. If you don't have enough time to share, your company can also help us by funding the development of some features. See our co-development offer at Noelios Technologies. Finally, nothing is written in stone, so please express yourself, we are looking forward to your feed-back!