wwerner's blog

Prerequisites

You should have skimmed over the first two posts of this series. If they do not contain new information for you you to not have to work through them, however since we are going to build upon the results from the last post, you should get the latest code from the post2 branch¹Â if you do not have it yet.

Introducing Extension Points

The extension point mechanism is a powerful feature that allows multiple bundles to communicate with each other. A bundle defining one or many extension points basically says “I am extensible. You can add your extension code here. “. An extension contributed to an extension point provides additional functionality to its bundle. The twist is that you can extend the bundle providing the extension point without making any changes to it. This is particularly useful when you want to customize/build upon an application without modifying it².

The extension point is a piece of XML schema that defines how contributions to that point are to be structured, i.e. which attributes they need in which cardinality and of which type. The contribution to the extension point is made in the plugin.xml file of the contributing bundle. In addition to that, there needs to be some code that evaluates all contributions to the extension point and provides them to the core implementation. Note that this also separates the implementation of single components (code) from their use (contribution). In my experience, this leads to a significantly improved overall design as the definition modular structure of an application is clearly separated from its implementation and people tend to think about modularization earlier and more clearly as a part of the development workflow³.

Eclipse and others uses this paradigm e.g. to provide IDEs in very different flavors^{4 5 6}, but they all share a common core.  I daresay that this  is one of the key factors to the success of Eclipse and its wonderfully vibrant and diverse ecosystem. The implementation of extension mechanism is provided by the Eclipse Equinox project ⁷. You could argue that a similar result can be achieved by using plain OSGi (declarative) services, perhaps we’ll do so in a later post. For a comparison refer to Neil Bartlett’s excellent posts^{8 9}.

If you want to dig deeper, there is quite a number of useful articles on that topic out there ^{10 11 12 13}.

The Restlet Registry – Extension Points

The backbone of our new architecture will be the Restlet registry. It will contain the definitions of our extension points  and the supporting code that evaluates contributions to these extension points. Our final registry will consist of multiple extension points:

• Resources
• Components
• Applications
• Routers
• Filters

For this post, we’ll only implement the first two, the other two will be in the example code as well¹⁴ but I won’t describe them in detail here¹⁵. To gather the contributed extensions, wire them at runtime and start  the application at runtime, we’ll also need to write some code.

To avoid clutter¹⁶, we’ll put all registry components into a new bundle. Create a new bundle as described in the first post ¹⁷ and call it “net.wolfgangwerner.restlet.registry”. 

Let’s start with the first extension point, Resources. A resource consist of an ID and a corresponding implementation class. First, activate the editors for extensions in the new project’s properties.

To be able to reference the the ServerResource interface, it needs to be added to the registry bundle’s dependencies.


After that, open the MANIFEST.MF file from the META-INF folder an go to the extension point tab. Click “Add” to add a new extension point. Enter ‘resources’ as ID ¹⁸ and ‘Restlet Resources’ as name.

 

Clicking “Ok” takes us the extension point schema editor. You should really enter useful information on how the extensions contributed will be handled. The function of your extension point may seem clear to you now, but remember you are building an interface for public (more or less) consumption.

Now let’s go to the “Definition” tab and add a new element “resource“. Add the attributes “id“, “name” and “class” to the new element. IDs  and names should have the type String; Classes the type Java with the restriction that contributed classes must implement Restlet’s ServerResource interface. Then select the ‘extension’ element and add a “New Sequence” of the cardinality 1:n. Add a reference to the “resource” element to the new sequence.

 

The next extension point to implement  is the one for Restlet Components. It should be able to handle a collection of component elements, each with a name for human (developer) readable representation, a list of servers it uses (each with protocol and port) and a list of referenced resources. Note that if you create references to IDs, you can also restrict the element you want to reference. Go ahead and try to create the extension point on your own now. If you get stuck, the screenshots¹⁹ below should help.

The following list summarizes all extension point elements created so far:

• Resources
  • resource (1:*)
    • id (String)
    • name (String)
    • class (Java, implements org.restlet.resource.ServerResource)
• Components
  • component (1:*)
    • name (String)
  • a  list (1:*) of elements of the types
    • server
      • name (String)
      • protocol (String)
      • port (String)
    • resourceReference  (1:*)
      • urlTemplate (String)
      • resourceId (Identifier, Restlet Resources/@id)

Contributing Restlet Extensions

Go back to the original net.wolfgangwerner.tutorial1.restlet bundle and open the plugin.xml file and go to the “Extensions” tab. Click “Add” to add a new extension point to contribute to. In the following dialog, deselect “Show only extension points from the required plug-ins”. Select the resources extension point we just created and click “Finish”. When prompted, confirm you want to add the registry plug-in to the list of required bundles.

Since we specified a lower bound of one element for the resource element, one has already been created for us. PDE is smart enough to parse our extension point schema and configure the editor correspondingly. ²⁰

Enter an ID, a name and the implementing class. The ID is used later to attach the resource to the Restlet Component. You should use a fully qualified ID (i.e. including the bundle name) here to make it unique within the runtime²¹. Though you can choose any ID you like, using a fully qualified one protects you from name clashes with extensions in other bundles. The name will be used as label in the extension editor; use a label that helps you identifying it once you contributed a larger number of resources. To chose the implementing class, you can use the code assist shortcut Ctrl+Space.

Repeat the last steps to contribute the Greeting List Resource in the same manner.

Then add a component extension and use its context menu to define two servers (e.g. HTTP on port 80 and on port 8080). Then add a resource reference element, enter “/greet” as URL template and browse for the corresponding identifier²².

Now your extension definitions should look like this:

The Restlet Registry – Implementation

Now that we have defined our extension points and contributed our code to them, we need to write the code that actually does something with this information.

As we need to reference the registry bundle to get its extension points, we add an ID to its Activator. The ID is the same as the bundle id of the registry bundle²³.

To keep the code that evaluates the contributed extensions separate from our bundle life cycle code, we create a new class called RestletRegistry that encapsulates . We can simply ask the Platform to give us all contributions to a specific extension point.  We specify the extension point by its namespace ²⁴ and the name of the extension point. We iterate over the list of contributions and save the contents in our Restlet Registry. This is straight forward for the ‘id’ attribute but requires some thought for the resource class. While there is a shortcut to create an executable extension (read: Object) from a class attribute, this doesn’t help us: The Restlet API requires us to attach the resource’s Class. In a non-OSGi environment, we could simply call Class.forName(String), but this will fail here as each bundle has a separate class loader. Instead, we need to get the contributing bundle and let it load the class for us using its own class loaded²⁵.

Getting the data from the component extensions is pretty straightforward. We get the extensions as we did for the resources, create a Restlet component for each extension, then add the corresponding servers to it and attach the resources at the given URL templates.
To keep our code clean²⁶, we split the parsing into several small methods²⁷.

You’ll have noted that there are several exceptions that can be thrown when working with extensions. In real life, you’ll need to safeguard your code against invalid extensions²⁸. Invalid extensions should be ignored and logged but may not impact other extensions contributed to the same extension point or obstruct the operation of the core.

In the last post, we started our server from the Activator of the first bundle. Since we are going to start all contributed components instead of hardcoding them, we can delete this Activator class and remove it from the Manifest.

Now all we have to do to make it run is to tie the registered component’s life cycle to the one of our registry bundle and adjust our launch configuration to include and auto-start the registry bundle.

Launch it and verify that the greeting service is active by pointing your browser to

They tried to make me go to recap …

You just created a small framework to build Restlet based web services and run them on the equinox OSGi runtime. You started by building an OSGi bundle that contained a simple Restlet web service. You rolled this bundle into a standalone server application. In the second post, you extended the application and learned a little bit about Restlet. Along the way, you also picked up some OSGi knowledge.

In this post, we improved our application by allowing the contribution of additional resources from other bundles as well.

The application is not yet finished, I left some work for you²⁹. The next step is to create more extension points to allow the contribution of other Restlet subclasses (Filters, Applications and Routers) and finish the migration of the version from post #2.

Prior art includes the presentation of Shams and Norris on eclipsecon 2008³⁰. Originally I wanted to give the code they created a try, but was deterred by a strange license and download process. Others have noticed that as well ³¹.

I will wrap the final results of the Restlet Registry with all extension points into a project ready to use, stay tuned ³² if you are interested. I’d also be happy to discuss whether the current extension point setup matches real world requirements and how it could be improved. Implementing a Restlet OSGi service is also very conceivable. Let me know if you want to help or simply go ahead and fork the repository.