Hot deploy WAR files in OSGi

These days I was looking for a simple way of deploying WAR files into OSGi. Something similar to a JEE servlet container does: I put the WAR file into a directory and it gets automatically deployed. Well, I could not find such a thing, which was easy enough to use (and do not tell me to take Spring dm Server or IBM WAS 7 Alpha something ).

So, what next? Only one option, build my own tools for such a thing. After all, how hard it could be?

I took Pax Runner to start it up easy, and provision via profiles Pax Web for WAR support (inspiration of OSGi Alliance RFC-66) and Felix File Install for hot deployment of files in a directory. Of course that was not enough as in its raw form File Install will not deploy a WAR file since it is not an OSGi bundle. It had to be first transformed. I already have a tool to transform WAR files to OSGi bundles in the form of Pax Url WAR handler (another inspiration of OSGi Alliance RFC-66), what was missing was “something” to ask me to transform the WAR to its OSGi form. Lucky me! File Install is extensible in latest versions by transformers like the one I needed. Took me 15 minutes to put in place a new Pax Web module (Pax Web Deployer), implement the transformer, build it and start it up using Pax Runner. Then I copied Sonatype Nexus WAR into the watched directory and there it was: Nexus running under OSGi. Deleted the WAR, Nexus got uninstalled. Sweet!

Want to try it out?

• install Pax Runner (note that using Pax Runner is just for convenience. What you need to get this working are just the bundles included in Pax Runner profiles and the new Pax Web Deployer)
• start the osgi framework with the following command line:

  pax-run war config felix.fileinstall url mvn:org.ops4j.pax.web/pax-web-deployer/0.7.3-SNAPSHOT --repositories=+http://repository.ops4j.org/mvn-snapshots/@snapshots
  

• ensure that all the bundles are started
• copy your WAR into “runner/load” directory under the directory from where you started .
• watch the console to see your WAR getting deployed
• have fun with it

Pax Runner is in da cloud

Checkout the excellent post of Jeroen van Grondelle about running OSGi in a public cloud service via Pax Runner.

Pax Runner 1.3.0 Released

Pax Runner 1.3.0 is out. This release is mainly focusing on adding support for latest version of Felix (2.0.1) and Equinox (3.5.1). Beside this I added support for Equinox 3.6 (m2) and upgraded Knopflerfish support for 3.0 to use beta 2. Take a look at release notes for details.

With this occasion I also brought the Eclipse Update site up to date, so now, it includes Pax Runner Eclipse Plugin 1.3.0. The update site url is: http://www.ops4j.org/pax/eclipse/update/

The wait is over: Pax Runner is released

It took about three months from the last release but finally I put out a new release of Pax Runner. The wait was mainly to my busy schedule working for Sonatype but also because I was waiting for OSGi Alliance to release 4.2.

Now, why should I wait for release 4.2? Because in this version we included Apache Felix 2.0 (see bellow) and this is the first version of Felix implementing the 4.2 specs. And since Pax Runner was always provisioning automatically the OSGi Alliance Compendium bundle corresponding to the version of specs implemented by targeted framework. And this brings us to the first noteworthy fact in Pax Runner 1.2.0:

Provision the OSGi Alliance of your need

Why should Pax Runner decide for you what OSGi Alliance compendium bundle you need? Is this one different then any other bundle? No, I would say. The choice of what version to be provisioned or if should be provisioned at all is up to the user, not to the tool. So, from now on Pax Runner does not provision anymore the compendium bundle. But wait a minute. Is now harder to get started? I would say not. Indeed there are some more letters to type but you have the full control:

pax-run compendium // provision latest version of compendium (4.2 for now)
pax-run compendium/4.1 // provision version 4.1 of compendium

But what is this? I do not know this type of provisioning. What it is? It is an alternative way to specify profiles.

Easier way to specify profiles

If you do not know what are Pax Runner profiles you better catch up so can get started faster. Till now you had to specify profiles using the “–profiles” option. Not bad. But why should you type “–profiles” at all? No reason from now on. You just name the profiles you need on the command line. As you see above. In that case the “compendium”  is just a profile as any other. Read more about about …

Support for latest Felix and Knopflerfish

Now back to our man “business”: easy start to OSGi frameworks. In this version we added support for Apache Felix 2.0.0, Makewave Knopflerfish 2.3.2, 2.3.3 and support 3.0.0 beta 1 version.

Chose the shell you like and know

Did you find yourself typing “ps” while in Equinox? Or “ss” while in Felix or Kf? Then you will like the new option “–shell” that will allow you to use the same shell across the frameworks. And Apache Karaf Shell 1.0.0 is around the corner Best I saw till now (extensible, completion, detailed help). Stay tuned.

Assemble (build) directories into bundles

Do you want to use a directory as you bundle packaging format as an alternative to a jar? Use assembly: and Pax Runner.

Faster mvn: urls resolution

In order to determine the download location and version of the artifact to download, “mvn:” protocol has to search across  the configured repositories. This process can be slow, particularly when many repositories are involved. Up to this version we used a set of four repositories to search by default: OPS4J, Maven Central and two SpringSource ones.
So, to make this process faster and with help from Sonatype Nexus we combined the four repositories into just one, a group repository in Nexus words. Beside the faster resolution we can this way also benefit from adding / removing repositories on demand without a need of re-downloading of Pax Runner. But if you liked the old way you can go back by using the new options –useFallbackRepositories (or –ufr).

Bundle validation options

Validate or no the bundles before provisioning, skip the invalid ones,… You choice.

I hope you will enjoy this version. But first you will have to download it.

One more step to feel at home in any OSGi framework

Pax Runner does an excellent job (beside many others ), to abstract you as an user from knowing or learning how to start any OSS OSGi framework implementation. But once you switch the framework, at a price of changing a letter, you find yourself into another shell where the commands you are familiar with, does not work anymore, or those commands have a different meaning. Some of useful ones, like equinox “diag” or “bundle” are not available on other frameworks. This makes me switch the framework when I’m in need just to be able to use them.

So, wouldn’t be useful to have the same shell across the frameworks. Sure, it would. And now we are very close to this goal. For two main reasons: most important: There are shells available over there that work across frameworks such as GoGo from Apache Felix and GShell from Apache Karaf (Apache Felix subproject, formally known as ServiceMix Kernel). Sure, GoGo is not yet very powerful but is just a foundation and I expect that as soon as OSGi Alliance will release the specs for “Command line interface” (known as RFC 147) to see a lot of useful commands out there. In plus, the requirement for this API it does not bring any dependency or imposed interface implementation so many of the services will just contribute commands specific to their service implementation. Till now the “best” shell I’ve seen is the Karaf one and I’m looking forward to its first release.

The second reason why we are closer? Well,  the upcoming release of Pax Runner, 1.2.0 (any day now) has a new option: –shell. The value of this option is the name of the shell (and an optional shell version) as in the following example:

pax-run --shel=gogo

This will start the latest version of GoGo shell (and will disable the standard framework shell) in Felix. You want to start Equinox with the same shell? Simple:

pax-run --shel=gogo --platform=equinox

Same for Knopflerfish.

Want a specific version of that shell?

pax-run --shel=gogo/0.2.0


Want to use another shell? Just create a profile for it (if someone else did not already did it) and you are good to go. For example, if you created a profile named “mcs” (my cool shell) you will just have to:

pax-run --shel=mcs


So, do you feel already at home?

OSGi Alliance artifacts available in Maven Central

Up to a month ago, the available OSGi Alliance jars from Maven Central were quite crappy as they had a strange naming scheme, no one assumed ownership and most annoying was that the jars did not have OSGi metadata in their manifest. More, they were version 1.0. 1.0? What version is that?

The only option you had been to use the artifacts provided by Apache Felix or the other framework implementations or the ones provided by OPS4J community.

Finally the official OSGi Alliance artifacts are now in Maven Central. This is exactly the same artifacts that you could download from OSGi Alliance site, with the right manifest and version. And yes, also the just released version 4.2 is already there

From now on, there is no need of using third party repository to get access to them. For those that already used them from OPS4J repository there is no change in groupId/artifactId.

http://repo1.maven.org/maven2/org/osgi/org.osgi.core/
http://repo1.maven.org/maven2/org/osgi/org.osgi.compendium/


<dependency>
<groupId>org.osgi</groupId>
<artifactId>org.osgi.core</artifactId>
<version>4.2.0</version>
</dependency>

<dependency>
<groupId>org.osgi</groupId>
<artifactId>org.osgi.compendium</artifactId>
<version>4.2.0</version>
</dependency>


And, just one final mention: uploading the files to Maven Central was made possible via Sonatype provided Nexus instance, a facility that you can use for your OSS projects as well.

Tips & Tricks: Simpler way to use profiles with Pax Runner

In the upcoming Pax Runner (1.2.0) I added an alternative way to specify which profiles should be provisioned by Pax Runner. Till now the (only) way to specify a profile was to use “–profiles” option. Not bad, but from now on, there is a better way. Lets see an example where I want to use Pax Web- latest version, Spring Framework – version 2.5.6 and Pax Logging – any version between 1.0 and 2.0 exclusive:

Using “–profiles” you will have to do: pax-run --profiles=web,spring/2.5.6,log/[1.0,2.0)
While using the new method you will do: pax-run web spring/2.5.6 log/[1.0,2.0)

So, you just have to specify them in the command line, separated by space, like any other provisioning url.

Install your build directory as a bundle in Apache Felix

As you may know Apache Felix only supports installing JARs as bundles. But sometimes, as for example during your development, you may want to use the a directory as your bundle packaging format and have Felix allow you to install such a bundle. Usually such a directory is the directory where your sources gets compiled (build directory).

So, if you are in such a need, the new OPS4J Pax URL “assembly:” url handler is for you. Here are the simple ways you can make use of it:

Prepared Apache Felix

First you will need to have Apache Felix installed. I suppose you already have it but if not, follow documentation of Felix site. As I will make use more times of your installation directory, lets name it <felix home>. As for version 1.8.0, after unpacking the distribution files you will get felix-1.8.0 as your <felix home>.

Next you will need the “assembly:” url jar. Download the latest version from project download page or take version 1.1.0 from this direct link. Save the file (or copy afterwards) to <felix home>/bundles directory. As “assembly:” protocol importsConfiguration Admin packages you will have to also install a bundle that has them. You can use Apache Felix Config Admin implementation or just have the OSGi Alliance Compedium API bundle. We will use the former, so download it and save it to <felix home>/bundles (note that Config Admin will become optional starting with next releases of Pax URL).

Next you will have to instruct Felix to load this bundles on start. You do so by changing the configuration file. You will have to edit <felix home>/config/config.properties, look for felix.auto.start.1 and append this lines:

file:bundle/org.osgi.compendium-4.0.1.jar \
file:bundle/pax-url-assembly-1.1.0.jar


Next, start up Felix and you are good to go. Pax URL “assembly:” and “assemblyref:” protocols are now ready to use.

From Apache Felix console

If you do not want to change your Felix setup as abve and just try it out you can achieve the same from Felix console. So, startup Apache Felix and once you are in the console execute the following commands in order to install “assembly:” protocol:

install http://repo1.maven.org/maven2/org/osgi/org.osgi.compendium/4.1.0/org.osgi.compendium-4.1.0.jar
install http://repo1.maven.org/maven2/org/ops4j/pax/url/pax-url-assembly/1.1.0/pax-url-assembly-1.1.0.jar


Pax URL “assembly:” and “assemblyref:” protocols are now ready to use.

Provision via Apache Felix FileInstall

A simple way of provisioning Pax URL “assembly:” protocol is to use FileInstall. If you do not know what is that, find it out from Filippo Diotalevi.
What you will have to do is to copy the two bundles (Pax URL Assembly and OSGi Alliance Compendium) to <felix home>/load (or <felix home>/dropins if you follow Filippo instructions).

Next, start up Felix and, once again, you are good to go. Pax URL “assembly:” and “assemblyref:” protocols are now ready to use.

Provision via Pax Runner

Of course that provisioning this bundles into Felix will be to use Pax Runner. Once you have Pax Runner installed and ready to use, you will not need to download or configure anything. Pax Runner will do that for you with a simple:

pax-run --platform=felix --profiles=url


That’s it. Don’t believe me? Try it out ;). Again you are ready to go with “assembly:” and “assemblyref:” protocols.

Configure java URL protocol handlers

You can transparently make use of Pax URL handlers by configuring Java to discover them. As Felix uses standard Java URL this will also work. But about this maybe some other time in another blog entry.

Using the “assembly” protocols

Now that you have an Apache Felix that knows about “assembly:” and “asemblyref:” protocol you can use them. Lets assume that you have a Maven project somewhere: <my project>. In this case your compiled classes are stored in <my project>/target/classes. What you will have to do to create & instal a bundle containing this classes and any other resource which are in this directory is the following (from Felix console):

install assembly:<my project>/target/classes


That is all. You have now a bundle installed.
I made some assumptions above such as in your build (by using Apache Felix Maven Bundle Plugin or other means), the <my project>/target/classes directory contained an OSGi valid META-INF/MANIFEST.MF. If that is not the case you can make use of Pax URL “wrap:” protocol to automatically generate the OSGi manifest as in:

install wrap:assembly:<my project>/target/classes


If this example of usage is not enough for you there are some much more in the “assembly:” protocol documentation page.

Provision your build directory as an OSGi bundle

During last week I added a new OSGi url handler member to OPS4J Pax URL family.

There are probably numerous use cases when you could use the new  ”assembly” protocol but one stands out:

During development of your projects you usually have the sources on the file system, sources that are compiled by your build system, such as Maven or ANT, or your IDE, and stored somewhere on the file system in a directory. As an example lets take Maven case: the compiled classes are stored under “/target/classes”. If you use an IDE such as IntelliJ IDEA on this Maven project, as soon as sources get changes, they are automatically compiled to the same directory.

Now, what would you want to do is to have the sources of this project, assembled together as bundle and deployed as a bundle in an OSGi framework. To do this you will have to (usually) generate an OSGi bundle (jar) our of this classes and deploy the generated bundle.

But why not directly deploy the directory as a bundle? Because most of OSGi frameworks only supports a jar as deployment artifact. And here is where the “assembly” protocol will shine. Will allow you to do just that: transparently deploy the directory as a bundle on ANY OSGi framework. More then that doing a bundle update will re-generate the bundle content automatically. And all of this with a simple URL like:

assembly:/target/classes

Now, you should not understand from this example that it can be used only with Maven. You can use any directory, include or exclude files you want and much more.

Sounds interesting? Read more about it on Pax URL “assembly” url handler documentation. Do not forget to scroll down to see some tips & tricks.

Cooking with Maven and OSGi

The just released version of Maven Cookbook, contains a new full chapter about doing OSGi development using Maven using OPS4J Pax tools such as Pax Construct and Pax Runner.

In this chapter, we introduce some tools and techniques you can use to start developing OSGi components (or bundles) using Maven. The following recipes focus on the intersection of Apache Felix, the OPS4J project, and the Nexus repository manager as a bridge between Maven repositories and OSGi Bundle repositories. At the end of this chapter, you should have a clear picture of how to start developing OSGi-based applications using Maven.

So, if you just starting doing OSGi development do not hesitate and grab a copy of the free online book.