vaadin-framework/documentation/advanced/advanced-osgi.asciidoc

---
title: Vaadin OSGi Support
order: 19
layout: page
---

[[advanced.osgi]]
= Vaadin OSGi Support

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.

[[advanced.osgi.servlet.maven]]
== 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`:

[source, xml]
----
    <packaging>jar</packaging>
----
* Change the scope for all vaadin dependencies from default to `provided`, like this:

[source, xml]
----
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-server</artifactId>
            <scope>provided</scope>
        </dependency>
----
* Add OSGi-related dependencies to the project

[source, xml]
----
        <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:

[source, xml]
----
 <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:

[source, text]
----
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
----

[[advanced.osgi.servlet]]
== Publishing a Servlet With OSGi

To deploy the app as a servlet all we need to do is annotate the [classname]#MyUIServlet# class with [literal]#@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 [interfacename]#@Component# declaration.

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

[source, java]
----
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 {
}
----


[[advanced.osgi.resources]]
== 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 [interfacename]#OsgiVaadinTheme# or [interfacename]#OsgiVaadinWidgetset# and annotating it with [interfacename]#@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.

[source, java]
----
@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 [interfacename]#@Activate# method can obtain an instance of [classname]#VaadinResourceService# from [classname]#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.

[source, java]
----
  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 [filename]#/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.

[[advanced.osgi.deploy]]
== 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 link:https://karaf.apache.org/[Apache Karaf 4.0.8] console:

[source]
----
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
----