Multiple Bundles per Project

I just got back from a very successful JAX London, these are always very well organized conferences and this conference was no exception. Yesterday we had an OSGi day during which Neil Bartlett succeeded in writing a Vaadin Web application without having to restart the application OSGi framework. OSGi is well on its way to provide a development process with much shorter turn around time than any other environment I know. All because of its dynamic model, there is just no need to restart the framework even if you make very big changes in your code, even your bundle layout can change or the run environment.

During this presentation someone in the audience asked why bndtools supported multiple bundles per project because all other environments (like Maven, PDE, etc) limit a project to a single artifact. So why does bndtools have multiple bundles per project? There are several reasons and I think it is interesting to highlight them.

The first reason is practical. In the OSGi build for the Reference Implementation and Compliance Tests has over 1300 bundles, mostly test bundles. Having to maintain that many projects would be very painful. In reality we now have only around 130 projects. I shudder what it would mean to have 1300 projects in your Package Explorer ...

The second reason is cohesion. Sometimes your deliverable consists of multiple bundles that are actually quite cohesive. For example, assume there is a bundle that is useful on its own but someone wants to use it in conjunction with Spring. To support that use case, your bundle then requires an import of a Spring package, which would transitively drag in many other packages. You could make this import optional but that is awkward. The best solution would be to create two bundles, one with,  and one without Spring. You could even make them a main bundle and a fragment for the Spring dependency. Being forced to put these two bundles in different projects creates an artificial separation that unnecessarily complicates development.

Last but not least, when we begin, we rarely know where the module boundaries are optimal. In bndtools an extra bundle has no overhead. It is easy to move packages between bundles or even allow them to live in multiple bundles. Experimenting with splitting a bundle or combining, or even just creating a test bundle, has no associated costs. In my experience, this changes the way you think about bundles, the process of developing them becomes more fluid. I rarely have projects that produces a single bundle nowadays. However, if you prefer a single bundle per project then that is your choice, 1:1 is the easy case.

That said, I actually never understood why popular build tools are constrained to a single output per project. Isn't that a little bit too much convention over configuration?

Peter Kriens


P.S. Ok, ok, Neil's Eclipse instance crashed because it ran out of heap space killing the application framework as well. So he almost reached perfection. :-)

OSGi lite

Yesterday we had a rather heated discussion during the CPEG meeting here in Austin.We discussed OSGi lite for which I had submitted an RFP (the requirements document). Key issue was the positioning, there was a general concern that an OSGi lite detracts from the core message: strong modularity. It would encourage you to work more modular but lacking enforcement of the module boundaries would not help solving many of the problems that plague our software industry today: we too often build on fuzzy foundations.
In my previous post I stated that OSGi lite would provide 80% of the benefits and this was seen as too high by some. I do agree that the 80% was not very scientific, it is a very personal estimate. I picked 80% because I do believe that the µservice layer  is the most important software innovation since OO came around in the eighties. Building systems out of µservices automatically makes systems more modular because they minimize  coupling.

That said, the modularity layer also does provide lots of advantages, especially when used within larger groups. Strong modularity can enforce rules across the development life cycle that are vital for large projects. As John Wells (from BEA at the time, now Oracle) once said: "If you think you're working modular but you're not using OSGi, then you're not working modular." Unfortunately, most people are not working modular and find the path to OSGi's strong modularity too painful. OSGi lite is the on-ramp to OSGi because it provides immediate benefits in any WAR or class path based application without any pain. Once you moved your code base to µservices you can then more easily transition to OSGi to reap its additional benefits.

So the question of conscience is, what will I use? If I think I get 80% of the benefits, why bother with the real thing? 

After working with OSGi lite last week I felt, a bit to my surprise, that the development cycle with OSGi is much faster and smoother than with OSGi lite. The difference is the dynamic update of OSGi. The Eclipse debugger can replace code in memory but it often has to restart because certain changes cannot be applied in a running process. Using bndtools this is never a problem because every time you save the source file it rebuilds all artifacts and deploys them on the running framework immediately. It works so smooth that that the deployment step becomes largely invisible. So with OSGi you can work for days with the same framework happily humming along. In contrast, working with OSGi lite forced me to use the standard Java Application run mode and the GWT Servlet runner that were not even remotely as smooth. And not to forget, the framework finds many hidden errors like missing packages, invalid versions, etc. before your code stumbles over them.

Last but not least, with OSGi I know it will deliver when I run into hard problems because it is mature. I might today not have many of the problems OGSi provides solutions to, but when tomorrow comes that situation might differ. If you would develop on OSGi lite you're bound to have a serious porting problem when you would not test/develop your bundles on OSGi regularly. After all, its strength that allows all these class loader hacks is also its greatest weakness.

Peter Kriens

P.S. All opinions in this blog are mine not necessarily the opinion of the OSGi Alliance. As should be clear in this case, OSGi lite is not without controversy inside the OSGi Alliance.

OSGi Lite

A few years ago I wrote a blog about OSXA, an OSGi framework without the module layer. Over the years, this idea kept intriguing me and discussed it with many but never found the time to work on it. Unfortunately, OSXA seems to be no longer active (the web site appears to be in zombie state) but thanks to Karl Pauls this idea has given a new lease. Last week, at the (fantastic as usual) EclipseCon/OSGi DevCon, he surprised me with an implementation of OSGi Lite. OSGi Lite is OSGi without the module layer; he based his implementation on Apache Felix.

OSGi without modules is so interesting because it significantly simplifies the migration to the service layer from existing (web) applications. Services are for me the key innovation in OSGi; the module layer was only a necessity to make that service layer work. Playing with OSGi Lite I realized that in a way we've been trying to convince the market to go OSGi without a good transition model. We promised all those goodies but then adopters had to basically refactor their whole code base before they could benefit from these goodies. Not particularly good marketing.

The primary transition problem is that today class loader hacks are prevalent in Java code. These hacks make it appear that "modules" are decoupled from each other.  For example, the JVM's Factories pervasively use a multitude of class loading hacks to desperately find an implementation for an interface; the Service Loader model supposed to improve the class loading hacks even hard codes the class loader in its API. Though an extension mechanism might be based on class loaders a cohesive design should not expose this implementation detail in the API as the Service Loader does.

All these class loading hacks are the antithesis of modularity because they mandate the visibility of implementation classes across module boundaries. Your POJO might look superficially  like a POJO but in classic Java someone in your code base must violate module boundaries to get an implementation. You can try to hide in some Spring XML or  Guice module but it is inevitable that someone needs global visibility. This is the exact problem addressed by the OSGi service layer. In OSGi, the only one knowing the implementation class for a service is the module that owns it, as it is supposed to be. It is even better, the module can register instances with context instead of having to revert to statics to provide context.

However, to be able to reap the wonderful benefits of the service layer one has to remove all the class loading hacks and that is usually a big change. Big changes in an active source base are usually not such a brilliant idea. Therefore: meet OSGi Lite.

Karl's OSGi Lite implementation is based on Apache Felix, ensuring good fidelity with a real OSGi framework.  His implementation runs in any standard Java environment: class path, WAR files, wherever your current Java is running because it never touches a class loader. Running an OSGi application is as easy as running the main method in PojoSR while the class path contains the "bundles". PojoSR will scan the JARs on the class path and treat each JAR as a bundle regardless if it is a bundle or not. If the JAR is a bundle and contains a Bundle Activator then this is activated. If you want to own the main method, you can initialize the OSGi Lite subsystem yourself using the META-INF/services model.

It is quite surprising how many bundles actually work out of the box: Declarative Services, the shell, etc. all work well with a bit of twiddling. With many bundles the only problem is the Bundle-ClassPath, this obviously does not work. However, it is trivial with bnd to unroll the bundle class path with the @ operator. For Felix's declarative services I had to do unroll the Bundle Class Path because it included the KXML parser.

To demo OSGi Lite, I wanted to port an existing application to OSGi to show how easy it has become.

After "one of those days" where every open source project I tried to build failed horribly(SpringSource Pet Store, Sun's Pet Store, some GWT Pet Store, and others). After half a day of horror I ended up with the Google Web Tookit  (GWT) standard sample application. GWT provides an Ajax based GUI environment combined with a Remote Procedure Call (RPC) model. The demo application sends a message to a GreetingService (!) and displays the result in a dialog.

The standard GWT GreetingService is definitely not a POJO because it must extend the RemoteServlet class. From a modularity point of view this is bad, really bad. Now we have OSGi Lite we can create a Dispatching Servlet bundle that decouples the Greeting Service POJO from the web environment. The Dispatching servlet creates the OSGi Lite runtime with Karl's code when it is first constructed. It then receives all the GWT requests and then uses the service name, which is embedded in the request, to find the service in the OSGi registry. It therefore is not coupled to any service code at all, it only knows the standard GWT classes. The next stage was to create a bundle that provided the Greeting Service. Well, with bnd's annotations and bndtools that was a snap. These two bundles then had to be placed in the WEB-INF/lib directory to become part of the WAR's class path.

To test this I used the GWT Eclipse plugin, this provides an environment based on Jetty to run a directory that looks like a WAR. This was a bit painful because I had to copy the bundles to the lib directory whenever I made changes and for some reason all the XML and hard coded path names make this stuff incredibly fragile and error prone. I really missed the standard dynamic run environment from bndtools! But I got it to work. I then created a war file and ran it on AWS Beanstalk, which worked like a charm (might be gone by the time you read this because it costs money to run there). You can find the workspace for this code at github, see the aQute.gwt.war project.

What did we achieve? From a modularity point of view the code has been significantly cleaned up. We could turn the Greeting Service implementation into a real POJO that no external dependencies while the old one was heavily coupled to the servlet API and GWT's implementation. Now, the service is deployed as a separate bundle and can easily be substituted. Also in this case the service registry demonstrates the shining power of the µservice model!

Conclusion
OSGi Lite provides 80% of the power of OSGi in a completely non-intrusive way. It allows any application build in Java to reap the benefits of increased modularity without first having to rid an existing code base of any of its class loader hacks; all these hacks just keep working as they used to work because everything runs in a single class loader.

The drawback is is that OSGi Lite does not enforce module boundaries and obviously does not allow multiple versions of the same package, nor does it support the Bundle-ClassPath. However, with OSGi Lite applications can move to the µservice model with virtually no complexity. The µservice model can then be used to get rid of the class loading hacks over time, after which it will be really easy to move to OSGi and get side by side versioning and real module boundaries.

It would be interesting if the OSGi Alliance would standardize this OSGi Lite model. So from these experiences I've written an OSGi Request for Proposal (RFP) and submitted for discussion next week in Austin. Though a standard is not absolutely  needed to start playing with OSGi Lite now Karl has implemented it, it would be better if the model was officially condoned by the OSGi Alliance. It could be used without coupling to a particular implementation.

I think this could be one of the biggest enablers for the OSGi model ever. If you're interested, check out the code and provide feedback!

  Peter Kriens

Karl Pauls' code: http://code.google.com/p/pojosr/
The GWT project: https://github.com/bnd/aQute

P.S. All opinions in this blog are mine and obviously not necessarily shared by the OSGi Alliance.

Metatypes

Many, many, many years ago I worked a lot with LDAP and the ISO communication standards like X.500 and X.700. Looking at the Metatype specification I am afraid I had some bad influence on that spec. Looking back, I probably would be able to make it a bit simpler today, however, I do believe that it is one of the specifications in the that under-appreciated. Actually, a lot of people have no clue what it is.

So what problem does the Metatype spec solve? The problem it addresses is runtime configuration. The OSGi Configuration Management specification makes it possible to configure bundles with properties. The problem we faced that gave us Metatype is that we needed a schema to describe those properties to editors and validators. At the time I was involved in creating automatically created user interfaces based on type information. The Metatype specification provided such type information for the configuration properties. In the first incarnation of Metatype we did not describe a format (seems silly and I forgot why), only hard to use Java interfaces. Later versions added a Metatype Service and an XML based format for describing the properties.

The Metatype specication has been in existence for quite a long time there are as far as I know very few editors built for it. Actually, the only one I am familiar with is the Apache Felix Webconsole. I am very interested in Metatypes because the triplet metatype + configuration + components (DS) provides a surprisingly powerful programming model. DS can control the life cycle of components based on the configuration data that is available. Creating a factory configuration causes the activation of a component (if it is satisfied of course) and deleting that configuration deactivates the component. Each component is provided with the properties of that factory instance. For example:

@Component(configurationPolicy=required)
 public class FactoryDemo {
   @Activate
   void activate( Map props ) {
      ...
   }
 }

Such a component will follow the life cycle of a configuration or factory configuration of the (factory) PID com.example.FactoryDemo (the name of the component). This model is one of the cornerstones of good use of OSGi: configuration driven design. This model allows us to register services that are under control of the deployer. For example, assume you want to make an interface to Amazon S3. Where do you store your acces key and secret key? If you have any real world experience you will of course not hard code them. So in a good design you would write the following code would register a Store service:

@Component(configurationPolicy=required)
  public class BlobStoreComponent implements Store {
    String domain;
    AmazonS3Client client;

    @Activate
    void activate( Map props ) {
      String secretKey = (String) props.get(".secret.key");
      String accessKey = (String) props.get(".access.key");
      AWSCredentials credentials = new BasicAWSCredentials(accessKey, secretKey); 
      client = new AmazonS3Client(credentials);
      domain = (String) props.get("domain");
    }
    ...
  }

With this component, the deployer can now decide how many, and for which domains a BlobStore service should be registered. This is quite a big step in information hiding with very little work (try doing this in other environments). However, setting these properties is always awkward, to say the least. Adding a Metatype file in the bundle would make the editing easier. Set lets add a Metatype XML file in OSGI-INF/metatypes/com.example.BlobStore.xml:

«metatype:MetaData xmlns:metatype='http://www.osgi.org/xmlns/metatype/v1.1.0'»
  «OCD 
    name='Blob store component config' 
    id='aQute.metatype.aws.BlobStoreComponent' 
    localization='aQute.metatype.aws.BlobStoreComponent$Config'»
    «AD name='Domain' id='domain' cardinality='0' required='true' type='String'/»
    «AD name='Secret key *' id='.secretKey' cardinality='0' required='true' type='String'/»
    «AD name='Access key *' id='.accessKey' cardinality='0' required='true' type='String'/»
    «AD name='Region' id='region' cardinality='0' required='true' type='String'»
      «Option label='US standard' value='US_Standard'/»
      «Option label='US west' value='US_West'/»
      «Option label='EU ireland' value='EU_Ireland'/»
      «Option label='AP singapore' value='AP_Singapore'/»
    «/AD»
  «/OCD»
  «Designate pid='aQute.metatype.aws.BlobStoreComponent'»
    «Object ocdref='aQute.metatype.aws.BlobStoreComponent'/»
  «/Designate»
«/metatype:MetaData»

This gives us a decent GUI on the webconsole:

Unfortunately, to get this GUI it looks like we're back in XML hell? Nope! bnd comes to the rescue! In the latest release 1.42 there is really nice support for create the Metatypes from a Java interface, using optional annotations to provide additional information. The previous GUI was created automatically from the following interface:

interface Config {
   String domain();
   String _secretKey();
   String _accessKey();
   Region region();
 };

The title is derived from the configuration interface name and the property key labels come from the method names, it uses the camel case and characters like $ and _ to turn them into something more pleasant to read for the labels. The _ in front of secretKey and accessKey indicate private properties, they will not be registered as a service property. Notice that he Region, which is an Amazon enum, is used to create a popup list with readable labels and the exact names of the enum. bnd will automatically create this for you. So what do you have to do to make this all work?

@Component(designate=BlobStoreComponent.Config.class,immediate=true)
 public class BlobStoreComponent implements Store {
  interface Config {
    String domain();
    String _secretKey();
    String _accessKey();
    Region region();
  };
  Config config;
  AmazonS3Client client;
 
  @Activate
  void activate(Map map) {
    config = Configurable.createConfigurable(Config.class, map);
    AWSCredentials credentials = new BasicAWSCredentials(
       config._accessKey(), config._secretKey());
    client = new AmazonS3Client(credentials);
    client.createBucket(config.domain(),config.region());
  }

  public InputStream get(String name) {
    S3Object obj = client.getObject(config.domain(), name);
    return obj.getObjectContent();
  }

  public void put(String name, InputStream input) {
    client.putObject(config.domain(), name, input, null);
  } 
 }

This is all you have code ... No property handling, not need to check for null properties (by default the fields are required), not mucking around deep in XML, all type safe ... The same package that contains the optional  annotations contains a tiny little class that creates a proxy that maps the methods to the property and performs type conversion if needed.

If you want to experience OSGi heaven (or at least the road towards OSGi heaven), download the alpha version of bndtools and play with it. This code and other samples are provided so you can directly use them with bndtools. You can find  this code at an aQute github repository.The Metatype and Components chapter of the bnd manual define the details.

For me, the metatype support is fixing a crucial extra step to take advantage of OSGi. I am looking forward to make many examples in the future that take advantage of the inredible power of metatype + configuration + components. For ant lovers, the latest version is available from the download page. For maven, this will require some collaboration with the maven bundle guys but I will work on this. Enjoy, and hope to see you next week at OSGi Devcon/EclipseCon!

Peter Kriens

PS. The hackathon (or hackaton as I erroneously called it) is on Thursday morning but I do not have the room yet. If you're coming send me a mail and I'll keep you posted.

Modularity is Hard, lets do a Jigsaw?

Reply to an interesting blog at DZone from Martijn Verburg about modularity, OSGi, and Jigsaw. The blog was about the eternal discussion of using the package as the atom of dependency or the JAR. So one more time.

After putting up with the argument of package versus JAR as dependency point I've noticed a pattern in people. Initially the proponents of the Jigsaw/maven model of JAR dependencies can only indignantly come up with one argument: it is simpler. We actually added Require-Bundle under protest for Eclipse, which actually models most of the Jigsaw/maven view of the world. However, once people start to use OSGi they discover that the model is not simple, it is simplistic. Yes, if you make a "hello world" Require Bundle might be simpler, but when you have to maintain a 400.000 line code base over many years you quickly discover why it is not simple but simplistic. I've not met an experienced OSGi user that argues for Require-Bundle, and I am pretty sure that Eclipse would not have pressed for Require-Bundle if they had known what they know now.

Having been on the OSGi side for more than ten years I came to compare it to plumbing. On the OSGi side the plumbing is done well and we got rid of the smell but when I visit the other side I cannot be but amazed at how messy and smelly life is there, like plumbing in the medieaval times. Though there is a lot of amazing functionality out there, invariably when you analyze these wonderful applications and libraries you find hundreds to thousands of type references that are impossible to satisfy in run time. Ticking bombs waiting to hit you when they cause the most harm. Versioning is absent, it is a mess, or it is not very useful at all. Beautiful castles but built on quick sand.

The tragedy of OSGi is that the model puts a lot of these hidden problems up front in your face of letting them explode at the customer's (always wondered if this is the reason our industries invests so much in logging). Most open source libraries never worry about their dependencies and drag in transitively many megabytes of unneeded code. Hey, the only time you notice this is when maven starts downloading the Internet and that is only once due to caching. In OSGi you have to handle the dependencies up front, without OSGi you can put your head in the sand and "prove" that it works by running it for some time without a Class Not Found Exception. If people build bridges like the average WAR I probably would buy a boat.

So yes, OSGi has a threshold that is not easy to cross, but there is nothing tooling cannot do. Afterall, we have a compiler that handles the byte codes for us, in the same vein tools can remove most of the additional metadata for OSGi. Fortunately, the tooling is improving, take a look at bndtools, which is supposed to integrate with Apache Sigil soon. This is an Eclipse plugin that works very well inside Eclipse but also provides a small ant plugin that can build workspaces in a headless build, providing identical results inside and outside Eclipse. I also know IBM is investing heavily in OSGi tooling for Websphere. There is of course Eclipse PDE and a derivative of PDE with SpringSource but these tooling are not very oriented to package dependencies, hope they will change too.

So I challenge anyone to argue why the Jigsaw/maven's model is technically superior to OSGi's package model. So the question is: do we want to move the Java industry forward by picking the technically superior model or do we keep  building on quicksand?

Peter Kriens

OSGi's Role

With the increased adoption of OSGi the issue of when to use the OSGi API pops up more and more often. One misconception, popularized with Dependency Injection, is that NO code should touch the OSGi API.

The reason code should not touch a specific API is cohesion. If you write a program to control the brakes of a car you'd likely not want to include code to optimize fuel consumption. Cohesion is about keeping focus in your module; the more concerns get mixed, the less cohesive the module gets. Low cohesion modules are bad because they are more complicated to maintain, which translates to extra cost, and they are less usable in another model because now the module requires both the brake semantics as well as the fuel semantics to be applicable for any new model. The less cohesive, the smaller the chance all the domains match the new usage area for the module.

So it is very true that you do not want to mix OSGi API with your shopping cart code for an ecommerce site, these are different domains. The quest for high cohesion forbids mixing these domains.

However (you knew this was coming), there are many cases where the application infrastructure is the domain. Looking at open source you find that (often too) large swaths of code are not related to some application domain but they are about the infrastructure of the application, or said differently, the plumbing. Application plumbing can be very beneficial; it is all about reducing application domain code. Dynamic class loading, annotation processing, reflection, and many other techniques are all used to reduce the amount of application code with plumbing code. Clever plumbing code is reusable so over several systems the total complexity will be much less.

Application plumbing is exactly the domain of OSGi.

So once you start using class loaders or play with Class.forName realize that you are acting as an application plumber. Whatever you're doing, once your code uses a class loader your no longer in Kansas. If you have to use Class.forName and class loaders you're like a plumber in the medieval ages. You might be a craftsman but the environment gives you very little support so you're largely on your own, devising your own tricks. There might be some common patterns you picked up from your local guild but there are no standards in the Java VM.

Once you realize you're into application plumbing you should realize that you're right at the heart of OSGi's application domain. In all those cases the OSGi API is perfectly suitable to use and gives you much cleaner and reusable solutions than continuing to abuse the Java APIs in this areas that were never intended to be used for application plumbing.

So to conclude that one should never use OSGi APIs is misunderstanding the cohesion issue; once you do application plumbing it is much more advantageous to use the OSGi API than any alternative route. The OSGi gives you a comprehensive framework for application plumbing that is unmatched in the software world.

Peter Kriens

Exception Hygiene

Arguably the worst decision in Java was to have checked exceptions. I've never been thrilled by Java as a language (after Smalltalk all other languages seem, well, just not something to get excited about) but checked exceptions seem to get to me every time. I just had an another bad experience with this exceptionally bad idea.

I recently had to work on some open source code, the code was about a specific servlet. After working around some of the limitations I decide to just fork it. The servlet was not working very reliable and I could not really pinpoint where the problem was. So I decided to just remove all low level exception handling and handle all exceptions in the service method of the servlet. The authors had done the traditional way. This is making APIs without general throw clauses so you have to catch all the bad stuff and then turn it into some specific exception. It was amazing how readable the code became, and, even better how easy it was now to diagnose because anything that went wrong always ended up in the catch block of the service method. Easy to set break points, and easy to handle. The other improvement was that I now could get rid of all of the messy logging code that also cluttered the code.  Virtually all code was logging exceptions and this logging could now be done in one place. Removing checked exceptions this way is imho the cheapest and most effective way to improve your code.

So how do I handle exceptions? Well, for me a function all has two exits: a normal return and an exception. I do not believe exception types matter, only badly designed APIs where exceptions are abused for normal behavior require their types. By having this simplified model, any API can throw any exception and I usually declare "throws Exception" on my API methods so I do not have to catch any lower level exceptions. This model makes it easy for an exception to bubble up to the top level method that knows what to do with an exception. Obviously intermediate functions must use the finally block to ensure that any any resources are properly closed.

For the OSGi APIs we've not followed this model because lots of people still need to get used to ignoring checked exceptions. However, if I see how far we've come since the early days then I think we can one day expect this style to be common.

Peter Kriens