Appendix B. Using Karaf Maven plugin

The karaf-maven-plugin enables you to create a Karaf server assembly, which is a microservices style packaging of a Karaf container. The finished assembly contains all of the essential components of a Karaf installation (including the contents of the etc/, data/, lib, and system directories), but stripped down to the bare minimum required to run your application.

B.1. Maven dependencies

Maven dependencies in a karaf-assembly project are either feature repositories (classifier features) or kar archives.

  • Feature repositories are installed in the maven structured system/internal repository.
  • Kar archives have their content unpacked on top of the server as well as have the contained feature repositories installed.

Maven dependency scopes

The Maven scope of a dependency determines if its feature repository is listed in the features service configuration file etc/org.apache.karaf.features.cfg (under the featuresRepositories property). These scopes are:

  • compile (default): All the features in the repository (or for a kar archive) will be installed into the startup.properties. The feature repository is not listed in the features service configuration file.
  • runtime: As boot stage in karaf-maven-plugin.
  • Provided: As install stage in karaf-maven-plugin.

B.2. Karaf Maven plugin configuration

The karaf-maven-plugin defines three stages related with Maven scopes. The plugin configuration controls how features are installed using these elements by referring to features from installed feature repositories:

  • Startup stage: etc/startup.properties

    In this stage, startup features, startup profiles, and startup bundles are used to prepare a list of bundles to be included in etc/startup.properties. This will result in the feature bundles being listed in etc/startup.properties at the appropriate start level and the bundles being copied into the system internal repository. You can use feature_name or feature_name/feature_version formats, for example, <startupFeature>foo</startupFeature>.

  • Boot stage: etc/org.apache.karaf.features.cfg

    This stage manages features available in featuresBoot property and repositories in featuresRepositories property. This will result in the feature name added to boot-features in the features service configuration file and all the bundles in the feature copied into the system internal repository. You can use feature_name or feature_name/feature_version formats, for example, <bootFeature>bar</bootFeature>.

  • Install stage:

    This stage installs the artifacts in ${karaf.home}/${karaf.default.repository}. This will result in all the bundles in the feature being installed in the system internal repository. Therefore at runtime the feature may be installed without access to external repositories. You can use feature_name or feature_name/feature_version formats, for example, <installedFeature>baz</installedFeature>.

  • Libraries

    The plugin accepts the libraries element, which can have one or more library child elements that specify a library URL.

    Example

    <libraries>
    <library>mvn:org.postgresql/postgresql/9.3-1102-jdbc41;type:=endorsed</library>
</libraries>

B.3. Customized Karaf assembly

The recommended way to create a Karaf server assembly is to use the karaf:assembly goal provided by the karaf-maven-plugin. This assembles a server from the Maven dependencies in the project’s pom.xml file. Both the bundles (or features) that are specified in karaf-maven-plugin configuration and the dependencies specified in the <dependencies> section in the pom.xml can go into the customized karaf assembly.

  • for kar

    Dependencies with kar type will be added as startup (scope=compile), boot (scope=runtime) or installed (scope=provided) kars in karaf-maven-plugin. The kars are unzipped to working directory (target/assembly) and feature XMLs are searched for and used as additional feature repositories (with stage equal to the stage of given kar).

  • for features.xml

    Dependencies with features classifier will be used as startup (scope=compile), boot (scope=runtime) or installed (scope=provided) repositories in karaf-maven-plugin. There’s no need to explicitly add feature repositories that are found in kar.

  • for jar and bundle

    Dependencies with bundle or jar type will be used as startup (scope=compile), boot (scope=runtime) or installed (scope=provided) bundles in karaf-maven-plugin.

B.3.1. karaf:assembly goal

You can create a Karaf server assembly using the karaf:assembly goal provided by the karaf-maven-plugin. This goal assembles a microservices style server assembly from the Maven dependencies in the project POM. In a Fuse on OpenShift project, it is recommended that you bind the karaf:assembly goal to the Maven install phase. The project uses bundle packaging and the project itself gets installed into the Karaf container by listing it inside the bootBundles element.

Note

Include only the necessary elements like karaf framework feature in startup stage as it will go into etc/startup.properties and at this stage karaf features service is not fully started. Defer other elements to boot stage.

Example

The following example displays the typical Maven configuration in a quickstart: 

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>karaf-maven-plugin</artifactId>
  <version>${fuse.version}</version>
  <extensions>true</extensions>
  <executions>
    <execution>
      <id>karaf-assembly</id>
      <goals>
        <goal>assembly</goal>
      </goals>
      <phase>install</phase>
    </execution>
  </executions>
  <configuration>

    <karafVersion>{karafMavenPluginVersion}</karafVersion>
    <useReferenceUrls>true</useReferenceUrls>
    <archiveTarGz>false</archiveTarGz>
    <includeBuildOutputDirectory>false</includeBuildOutputDirectory>
    <startupFeatures>
      <feature>karaf-framework</feature>
            </startupFeatures>
            <bootFeatures>
      <feature>shell</feature>
      <feature>jaas</feature>
      <feature>aries-blueprint</feature>
      <feature>camel-blueprint</feature>
      <feature>fabric8-karaf-blueprint</feature>
      <feature>fabric8-karaf-checks</feature>
    </bootFeatures>
    <bootBundles>
      <bundle>mvn:${project.groupId}/${project.artifactId}/${project.version}</bundle>
    </bootBundles>
  </configuration>
</plugin>