What is it good for

It's supposed to help people run their Vaadin Applications easily in a OSGi Environment without the need for special Compendium Services.
Just plain OSGi

How does it work

Just some OSGi-Black magic for tracking bundles.
A tracker watches for bundles importing com.vaadin and providing the Manifest header Vaadin-Application or watches for bundles registering Vaadin Applications via the com.vaadin.Application interface.
This tracker does also look for custom themes.

Registering a Vaadin Application

The Application is retrieved from the Vaadin-Application Manifest Header.
This Application class is instantiated and added to a new instance of the VaadinApplicationServlet
which is registered via the Http-Whiteboard extender. As alias the Vaadin-Alias Manifest Header is used.

Registering a Vaadin Application provided as OSGi service

The Application is provided as an OSGi service registering the com.vaadin.Application interface.
This Application class is instantiated and as alias the service property alias is used.

The tracker also registers the bundle to the VaadinResourceServlet, if the bundle contains resources in the /VAADIN/ folder
This Servlet registers itself for the std. /VAADIN/* context.

Registering a Vaadin theme

The Extender searches for the Vaadin resource directory. If found the bundle containing the
theme is registered to the VaadinResourceServlet.
This Servlet registers itself for the std. /VAADIN/* context.

So there is still some specialties needed?

Yes indeed, but just two.

Declaring the application

Application registered via Manifest-Header

Add a OSGi Manifest header to your Manifest called: Vaadin-Application
With this header you declare the Application instance to use.
Almost just like adding this property to the web.xml in a std. Vaadin War.

Vaadin-Application: org.pax.vaadin.samples.simple.app.MyVaadinApplication

Application registered via OSGi service

Publish a OSGi service using the com.vaadin.Application interface. The tracker will
instantiate the application for you using the alias provided via the service property alias.

In the following sample the service is published via Blueprint:

<service ref="vaadinApplicationBean" interface="com.vaadin.Application">
    <service-properties>
        <entry key="alias" value="/SampleVaadin" />
    </service-properties>
</service>

Declaring the alias

Application registered via Manifest-Header

To address your application you still need a alias to retrieve it,
therefore another header for declaring the web-context is needed: Vaadin-Alias

Vaadin-Alias: /SampleVaadin

Application registered via OSGi service

To address your application you still need a alias to retrieve it,
therefore the service property is needed: alias

In the following sample the service is published via Blueprint:

<service ref="vaadinApplicationBean" interface="com.vaadin.Application">
    <service-properties>
        <entry key="alias" value="/SampleVaadin" />
    </service-properties>
</service>

External dependencies?

Yes, Pax Web is needed and the Whiteboard extender and of course a Vaadin Bundle is also needed.
If a GWT like presentation is wanted a GWT bundle is also needed.
Take a look at the samples, especially the color picker on how to integrate GWT Presentations.

Usage with Apache Karaf

So how do you use it with Apache Karaf. Since there is also a features.xml available for easy deployment
you should use it.

First install a valid vaadin bundle:

install -s mvn:com.vaadin/vaadin/6.7.8

Second add the features.xml to the features repositories

features:addurl mvn:org.ops4j.pax.vaadin/feature/0.1.0-SNAPSHOT/xml/features

Now install the Pax for Vaadin service

features:install -c service

This is already it.

Now for testing purposes you might also try to install the provided sample for testing.
You might skip the Service and Vaadin Installation from the beginning, cause those are installed right away through this sample Feature.

features:install -c ColorPicker

Call the application from http://localhost:8181/ColorPicker

Other examples can be deployed in Apache Karaf using the following commands :

features:install SimpleApplication
features:install SimpleBlueprintApplication
features:install SimpleAddressBook
features:install Sampler

To play with them, simply call http://localhost:8181/SimpleApplication or SimpleBlueprintApplication or SimpleAddressBook or Sampler

Any Samples

There are sampels available in the sources.
For example here: https://github.com/ops4j/org.ops4j.pax.vaadin/tree/master/samples