OSGi Components – Simply Simple – Part I

There is a lot of prejudice and misunderstanding when it comes to OSGi. As with every technology there is a learning curve and some things might be different than you are used to. But change isn’t necessarily a bad thing.

Component-oriented development is a very common and powerful software engineering style where you assemble your application out of components. A component might offer a service, e.g. a scheduler service. Other components can use this scheduler service.

Or a little bit more formal: a component is a piece of software managed by a (component) container. In Java this means this is an instance, created and managed by a container. Therefore it is not the task of the developer to create or configure these instances. This is the task of the container. If the component uses other services, it is also the task of the container to pass these services to the component. Therefore a service is a component which provides one or more services. In Java this means a service implements one or more interfaces where an interface represents the service description or contract.

OSGi Components with Declarative Services

I will show that developing components with OSGi is really simple and straightforward with no additional cruft – and I think it can’t really get much easier than this. We’ll be using the Declarative Services specification(see OSGi Compendium Chapter 112) in it’s latest version (R6). With the use of the annotations also defined in this specification, components are usually POJOs with all its benefits.

I will not go into the usual tooling discussion – there are different tools out there for your favorite development environment for processing these annotations, like Ant, Maven, Gradle. In contrast to other solutions, all the annotations are build time annotations. They are processed by some tooling and create additional files which are put in the final jar (bundle). I don’t explain everything in every detail and leave out things here and there – it is advisable to read the mentioned specs in addition!

Please note, that using Declarative Services (DS) is one way of developing components and services for OSGi, there are other approaches like Blueprint, Apache Felix iPojo, Apache Felix Dependency Manager etc. Each one of these solutions (including DS) has pros in some areas while it has cons in others. I think, DS is a simple and straightforward way of developing components and its a standard maintained by the OSGi alliance. It’s easy to learn, easy to manage and maintain and provides all required features. However, if you plan to use something different than DS, the real good news is: you can mix and match all these approaches – they’re all based on the OSGi service registry and work well together!

With Declarative Services we have a nice component container managing our components and providing them with configurations and required services. As we’re talking about OSGi here, we’re talking about bundles, so the classes for your component or service go into a bundle. Declarative Services (DS) needs to know which classes are components, what services they might provide etc. Therefore your bundle should contain an XML file for DS which exactly defines this. You might know such XML configuration files from other frameworks – however, the DS format is rather simple and – the good part – you never have to write this by hand and never even have to look at it (ok, if things go wrong, it might sometimes help to check it). At runtime the SCR implementation will read these descriptor files and manage the components and services. Oh, I forgot to explain SCR 🙂 It stands for Service Component Runtime and can be seen as the container defined by DS. Now usually people use SCR and DS as synonyms though that is not quiet correct for the purists amongst us.

So let’s start…

Components

If you want to write a component which is managed by the container, just add the @Component annotation to your class:

package com.mycompany.cool.project.impl;

import org.osgi.service.component.annotations.Component;

@Component
public class MyFirstComponent { }

Build your project, deploy your bundle into an OSGi framework which has SCR running (I recommend the implementation from Apache Felix, version 2.0 or higher) – and your component will be instantiated by the container on bundle start. As a component has never public API but is a private implementation, the class should go into a private package which is not exported by the bundle! It is good style to add impl or similar somewhere in the package name, like com.mycompany.cool.project.impl.

Now, while this component runs and works – it’s not really useful as the component does nothing.

Lifecycle

As noted above, the container manages the lifecycle of the component, its instantiation and removal. In order to make this work, the component class needs the default zero argument constructor. However, if the component wants to do something during the creation or the deletion phase, it can implement an activate and/or deactivate method and mark it with the according annotation:

package com.mycompany.cool.project.impl;

import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Deactivate;
 
@Component
public class MyFirstComponent {
 
    @Activate
    protected void activate() {
        // do something
    }
 
    @Deactivate
    protected void deactivate() {
        // do something
    }
}

It is good practice to name these methods activate and deactivate – however you could pick any other name if you want. The methods have to be protected with no return value.

Still, we have a component not doing that much, so lets do something “more” usefull:

package com.mycompany.cool.project.impl;

import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Deactivate;
 
@Component
public class MyFirstComponent {
 
    private volatile boolean doRun;
 
    @Activate
    protected void activate() {
        final Thread t = new Thread() {
            public void run() {
                doIt();
            }
        };
        t.setDaemon(true);
        doRun = true;
        t.start();
    }
 
    private void doIt() {
        while (doRun) {
            System.out.println("I'm still alive!");
            try {
                Thread.sleep(60 * 1000);
            } catch (InterruptedException e) {}
        }
    }
 
    @Deactivate
    protected void deactivate() {
        doRun = false;
    }
}

We create a new thread in activate and start it – in the thread we print out a message every minute. In addition we use a boolean variable to stop the thread when the component gets deactivated. While this example is not a production ready implementation, it shows that the thread of the activate and deactivate method “belong” to the component container – so the component should return as quickly as possible and do not block this method. Therefore we created an own thread. Please note, that this is just an example to demonstrate something, for things like timed execution, you would rather use a scheduler invoking your component periodically instead of running an own thread inside your component. The Apache Sling scheduler is a great way of doing things like these.

Using Services

A single component alone does usually not make up an application – it is rather assembled of dozens if not hundreds of components interacting. And interaction happens by using services.
So let’s extend our example – we use the event admin (another OSGi compendium spec with a great implementation from the Apache Felix project). The event admin is a service which allows us to send out events in a publish/subscrib kind of way. So each event gets a topic, and subscribers subscribe with the topics they are interested in.

A component can use other services by using the @Reference annotation. The container uses dependency injection and injects references into fields:

package com.mycompany.cool.project.impl;
 
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Deactivate;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventAdmin;
 
@Component
public class MyFirstComponent {
 
    @Reference
    private EventAdmin eventAdmin;
 
    private volatile boolean doRun;
 
    @Activate
    protected void activate() {
        final Thread t = new Thread() {
            public void run() {
                doIt();
            }
        };
        t.setDaemon(true);
        doRun = true;
        t.start();
    }
 
    private void doIt() {
        while (doRun) {
            final Event event = new Event("alive", null);
            this.eventAdmin.sendEvent(event);
            try {
                Thread.sleep(60 * 1000);
            } catch (InterruptedException e) {}
        }
    }
 
    @Deactivate
    protected void deactivate() {
        doRun = false;
    }
}

The above example looks pretty simple and from a developer’s point of view it is simple. You just declare an instance variable with the type of the service you want (services are registered by the interface(s) they implement) and add the @Reference annotation. Before the component is activated (the activate method is called), this instance field is set with the event admin service from the container. Therefore it is safe to assume that the event admin service is available and setup.

As OSGi is highly dynamic, bundles and services can come and go – so the event admin might be there or not, disappear, reappear etc. You don’t really have to care about this (at least not for the moment). Your component is only active if the event admin is available – if not, your component will either not be activated or will get deactivated. We’ll go deeper into references later on and learn how to cope with all the dynamics of services.

With just these four annotations you already know the building blocks for developing OSGi components and services. I suggest you test out the examples and make yourself familiar with using your favorite development environment. Once you are able to successfully build and deploy these components, you’re ready for the cool fun stuff of DS which I will show in part two.

Stay tuned.

Hello world!

It took some time, but my website has a undergone several changes – which hopefully enable me to blog about interesting stuff in the future. The past has not seen frequent updates from me, the main reason (excuse?) being very old software in my web space. I’ve now removed all that stuff and replaced it with something new…

Let’s see how this works

Apache Axis2 Book

I recently had the change to review the second edition of the Apache Axis2 book from Deepal Jayasinghe and Afkham Azeez. I think it gives a nice overview of the various web services aspects and how to develop applications with Apache Axis2. On the one hand it can be used as a reference for the various web services standards and Java APIs in this area, on the other hand it also covers important topics like clustering and enterprise integration patterns. It comes with samples which show how to use Axis2. In general its a nice book which you consider when using Axis2. Some examples or descriptions could be a little bit more detailed though.
There is still the Packt Graphic Apps and Libs Campaign.

Increasing Interest in JCR and Apache Sling

I’m attending some tech conferences in the Java space for several years now; for the last years I’m trying to push JCR, Apache Jackrabbit, and Apache Sling at various occasions – mostly through several talks. It seems to me that there is a change/increase in interest for these topics.
While two years ago, people have not been really that interested in JCR and usually asked questions along the line of “why should i use this? I have a database, it works fine” etc., this has definitly changed now. There are more and more people interested in alternatives to a POD (plain old database). It seems to me that the pain with traditional dbs is now too much and they’re searching for nosql solutions. Don’t get me wrong, JCR is not the golden hammer for data storage – there are valid use cases for PODs, but there are also many use cases where an alternative like JCR is much better suited.
Today people ask questions like “I looked at jcr, I have this problem, and I think I could do it this way. What do you think?” and of course variations on this theme.
I don’t think that this is motivated through the NOSQL hype, I ratherthink that this is a parallel movement which has the same origin. In addition, these people seems to know a lot about Apache Jackrabbit and usually ask deep going questions. As I’m not working on Jackrabbit itself – I’m a user of Jackrabbit – these questions usually give me a hard time 🙂
While I have a hard time with Jackrabbit questions, people seem often to have a hard time understanding the needs for Apache Sling. For one this might be cause they are still living in their POD driven world and know how to handle applications based on databases. Building applications on top of NOSQL solutions is a slightly different thing. When it comes to Apache Sling which is a web framework, it is immediately compared against web application frameworks with all the nice ui features, widget libraries and whatnot. And as Sling does not provide a UI library it is often immediately discarded.
But on the bright side as soon as people realize that they need something like JCR and now need a way to get all this content stored in the repository out to the users in a nice, elegant and flexible way, they also realize that Apache Sling helps a lot.
So my hope is that the adaption of JCR is increasing (and I think that is already the case) and that this drives the adoption of Apache Sling as well 🙂
And of course we are not day dreaming in Apache Sling – we will continue it’s development and add missing pieces or provide bridges etc.

Rapid Development with Apache Sling using an IDE

Apache Sling allows you to use scripts to render your content. Usually these scripts are stored in the repository as specific path. While it is possible to directly edit a script in the repository (using WebDAV), this editing happens out of your project’s context. But fortunately there is a better way!
Usually your project consists of modules (or a single module) which are deployed as OSGi bundles. To get your scripts into the repository, you add the scripts as resources to your project and use the initial content feature from Apache Sling to add the scripts to the repository.
So you usually end up with your module (bundle) checked out in your IDE (Eclipse for example), you do your initial development here (develop your OSGi services and scripts). For testing purposes you deploy the bundle (using the Maven Sling Plugin) which copies your scripts into the repository. From here they get picked up by Sling. If you now edit your scripts directly in the repository you have to take care to synchronize the changes with your checked out project in your IDE which can be an error prone and annoying task. Or you can edit the scripts in your IDE and then either redeploy your bundle or manually copy the scripts via WebDAV – which doesn’t make the process easier.
Fortunately Sling provides some tooling which makes these extra steps obsolete – actually we have this feature for a long time now but I always forgot to write about it…of course the following is only interesting for you, if you’re using Maven for your project.
Now, imagine your scripts are for your own node types which use the namespace prefix “myapp”, so you have a “src/main/resources/SLING-INF/content” (this is a convention for initial content) directory in your project. This content directory now contains a sub directory “libs” (or “apps” or any other configured search path) with your scripts. Underneath “libs” you have the “myapp” folder with a folder for each node type and this folder contains then your scripts (it’s really easier than it is to describe in textual form).
You’ll add a configuration for the Maven Bundle Plugin for adding the initial content header to your pom.xml:

<Sling-Initial-Content>
SLING-INF/content/libs/myapp;overwrite:=true;path:=/libs/myapp
</Sling-Initial-Content>

This basically copies the contents of the “/libs/myapp” folder on bundle install into the repository at the same location. On each update the contents gets overwritten.
Now add the Maven Sling Plugin to your pom.xml:

<plugin>
<groupId>org.apache.sling</groupId>
<artifactId>maven-sling-plugin</artifactId>
<version>2.0.3-incubator-SNAPSHOT</version>
<executions>
<execution>
<id>install-bundle</id>
<goals>
<goal>validate</goal>
<goal>install</goal>
</goals>
<configuration>
<mountByFS>true</mountByFS>
</configuration>
</execution>
</executions>
</plugin>

In the configuration above you can spot to new features of the latest plugin version: the validate goal will validate all *.json files and more important for our topic, the configuration “mountByFS” with the value “true”. Apache Sling has an extension bundle called file system provider (aka fsresource) which allows you to mount a file system path into the resource tree. So basically you can point for example the Sling resource path /myphotos to some directory on your server containing photos. This allows you to directly use files with Sling without copying them into the repository. Once you have installed this bundle into Sling and use the above configuration, each time you build your bundle with Maven and do a “mvn install”, the Maven Sling plugin will create a fsresource configuration for your initial content. In our case the Sling resource path “/libs/myapp” points to the file system directory “/src/main/resources/SLING-INF/content/libs/myapp”. So once you’ve done an initial install of your bundle, you can directly change the scripts in your IDE in your project. And the changes get immediately active, no need to sync and no need to copy. This makes development turnarounds for scripting much shorter as there is no turnaround any more.
The whole thing comes with a little drawback – with the configuration from above, your build fails if no Sling instance is reachable. So you should use a Maven profile for this configuration.

JAX, Apache Sling and Accidental Complexity

This year the number one Java conference in Germany, the JAX 09, is great as always. With nearly the same number of attendees it’s crowded in the positive sense – although you have to go to a session in time to get a good seat. I’ve seen a lot of highlights today – but first was my own presentation about JCR, OSGi, Scripting and REST – which presented the great Apache Sling web framework. Apache Sling uses Apache Felix as the OSGi framework and Apache Jackrabbit for the content repository. My session was very well attended, more than I expected, and while preparing the talk I noticed that I actually have more presentation material for JCR/Jackrabbit and OSGi/Felix than for Sling itself; although Sling is of course the topic of the session.
I think this shows that Sling is really a very clever framework, leveraging existing stuff and combining it in a productive way – this goes hand in hand with the great keynote tonight from Neal Ford – now, I can’t summarize it for you, but one of the key points was: don’t make things more complex than they should be (just because somethings that it makes sense or is cool). Look around and make use if available stuff – even if that doesn’t look cool for your developers. Most of the time is spent on accidental complexicy which in the end causes projects to fail.
I’m in the software world for over 20 years now and Neal is spot on with his message; i’ve seen a lot of projects fail because of this or because of one (or more) of the anti-patterns Neal mentioned.
Unfortunately I missed the sessions from Neal’s collegue Ted Neward which I enjoyed last year, but I saw an interesting session about the tools in Spring IDE for Spring, OSGi and Spring DM – now this looks pretty cool to me; I’m not in favour of using Spring as I think that there are more lightweight 🙂 solutions when it comes to OSGi – but on the other hand giving the fact that everyone and his dog knows Spring and given such good tooling with Spring IDE, it’s really hard to advocate something else. With the upcomming OSGi blueprint specification this will also have an impact on OSGi. And in the light of Neal’s talk, what could possible reasons be to not use this stuff? It would be great if the tooling would work with any OSGi framework and not just the Spring server.
But these are just excerpts from the day – and it’s just the first day; I’m looking forward to tomorrow when the OSGi day takes place!
During the breaks I’m trying to finish some stuff for the upcomming Sling release – we hope to get it out in the next weeks. So stay tuned.

Portals Meetup at ApacheCon Europe

If you’re attending the ApacheCon Europe in Amsterdam in two weeks and if you’re interested in portals or portal related stuff (and I guess we all are interested into portals, right?), then you should join the portals meetup and add yourself here.
Even if you’re not into portals but are interested in visiting a zoo, there are a lot of hippo’s and dinosaurs (yes, really!) there. So it’s fun for everyone 🙂

Conference Season – ApacheCon Europe and JAX

In just two weeks the conference season for 2009 starts. This spring I’ll speak at the ApacheCon in Amsterdam about OSGi and some of the stuff we have at Apache for using OSGi within your own project.
Later, in April, it’s JAX time again – and again with a new location. My talk for the JAX is about the great Apache Sling project (JCR, REST, OSGi etc.). I’m happy to see that OSGi is one of the key topics for the conference with a lot of famous people there 🙂
Going to these conferences for several years now, I still think that the chance to meet people and talk with them is one of the greatest things – and especially these two conferences provide excellent opportunities. So don’t miss them! See you in Amsterdam and/or Mainz, Germany 🙂

Getting Started with Portal Servers and Spec Compliance

In the last months I had the nice and interesting opportunity to try out several portal servers – ranging from open source to the big commercial ones. As a summary upfront, the first time experience of nearly all solutions is REALLY ANNOYING; in some cases it’s unbelievable how poor and confusing everything is. Just as a disclaimer, this is my personal opinion after playing around with these servers for just a short time.

But let’s be more precise…I started with looking for open source portal servers implementing the JSR 286. Due to bad experience in the past I avoided the JBoss portal (this might be unfair as my experience is two years old.). Apache Jetspeed does not support the standard yet, so I looked for Exo and Liferay. I think their web sites are overloaded, they look too much like a brochure for me and getting to the real downloads requires too many clicks.

After downloading Exo, I found a nice README in the root directory which tells you briefly how to start the portal and what the admin credentials are. Nice and easy. Unfortunately after starting the whole thing, I got lost as I found no way to deploy my portlet. Afer downloading the docs (again some clicks) I found out that the downloaded version does not support the deployment of portlets through the UI. I think deployment through the UI is a number one feature. So I immediately stopped here and went to Liferay.

They have the same shiny web site, sigh, and after downloading you have “something” extracted. The provided README is the Apache Tomcat README, so no real clue about how to start this thing. As I’m able to start Tomcat and know the default port I could get the portal running easily. Looking for the admin credentials required to download the docs and search for it. It took me some more reading that for Liferay everything is a plugin, even a portlet. So I uploaded my portlet through the UI and got it running immediately. I didn’t found any spec related problems with my portlet, however the AJAX based UI of Liferay seems to have sometimes problems with render parameters.

Then it was time for the commercial ones. Fortunately I had someone else downloading and installing WebSphere and Weblogic Portal for me and providing me the admin credentials. Of these two, WebSphere is slow, has an overloaded admin UI, but deploying your portlet through the UI is nice and easy. I didn’t found any spec related problems. Nothing more to say about this one 🙂

But the nightmare of every portal developer is Weblogic Portal. It seems to be even slower than WebSphere, is full of bugs and has a more than overloaded and unstructured admin UI. There is no menu for deploying a portlet. So I went to the website, and really got lost. It took me some time to find a small guide explaining how to deploy JSR 168 portlets…hmm but I had a 286 portlet. Ok, let’s try it anyway. The unbelievable thing is that the UI for uploading a portlet is not linked from the portal admin console. It seems that this vendor is rather ashamed of having this. And after you type the secret url in your browser, you know why. Honestly, I’m really bad in doing nice looking html pages, but I think I could have done even this one better. Ok, good looking is not important in this case, so I ignored that and happily uploaded my portlet. Then I knew why these things cost a fortune….it took the server three minutes to deploy my little portlet – at least that’s what was displayed after three minutes. So back to the real admin console and trying to find my latest deployed stuff…hmm, where is it? Ok, consulting the same docs again, it explained that I have to configure a WSRP provider. Wait a minute…did you say WSRP, like in WSRP = Web Serices for Remote Portlets? Oh well, my portlet is running locally (hopefully), so it makes sense to configure something running remotely. Indeed. Shrug, just follow the docs and you will find success…of course, not! Ok *something* is wrong. Now, if you’ve seen one of these server beasts you know that they have a separate server console where you can see and configure millions of things (the more configurations you have the better the product is, I guess), so after several clicks I found out that my portlet application had not been deployed correctly. How could this be? It wasn’t my fault, so it should be the servers fault..ok to keep a really long story short, in order to deploy a portlet application you have to copy it physically to the hard drive on the portal server, invoke the browser based UI and upload the application through the browser (again). This must be some strange security feature or one of those evil developers still laughing today in his cubicle about this funny joke he did. (Oh and btw, don’t use Firefox 3 to upload your portal applicaiton, the server is not capable of handling the requests correctly…but fortunately the server happily accepts the requests and pretends that everything is fine)

Ok, but the best part was still to come. I went back to the portal admin console, configured the WSRP consumer (still, can someone explain me why? – ok, I’ve an idea why it could be this way, but I think it’s wrong to impose technical decisions on the UI.). From here everything went smoothly, I configured the portlet, added it to the page, got some server crashes and broken pages and finally came to the page with my portlet. Remember that this was a JSR 286 portlet deployed through the JSR 168 import tool? Ah well, everything went fine until my portlet should render itself. Some wired exceptions occured.

After some experiments it turned out that the server exposes the portlet 2.0 API and is able to deploy portlets relying on this API and using the new deployment descriptor. And if you inspect the API version from within your portlet it confirms to be a 2.0 compliant portal server. BUT as soon as you invoke a 2.0 feature you get an exception. I have zero idea what the intension of such an implementation is. Perhaps it’s again this developer in his cubicle? Or is it a whole team making fun of dumb users like me?

So after reducing my portlet to just use JSR 168 features it nearly worked – except for some more quirks and errors in the implementation of the spec. As a summary, I don’t want to use the WebLogic Portal server again.

In general, Liferay seems to be a good open source solution, if they only would add a small README to the downloaded archve. Without a deployment functionality, Exo is of no interest for me. If you’re into complicated UIs, slow running servers with zillions of features noone needs, use WebSphere – forget about WebLogic. The portlet API 2.0 spec compliants seems to be given with Liferay and WebSphere. So now I’m waiting for Jetspeed to finalize their support 🙂

Portlets and OSGi

OSGi is today used in many places, for desktop applications, complex application servers and even for web applications. But what about portlets?
In the last weeks I developed some portlets for our product offerings. The portlets allow you to display, edit and manage content inside a JSR 286 (portlet API 2.0) compliant portal server. As our whole product offering is based on OSGi for the obvious reasons, I thought about using the same technology for implementing the portlets.
By using the great Apache Felix implementation, togther with some of the nice things we developed in the Apache Sling project I could easily manage to start the OSGi framework inside the portlet web application. A simple generic portlet implementation running outside the OSGi world receives the portlet calls, like events, actions and render invocations. This generic portlet just forwards them to a receiving portlet running as an OSGi service. Once you are inside the OSGi world you can use all the benefits of OSGi for your implementation and it was quite simple to develop the “real” portlets. Besides using the same base for all of our products and being able to reuse stuff through well defined bundles and services, one of the main advantages during development has been the easy update of the portlet code. While the whole portal application has been deployed to some portal container, updating the portal did not require an update/redeployment of the portal web application. Just updating a bundle through OSGi is enough and your new code is deployed. This makes the development and testing way faster.
I really don’t want to miss OSGi in everyday development, it creates clear boundaries, enables real modularization and reuse and makes the development much easier. Start your server once and just update the parts that have changed. No need to restart, no need to update the whole application. Priceless!