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