Vaadin OSGi Support

Minimal Vaadin Project For OSGi
Publishing a Servlet With OSGi
Publishing Static Resources With OSGi
Deployment to OSGi container.

Vaadin applications can be deployed on an OSGi compatible servlet container, or on Liferay 7 as OSGi portlets.

An OSGi application typically consists of multiple bundles that can be deployed separately. Multiple versions of each bundle can be present, and the OSGi runtime resolves their dependencies at run-time based on bundle manifests.

To deploy Vaadin applications as OSGi bundles, static resources (including themes and widget sets) must be published using the appropriate APIs to enable using multiple Vaadin versions on the same server.

The application is typically packaged as a JAR file, and needs to have a valid OSGi bundle manifest which can be created e.g. by the bnd-maven-plugin. All the dependencies of the application should be available as OSGi bundles.

Minimal Vaadin Project For OSGi

Vaadin application for OSGi should be a valid bundle, i.e. it should be packaged as a .jar file, and it should have a proper OSGi manifest inside. The easiest way to convert regular maven-based Vaadin application into a valid OSGi bundle consists of five steps:

Change packaging type to jar in your pom.xml:

    <packaging>jar</packaging>

Change the scope for all vaadin dependencies from default to provided, like this:

        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-server</artifactId>
            <scope>provided</scope>
        </dependency>

Add OSGi-related dependencies to the project

        <groupId>com.vaadin</groupId>
            <artifactId>vaadin-osgi-integration</artifactId>
            <version>8.1.0.beta1</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>osgi.core</artifactId>
            <version>6.0.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>osgi.annotation</artifactId>
            <version>6.0.1</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.osgi</groupId>
            <artifactId>osgi.cmpn</artifactId>
            <version>6.0.0</version>
            <scope>provided</scope>
        </dependency>

Setup necessary plugins for building the project:

 <build>
        <plugins>
            <plugin>
                <groupId>biz.aQute.bnd</groupId>
                <artifactId>bnd-maven-plugin</artifactId>
                <version>3.3.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>bnd-process</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.0.2</version>
                <configuration>
                    <archive>
                        <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
                    </archive>
                </configuration>
            </plugin>
            ...
        </plugins>
    </build>

Add bundle script (bnd.bnd) into the project root folder:

Bundle-Name: ${project.name}
Bundle-Version: ${project.version}
Bundle-SymbolicName: ${project.groupId}.${project.artifactId}
Export-Package: com.example.osgi.myapplication
Import-Package: *
Web-ContentPath: /myapp

Publishing a Servlet With OSGi

To deploy the app as a servlet all we need to do is annotate the MyUIServlet class with @Component(service = VaadinServlet.class). The Vaadin integration will track this registration and use HttpWhiteboard specification to register a servlet with the location of the Vaadin resources properly configured. This means that the user can specify a set of HttpWhiteboard properties in the @Component declaration.

The @WebServlet annotation settings will be used to configure the urlPatterns and async parameters.

import org.osgi.service.component.annotations.Component;
...
@Component(service = VaadinServlet.class)
@WebServlet(urlPatterns = "/*", name = "MyUIServlet", asyncSupported = true)
@VaadinServletConfiguration(ui = MyUI.class, productionMode = false)
public static class MyUIServlet extends VaadinServlet {
}

Publishing Static Resources With OSGi

Vaadin Framework 8.1 and later versions provide two supported ways of publishing static resources for OSGi: by making OSGi services implementing an interface or by explicit calls to a service.

The easiest way to publish a theme or a widgetset is to create a class implementing the interface OsgiVaadinTheme or OsgiVaadinWidgetset and annotating it with @Component to make it an OSGi service. This automatically publishes the theme or the widget set from the bundle at a path that contains the Vaadin Framework version used by the application.

@Component
public class MyTheme extends ValoTheme implements OsgiVaadinTheme {
    public static final String THEME_NAME = "mytheme";

    @Override
    public String getName() {
        return THEME_NAME;
    }

}

Alternatively, an OSGi bundle activator or an SCR Component @Activate method can obtain an instance of VaadinResourceService from OsgiVaadinResources and explicitly call its methods to publish a theme, a widget set or an individual file in the bundle as a static resource at the correct path.

  VaadinResourceService service = OsgiVaadinResources.getService();
  service.publishTheme("mytheme", httpService);

In addition to these approaches, it is also possible to repackage all the static resources of an application to a single bundle and export the /VAADIN directory. This can be useful e.g. when migrating an old Vaadin OSGi application in an environment that does not support parallel deployments of multiple versions of the application.

Deployment to OSGi container.

In order to have your application running under OSGi container, you need to have Vaadin framework bundles deployed, and then the application bundle can be deployed and started. Here is a list of required Vaadin bundles, in order of loading:

jsoup-1.8.3.jar
gentyref-1.2.0.vaadin1.jar
vaadin-shared-8.1.x.jar
vaadin-server-8.1.x.jar-8.1.x.jar
vaadin-osgi-integration-8.1.x.jar
vaadin-client-compiled-8.1.x.jar (not required, if your project uses its own widgetset)
vaadin-themes-8.1.x.jar

And here is a complete script to have Vaadin application up and running using Apache Karaf 4.0.8 console:

feature:install http
feature:install http-whiteboard
bundle:install -s mvn:org.jsoup/jsoup/1.8.3
bundle:install -s mvn:com.vaadin.external/gentyref/1.2.0.vaadin1
bundle:install -s mvn:com.vaadin/vaadin-shared/8.1.0
bundle:install -s mvn:com.vaadin/vaadin-server/8.1.0
bundle:install -s mvn:com.vaadin/vaadin-osgi-integration/8.1.0
bundle:install -s mvn:com.vaadin/vaadin-client-compiled/8.1.0
bundle:install -s mvn:com.vaadin/vaadin-themes/8.1.0
bundle:install -s file:path-to-the-application.jar

Docs