Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Using Vaadin with Karaf

Apache Karaf is based on OSGi and provides a lightweight container within which various components and applications can be deployed. It provides some enterprise-ready features, such as shell console, remote access, hot deployment, and dynamic configuration.

The Karaf http feature along with the war feature provides an implementation of HTTP Whiteboard, which is the standard in Karaf in practice. This implementation is known as Pax Web (see HTTP feature details here). Pax Web isn’t fully compliant with the HTTP Whiteboard OSGi Compendium 7 specification. ServletContextListener support has some issues. Because of these issues, the recommended way of registering VaadinServlet, described in the generic Using Vaadin with OSGi tutorial, doesn’t work in Pax Web.

Still, it’s possible to use Vaadin OSGi support with Pax Web. But the OSGiVaadinServlet should be used as a base class for the servlet which is registered in an OSGi bundle:

@org.osgi.service.component.annotations.Component(service = Servlet.class)
@HttpWhiteboardServletAsyncSupported
@HttpWhiteboardServletPattern("/*")
public class FixedVaadinServlet extends OSGiVaadinServlet {

    @Override
    protected void servletInitialized() throws ServletException {
        getService().setClassLoader(getClass().getClassLoader());
    }

}

Refer to the generic Using Vaadin with OSGi and Using Services With Vaadin tutorials for other non-Karaf-specific Vaadin OSGi documentation.

Karaf Base Starter

A Karaf base starter project is available at https://github.com/vaadin/base-starter-flow-karaf.

The project may be used as a basis for a custom OSGi Vaadin web bundle project. The README contains information on how to run Karaf, install all the required Karaf features, and install project features to an existing Karaf container.

The base project generated feature Maven artifact classifier contains all the dependencies for the project and can be used as a basis for a custom project "feature". A few Karaf features are already provided by Vaadin (see below).

Karaf Features

One of the most important questions that needs to be addressed when an OSGi bundle is deployed to the OSGi container is the resolution of the bundle dependencies. Even if it’s deployed, the bundle doesn’t work in the OSGi container until all its dependencies are resolved. Karaf allows you to solve this via the "feature" concept; bundles can be combined into a "feature" that contains all the dependency bundles and can be installed as one unit.

Vaadin provides several features which can be used depending on requirements:

  • flow-server

  • flow-data

  • flow-osgi

  • flow

  • vaadin-core

  • vaadin

The flow-server feature contains the minimum dependencies that have to be added to any Vaadin web project. The flow-osgi feature contains the necessary dependency for a Vaadin OSGi web bundle. The flow feature combines all Flow bundles altogether and it’s convenient when you use all Flow modules in your project. However, it may be too big for your purposes (some bundles can be excluded from it).

A similar situation arises with vaadin-core and vaadin features; they combine all Flow bundles (including the flow feature) plus all Vaadin components. The first one contains all the free components; the second one includes free and commercial components. These features can be used as they are, if you want to deploy everything to the Karaf container and aren’t concerned with anything else. But it’s also possible to use the features as a base for a custom feature.

The feature can be installed into the Karaf container with two commands:

karaf@root()> feature:repo-add mvn:com.vaadin/flow/$FLOW_VERSION$/xml/features
karaf@root()> feature:install flow

Here, $FLOW_VERSION$ is a placeholder for the Flow artifact version value. The first command uses the feature Maven classifier to add a feature repository (which is an XML file with a feature declaration). The second command installs the feature which is declared in the added repository. Here is an example of the feature repository.

The same can be done with any of the features mentioned.

It might sometimes be useful to install a bundle without a feature. This can be done like this:

karaf@root()> bundle:install mvn:com.vaadin/flow-html-components/$FLOW_VERSION$
karaf@root()> bundle:install mvn:com.vaadin/vaadin-text-field-flow/$TEXT_FIELD_VERSION$

The command refers to the Maven artifact via the com.vaadin group ID, flow-html-components (vaadin-text-field-flow) artifact ID and the artifact version.

ECA1725D-4D2C-478D-B919-0527C91BC49C