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.propertiesIn 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 inetc/startup.propertiesat the appropriate start level and the bundles being copied into thesysteminternal repository. You can usefeature_nameorfeature_name/feature_versionformats, for example,<startupFeature>foo</startupFeature>.Boot stage:
etc/org.apache.karaf.features.cfgThis stage manages features available in
featuresBootproperty and repositories infeaturesRepositoriesproperty. 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 thesysteminternal repository. You can usefeature_nameorfeature_name/feature_versionformats, 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 thesysteminternal repository. Therefore at runtime the feature may be installed without access to external repositories. You can usefeature_nameorfeature_name/feature_versionformats, 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
kartype 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
featuresclassifier 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
bundleorjartype 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.
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>