Wednesday, 30 October 2013

Felix GoGo inspect command (OSGi R4.3)

I don't really know why I was not able to find a more prominent location on the web for the details of the Apache Felix inspect command in an OSGi shell, but at least I found something:

We've got the mailing list and a corresponding issue, from which I want to summarize the details in this post.

In the Felix gogo command bundle version 0.12.0 the inspect shell command was changed to the following signature:

inspect ('capability' | 'requirement') <namespace> [<bundles>]

Before OSGi R4.3 the namespace was one of  bundle, package, host and service, which now changed to one of  
  • osgi.wiring.bundle
  • osgi.wiring.package
  • osgi.wiring.host and 
  • service

"capability" and "requirement" can be abbreviated with "cap" and "req" respectively, furthermore you can use wildcards for the namespace.

Let' give some examples:

In an OSGi shell, executing a command like

  inspect cap service <bundleId>

might give you something like

The output gives you all the details about the service capabilities of the referenced bundle.

  inspect req service <bundleId>

on the contrary, lists all the service requirements:

What about the other namespaces?

Let's try

  inspect cap osgi.wiring.package <bundleId>

This is the list of all the provided packages of that bundle which comes in handy when trying to understand the package relations if a bundle doesn't want to resolve.

A last tip:

In the gogo shell you can grep the output like this

  inspect cap * 54 | grep pid

This will query all the capabilities of bundle 54 and then grep for the string "pid".

Tuesday, 29 October 2013

Debugging OSGi services

This post is a collection of tips of how to "debug" into OSGi services, grouped by the providers I am using. I will keep updating this whenever I find something new.

Apache Felix Declarative Services

Setup:

Active     |    5|Apache Felix Log Service (1.0.1)
Active     |    5|Apache Felix Declarative Services (1.6.2)
Active     |    5|Apache Felix EventAdmin (1.3.2)
Active     |    3|Apache Felix Configuration Admin Service (1.4.0)
Active     |    3|Apache Felix File Install (3.2.4)
Active     |    1|Apache Felix Gogo Command (0.12.0)
Active     |    1|Apache Felix Gogo Runtime (0.10.0)
Active     |    1|Apache Felix Gogo Shell (0.10.0)

Hint: I didn't get the scr shell commands with Declarative Services 1.6.0. Also, not all of the listed bundles might be necessary, this is just my setup.

scr:list will give you something like this:

[   1] [active       ] de.twenty11.skysail.server.config.ServerConfiguration
[   4] [active       ] de.twenty11.skysail.server.webapp.internal.WebappApplication
[   3] [active       ] de.twenty11.skysail.server.internal.Events
[   0] [active       ] de.twenty11.skysail.common.config.ConfigurationProvider
[   2] [active       ] de.twenty11.skysail.server.internal.Configuration


Now pick the id of the component you are interested in and type, for example,

scr:info 2

You will get all the details of the component, together with the information if all the requirements are satisfied (so that the component is actually active):

(...)
Reference: ApplicationProvider
    Satisfied: satisfied
    Service Name: de.twenty11.skysail.server.services.ApplicationProvider
    Multiple: multiple
    Optional: optional
    Policy: dynamic
    Policy option: reluctant
    Bound to:        [de.twenty11.skysail.server.services.ApplicationProvider]
        [de.twenty11.skysail.server.services.ApplicationProvider]
        [de.twenty11.skysail.server.services.ApplicationProvider]
        [de.twenty11.skysail.server.services.ApplicationProvider]
        [de.twenty11.skysail.server.services.ApplicationProvider]
Reference: MenuProvider
    Satisfied: satisfied
    Service Name: de.twenty11.skysail.server.services.MenuProvider
    Multiple: multiple
    Optional: optional
    Policy: dynamic
    Policy option: reluctant
    Bound to:        [de.twenty11.skysail.server.services.MenuProvider]
        [de.twenty11.skysail.server.services.MenuProvider]


help, as always, gives you the available commands:

scr:config
scr:disable
scr:enable
scr:info
scr:list

Reference: Felix Declarative Services Documentation

Sunday, 20 October 2013

converting an ordinary jar into an OSGi bundle (with maven and bnd)

Sooner or later, when dealing with OSGi, you'll find the need to utilize a third-party library which - unfortunately - was not written with OSGi in mind.

Depending on what exactly this library does, it might not be easy to convert it into an OSGi bundle. For example, if it depends a lot on Class.forName(...) constructs, it might be better to look for an alternative implementation, if that exists. Or, if that library depends heavily on further libraries and jars, you might have to convert all of those into OSGi bundles themselves, transitively... which is no fun, especially as you will not know if it will work at all until the end.

Having said that, sometimes it can be easy. A well-written library with low dependency profile, not relying on some fancy class-finding tricks can be converted into an OSGi bundle very easily.

For the following to work, I assume you are using maven.

For our example, I will pick a library I am using myself, which is not OSGi-compatible by default, stringtemplate. You can download the stringtemplate jar, and a quick look at its MANIFEST.MF files content will show you that it is not an OSGi bundle. In fact, with a manifest file not bigger that 122 bytes, you don't even need to open that file to know that you are not dealing with an OSGi bundle.

A simple pom.xml, like the one below, together with a minimal instruction file, will convert the referenced library into an OSGi bundle.

Please note, that the second file, osgi.bnd is referenced in the first one with a leading minus "-" sign.

Update: It seems like the pom setup does not work with the newest version of maven-bundle-plugin (2.4.0), you have to use 2.3.7 to make it work. I was not able yet to figure out why this happens. Thanks to Thomas Newman for the feedback!

Running "mvn clean install" now will create an OSGi bundle that you can deploy to a repository and use in your OSGi framework. Depending on how you use the library, you might have to tweak the contents of the osgi.bnd file to adjust the bundles requirements and capabilities to your context. After all, the original jar version of the library never dealt with OSGi-related concepts, so there might be some work left for you.

From my personal experience I have to add that I was using this approach quite often when starting using OSGi - I was tempted to use a lot of code which was not OSGi-aware. Over the years, for some reason, this need to utilize something from outside the OSGi world became less and less. I guess that, by now, many libraries became OSGi-aware (which is great), and, that - if you look for it - you will find OSGi-compatibly alternatives to many of your needs.

References:

  1. bnd - the tool behind the magic
  2. maven-bundle-plugin - the tool making bnd work inside maven
  3. example project on github - check out the code yourself and try it.

Thursday, 17 October 2013

skysail notes project

[originally published in skysail notes blog 29/9/2013; now moved to its parent blog]

One thing everybody seems to need is to handle notes.

What's in a note? Well, some text. And that's it - you make a note, and when you want to remember what's in that note, you search it, you find it, you read it, maybe  you act on it. Maybe you change it, and it starts all over.

Doesn't seem like a hard thing to do... I mean to create a program for.

Let's see... Unless you physically write a note and stick it to your refrigerator I mean, you will write it on your computer using some application. The question is, from where will your note be available in the future, after initial writing?

From your local machine only? The one you are sitting at right now, maybe? The one the hard drive of which will maybe fail in a couple of months? Well, maybe, why not, if the notes contents are not particularly valuable, why not. If you loose a recipe, the cell number of an old friend, maybe a license key, probably not much harm done, things can be restored or information regained somehow.

Of course, there's your fridge, your local PC or laptop, and there's "the cloud" (aka the internet).

So why not use one of the many services available to store your notes online (let's use "your notes" as a synonym for "your data" for now). Great, you get an account (easy!), you get started (easy again), you create your first notes (eas...), and, you can access it from everywhere, that's a big difference! You can even share your notes with someone if you want to! Your provider (hopefully) will care for backups, so you don't have to worry at all.

Your fridge is online, gets backuped, and you can share it, great.

But it is a potentially public fridge now. Your provider knows what's stuck on it, the NSA knows too (they seem to care), and if something goes wrong, somebody else might get access to it - or just see it, if you yourself make a mistake.

Ok, it's still the recipe, the cell number of your old friend, a couple of license keys, and, wait, some ideas about a new patent, the bank account number you don't really what your wife to know about, and that doctors number who dealt with something the insurance is not supposed to know about.

Hmm... Huston, we got a conflict.

What I am aiming at is, that people trade convenience over security. They will always, it seems. The better the offer is, the less resistance there will be.

And what about notes? After all, this here is only about notes ;)

The thing is not to pass everything to the big players, host the software yourself. Get somebody hosting it for you. Get some decent trusted open-source software and install it on your own server. It's not that hard. There are people willing to help you with that. Cryptography without back doors can be applied, it can be save. It's not even expansive. It's just a little little bit less convenient than the obvious alternatives.

Your fridge will be online, backuped, and ready to share with people you trust.

It's still your fridge, it's still your notes, - it's still your data.

It's just a little bit less convenient, sorry.

And there are some open source projects trying to achieve the things I just described, like skysail notes (the name you read in the title).

We are working on it (but already, there are solutions, you might have to search for them).


 




Sunday, 6 October 2013

launching skysail server website

Now, after my initial post yesterday, the coming out of skysail, I am ready to publish the location of the skysail.server website ;)

http://skysail.server.twentyeleven.de



Being based on OSGi, there will be quite a few "landing pages" for skysail, one for each bundle. These pages will describe the technical aspects of skysail are are meant for developers. Once I have the first products running (based on skysail) I'll have to start with end-user documentation as well, but this might take a while.

For now, for those interested, you can check out the overview pages, that is the
10.000 and 1.000 feet view, and the pages about Routing and Resources, business logic execution and SkysailResponses.


Saturday, 5 October 2013

the coming out of skysail

I've been playing with this little pet project of mine for quite a while now. I did learn a lot, mainly by making a huge number of mistakes ;)

By now, things start becoming a little bit more stable (well, we're still in pre-alpha to be honest). Nevertheless, I started with some documentation and I am ready to share my ideas, hoping for feedback.

The coming out of skysail


For starters, I want to provide a 10.000 feet view of skysail:




Looks like the typical input-process-output chain - sure, it's IT after all ;)

So, what's special about this? First of all, the skysail server deals with RESTful requests only (please note that this is not about restful web services). What seems like a restriction really adds value, as explained later.

The request will get processed (skysail will take care of authentication, authorization, logging, persistence and the like in a generic way) and return a response.

This response is a representation of the answer to that request. The specific format of the answer (that is, the response representation) depends on the request itself - asking for a JSON-formatted response will give you a JSON string. This powerful feature is build into the http protocol itself, called content negotiation.

An example

Let's assume you have a skysail server installation at myserver.org, running on port 8080, and this installation provides a RESTful "notes" application, i.e. the following paths are mapped to resources dealing with the following requests:

 /notes          -> mapped to NotesResource
 /notes/{noteId} -> mapped to NoteResource

Now, by typing http://myserver.org:8080/notes/27 in your browser, what you do is to initiate a GET request to that URL, which is dealt with by your skysail installation and mapped to the second resource, NoteResource.

NoteResource reacts to the request according to the business logic defined in the notes application. Typically, assuming you've been authenticated and have the proper permissions, the application will get the note with id 27 from its persistence store, format it according to the request, and deliver it:

{
    "message": "Note #27",
    "success": true,
    "data": [
        {
            "pid": 27,
            "parent": null,
            "title" : "myNote",
            "content" : "some content",
            "owner": {
               ...
            },
        }
    ],
}


Please note that skysail server itself is not capable of dealing with notes or any other business entities, this is the task of dedicated OSGi-bundles deployed into skysail server. Using OSGi is the only way to properly deal with all the requirements (in terms of modularization and shared services).

Summary

As described, skysail is a RESTful "business server" focusing on the business logic. This is, IMHO, a reasonable abstraction, as it really separates the representation of entities (the GUI) from the logic performed in the back-end.

Like this, it is very easy to develop various clients (think about a web application, a rich client and multiple mobile apps), all communicating with the same business server. Those clients could be written in any language, too. The only thing they'd have to suport is the HTTP protocol (and understand json).

So, the restriction on dealing with RESTful requests only gives you a chance to really decouple clients and server and provide the most generic interface, using the standard HTTP methods like GET, POST, PUT and DELETE.