Introduction

Restlet is becoming an ubiquitous Web development framework. This has led us to provide various adaptations (ports) of the main Restlet code. So far we have been handling this process manually, but time has come to industrialize this process.

Requirements

• Support all major Java-based deployment environments for Restlet applications
• Support modular distributions
• Automate the port of the main Restlet code to specific environments
• Ensure that Restlet application portability is maximal
• One base code managed by SVN
• One code per edition
• A set of distributions (zip, windows installer, maven, etc) per edition
• Solve this issue related to the module version defined in the manifest (http://restlet.tigris.org/issues/show_bug.cgi?id=755)
• Allow contributors to send "patches" (SVN patches?)

Analysis

• The current usage of the org.restlet.ext" prefix for extension modules restricts the core packages
• Depending on the target platform, the available core dependencies vary (ex: JAXP transformations aren't always available)
• We should make sure that the Restlet core API provides the stable set across all target environments (GAE/J, Android, Java SE, etc.)
• Express a set of transformation rules (modification, deletion, addition) from the base code to the code of an edition (several granularities: module, library, classe/file, method/attribute, body of a method, annotations of a method, java comments)
• Specific dependencies (distinct libraries per edition, distinct versions per edition)
• Customization of edition's distributions (e.g.: installation directory for the Windows installer)
• Make the build.xml script more maintainable (e.g. when adding a new extension)
• Decentralize the declaration of the modules.
• Editions form a hierachy sharing common rules (ex: OSGi and Equinox, Java SE and Java EE)

Supported editions

• Restlet for Android
• Restlet for Google App Engine
• Restlet for GWT
• Restlet for Java SE
• Restlet for Java EE

Planned editions

• Restlet for Equinox
• ...

Design

• Use consistent Java package names across all editions
• Restlet core packages, without the "ext" suffix should be based on the smallest set of APIs possible (smaller than Java SE?)
• Modules packaging (ex: Servlet extension) should be consistent across all editions to facilitate application porting
• Modules, Libraries describe themselves with a single XML file
• The build.xml is templated, in order to generate a single build.xml file per edition
• A boot script is provided that aims at generating for each edition: the build.xml file (according to the XML descriptors file), the source code
• Each build.xml file per edition is responsible to generate the edition's distributions (zip, exe, etc)

Overall file hierarchy, with XML files descriptors:

svn/trunk
  + build
  |   + project.xml
  + modules
  |   + org.restlet/module.xml
  |   + org.restlet.ext.freemarker/module.xml
  |   + ...
  + libraries
      + org.mortbay.jetty_6.1/library.xml

Overall build schema:

Implementation

• We should aim at maintaining a single code base for the Restlet modules
• Annotations could be used to indicate specificities of each Restlet edition e.g.: @Includes(Edition.GAE), @Excludes(Edition.GWT)
• Take care of specific dependencies per edition, wich could not apply to the same source code
• JDK's APT tool can process annotations but can modify the Java source code
• INRIA's Spoon tool is much more powerful and allows Java source code transformation/customization
• fmpp, freemarker for text generation (build.xml, properties files, etc)
• ant
• ivy, maven
• Note: in order to specialize by edition, use parameters such as "includes" and "excludes" instead of nodes which could lead to duplicate large blocks of data.

Description of the project.xml file

• list of supported editions?
• description of each edition?
• list of supported distributions (zip, installer for Windows, Maven, etc) per edition

<editions>
   <edition id="android|gae|gwt|jee|jse">
      <label>
         <full></full>
         <medium></medium>
         <short></short>
      </label>
      <description></description>
      <javadocs>
         <link href="http://java.sun.com/j2se/1.5.0/docs/api/" />
         [...]
      </javadocs>
      <distributions>
         <distribution id="classic" />
         <distribution id="maven" />
      </distributions>
   </edition>
</editions>

Description of the module.xml file

Necessary data:

• name (maven), bundle name (manifest) (nearly the same: "Restlet extension: Jetty"/"Restlet extension: Jetty 6")
• description
• version, bundle version (manifest)
• dependencies (per edition)
• exported packages (manifest) (per edition)
• imported package (manifest) (per edition)
• bundle activator (manifest, not supported in Android) (per edition)
• bundle required environment (manifest) (per edition?)
• others?

<module id="" type="core|standard|integration|connector" package="org.restlet[...]" includes="" excludes="">
   <label></label>
   <description></description>
   <distributions>
      <distribution id="classic" />
      <distribution id="maven" />
   </distributions>

   <dependencies>
      <dependency includes excludes="" type="library|module" id="" />
   </dependencies>
   <osgi>
      <export includes="" excludes=""></export>
      <import includes="" excludes=""></import>
      <activator  includes="" excludes="" />
   </osgi>
   <source edition="android|gae|gwt|jee|jse">
      <files-mappers>
<![CDATA[
]]>
      </files-mappers>
      <files-sets>
<![CDATA[
]]>
      </files-sets>
   </source>
   <stage edition="gwt" includesource="true">
      <files-filters>
<![CDATA[
]]>
      </files-filters>
      <files-sets>
<![CDATA[
]]>
      </files-sets>
      <files-mappers>
<![CDATA[
]]>
      </files-mappers>
   </stage>
</module>

Description of the library.xml file

Necessary data:

• package
• version
• release number
• id (in main cases "package"_"version")
• home uri
• download uri
• maven goup id
• maven artifact id
• maven version

<library id="">
   <package id="" name="">
      <maven>
         <groupId /> optional (default to "org.restlet")
         <artifactId /> optional (default to package, always concatenated with "org.restlet.lib")
         <version /> optional (default to version.release or version)
      </maven>
   </package>
   <version></version>
   <release></release>
   <distributions>
      <distribution id="classic|maven" includes="" excludes="" />
   </distributions>
   <homeUri></homeUri>
   <downloadUri></downloadUri>
</library>

Sources of diagrams: buildEditions

Distributions

Current supported editions:

• jse
• jee
• gwt
• gae
• android

Maven group id: org.restlet.<edition>

Files distributions

• zip: http://www.restlet.org/downloads/<minor version (2.0)>/restlet-<edition>-<compact version (2.0m4)>.zip
• Installer for Windows: http://www.restlet.org/downloads/<minor version (2.0)>/restlet-<edition>-<compact version (2.0m4)>.exe

Code annotations

The aim of this set of code annotations is to provide text transformation rules in order to generate a new version of a class for a specific edition. Basically the following transformations are supported:

• remove a specific bloc of code, or single instruction, or method, or member  for the current edition
• add a specific bloc of code, or single instruction, or method, or member  for the current edition
• specify that the whole class must not be part of the current edition

The implementation is not incarnated by a set of Java annotations which are not flexible enough. The idea was taken from the concept of conditional compilation used for other languages such as C. It consists only of simple Java comments:

1. // [ifdef <list of editions>] <optional keywords>
2. // [ifndef <list of editions>] <optional keywords>
3. // [enddef]

The avantage of such comments is that they can be put everywhere in the source code, and still remain even if the source code is automatically formatted by the development environment. Note that unfortunately, Eclipse does not allow such comments in the section where are declared the "import"  classes.

Explanations

The "ifdef" and "ifndef" annotations mark the beginning of a block. Such blocks target a list of editions specified with a simple coma-separated list of editions id. According to the optional keywords, they may  require the end block marker: "enddef".

As sample code says a lot more than a flow of explanations, here is the way to indicates that the a block code apply only for the jee and jse editions:

// [ifdef jee,jse]
instructions1;
instructions2;
// [enddef]

On the contrary, the following code will be removed for the gwt edition, but will be applied for any other:

// [ifndef gwt]
instructions1;
instructions2;
// [enddef]

Now, imagine that the gwt edition requires a set of instructions that must not be be included in the unique source code. This code must be commented in the unique source code, but uncommented for the gwt edition. Let's introduce the "uncomment" keyword:

// [ifdef gwt] uncomment
// instructions1;
// instructions2;
// [enddef]

Note that the "uncomment" keyword applies for both ifdef and ifndef block markers.

Finally, let's introduce the other available keywords. They aim at lighten the unique source code and get ride of the "enddef" blowk marker. At this time, three keywords are at disposal: member, method and instruction.