Using the karaf-maven-plugin
The Karaf Maven plugin allows you:
-
to work with Karaf features: verify and validate a features descriptor, add features bundle into a repository, create a KAR archive from a features descriptor, etc.
-
to create Karaf commands help: it generates help from Karaf commands
-
to modify Karaf instances and create distributions
See [examples/karaf-maven-example] for details.
Packaging
The most generally useful features of the karaf-maven-plugin are exposed as packagings. To use the packagings the pom or an ancestor must configure the karaf-maven-plugin with extensions:
<build> <pluginManagement> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> <extensions>true</extensions> </plugin> </plugins> </pluginManagement> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> </plugin> </plugins> </build>
Then specify the packaging in your project as usual, e.g.
<packaging>kar</packaging>
Packaging | Description |
---|---|
feature |
The feature packaging verifies a features.xml descriptor using the |
kar |
The kar packaging generates a features.xml descriptor using the |
karaf-assembly |
Assembles a Karaf server based on the features descriptors and kar files listed as Maven dependencies. |
Commands goals
The karaf-maven-plugin
is able to generate documentation for Karaf commands
karaf:commands-generate-help
The karaf:commands-generate-help
goal generates documentation containing Karaf commands help.
It looks for Karaf commands in the current project class loader and generates the help as displayed with the --help
option in the Karaf shell console.
Example
The example below generates help for the commands in the current project:
<project> <build> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> <executions> <execution> <id>document-commands</id> <phase>generate-resources</phase> <goals> <goal>commands-generate-help</goal> </goals> <configuration> <targetFolder>${project.build.directory}/docbook/sources</targetFolder> </configuration> </execution> </executions> </plugin> </plugins> </build> </project>
Parameters
Name | Type | Description |
---|---|---|
|
|
The directory where the documentation output files are to be generated. Default value: ${project.build.directory}/docbkx/sources |
|
|
The output format (docbx, asciidoc, or conf) of the commands documentation. Default value: docbx |
|
|
The class loader to use in loading the commands. Default value: ${project} |
Features and kar goals
Note
|
You should use the features or kar packaging instead of these individual goals. |
The karaf-maven-plugin
provides several goals to help you create and verify features XML descriptors as well as leverage your features to create a custom Karaf distribution.
karaf:features-generate-descriptor
The karaf:features-generate-descriptor
goal generates a features XML file based on the Maven dependencies.
By default, it will follow Maven transitive dependencies, stopping when it encounters bundles already present in features that are Maven dependencies.
A record of the dependency tree search can be found in target/history/treeListing.txt.
You can track dependency changes and warn or fail on change.
Configuration
Specify the packaging as a top level element
<packaging>feature</packaging>
You can supply a feature descriptor to extend in src/main/feature/feature.xml
.
Parameter Name | Type | Description |
---|---|---|
aggregateFeatures |
boolean (false) |
Specifies processing of feature repositories that are (transitive) Maven dependencies. If false, all features in these repositories become dependencies of the generated feature. If true, all features in these repositories are copied into the generated feature repository. |
startLevel |
int |
The start level for the bundles determined from Maven dependencies. This can be overridden by specifying the bundle in the source feature.xml with the desired startlevel. |
includeTransitiveDependency |
boolean (true) |
Whether to follow Maven transitive dependencies. |
checkDependencyChange |
boolean (false) |
Whether to record dependencies in |
warnOnDependencyChange |
boolean (false) |
whether to fail on changed dependencies (false, default) or warn in the build output (true). |
logDependencyChanges |
boolean (false) |
If true, added and removed dependencies are shown in |
overwriteChangedDependencies |
boolean (false) |
If true, the |
Example
<project> ... <packaging>feature</packaging> <dependencies> <dependency> <groupId>org.apache</groupId> <artifactId>bundle1</artifactId> <version>1.0</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> <extensions>true</extensions> <configuration> <enableGeneration>true</enableGeneration> </configuration> <executions> <execution> <id>generate-features-file</id> <phase>generate-resources</phase> <goals> <goal>features-generate-descriptor</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project>
karaf:verify
Except in unusual circumstances, use the <packaging>feature</packaging>
to run this goal.
The karaf:verify
goal verifies and validates a features XML descriptor by checking if all the required imports
for the bundles defined in the features can be matched to a provided export.
By default, the plugin tries to add the Karaf core features (standard and enterprise) in the repositories set. It means that it’s not required to explicitly define the Karaf features descriptor in the repository section of your features descriptor.
Example
The example below validates the features defined in the target/features.xml
by checking all the imports and exports.
It reads the definition for the packages that are exported by the system bundle from the src/main/resources/config.properties
file.
<project> <build> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <configuration> </configuration> <executions> <execution> <id>verify</id> <phase>process-resources</phase> <goals> <goal>verify</goal> </goals> <configuration> <descriptors> <descriptor>mvn:org.apache.karaf.features/framework/4.0.4/xml/features</descriptor> <descriptor>file:${project.build.directory}/feature/feature.xml</descriptor> </descriptors> <distribution>org.apache.karaf.features:framework</distribution> <javase>1.8</javase> <framework> <feature>framework</feature> </framework> </configuration> </execution> </executions> </plugin> </plugins> </build> </project>
Parameters
Name | Type | Description |
---|---|---|
|
|
The list of features XML repositories to use for the verify |
|
|
The list of features to verify. If not specified, all features in the descriptors will be verified. |
|
|
The features providing the Karaf framework (optional) |
|
|
The Java version to use for the verify |
karaf:features-add-to-repository
Consider using the karaf-assembly packaging which makes it easy to assemble a custom distribution in one step instead of this individual goal.
The karaf:features-add-to-repository
goal adds all the required bundles for a given set of features into directory.
You can use this goal to create a /system
directory for building your own Karaf-based distribution.
By default, the Karaf core features descriptors (standard and enterprise) are automatically included in the descriptors set.
Example
The example below copies the bundles for the spring
and war
features defined in the Karaf features XML descriptor
into the target/features-repo
directory.
<project> <build> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> <executions> <execution> <id>features-add-to-repo</id> <phase>generate-resources</phase> <goals> <goal>features-add-to-repository</goal> </goals> <configuration> <descriptors> <descriptor>mvn:org.apache.karaf.features/standard/4.0.0/xml/features</descriptor> <descriptor>mvn:my.groupid/my.artifactid/1.0.0/xml/features</descriptor> </descriptors> <features> <feature>spring</feature> <feature>war</feature> <feature>my</feature> </features> <repository>target/features-repo</repository> </configuration> </execution> </executions> </plugin> </plugins> </build> </project>
Parameters
Name | Type | Description |
---|---|---|
|
|
List of features XML descriptors where the features are defined |
|
|
List of features that bundles should be copied to the repository directory |
|
|
The directory where the bundles will be copied by the plugin goal |
karaf:create-kar
Note
|
Except in unusual circumstances, use the |
The karaf:kar
goal assembles a KAR archive from a features XML descriptor file, normally generated in the same project
with the karaf:features-generate-descriptor
goal.
There are two important directories in a kar:
-
repository/
contains a Maven structured repository of artifacts to be copied into the Karaf repository. The features descriptor and all the bundles mentioned in it are installed in this directory. -
resources/
contains other resources to be copied over the Karaf installation.
Everything in target/classes
is copied into the kar.
Therefore resources you want installed into Karaf need to be in e.g. src/main/resources/resources
.
This choice is so other resources such as legal files from the maven-remote-resources-plugin can be included under
META-INF in the kar, without getting installed into Karaf.
Example
<project> ... <packaging>kar</packaging> <build> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> <extensions>true</extensions> <!-- There is no useful configuration for the kar mojo. The features-generate-descriptor mojo configuration may be useful --> </plugin> </plugins> </build> </project>
karaf:install-kar
Instances and distributions goals
Note
|
You should use the karaf-assembly packaging instead of this individual goal. |
The karaf-maven-plugin
helps you to build custom Karaf distributions or archives existing Karaf instances:
karaf:archive
Note
|
This goal is run as part of the karaf-assembly packaging. |
The karaf:archive
goal packages a Karaf instance archive from a given assembled instance.
Both tar.gz and zip formats are generated in the destination folder.
Example
The example below create archives for the given Karaf instance:
<project> <build> <plugins> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> <executions> <execution> <id>generate</id> <phase>package</phase> <goals> <goal>archive</goal> </goals> <configuration> <destDir>${project.build.directory}</destDir> <targetServerDirectory>${project.build.directory}/assembly</targetServerDirectory> <targetFile>${project.file}</targetFile> </configuration> </execution> </executions> </plugin> </plugins> </build> </project>
Parameters
Name | Type | Description |
---|---|---|
|
|
The target directory of the project. Default value: ${project.build.directory} |
|
|
The location of the server repository. Default value: ${project.build.directory}/assembly |
|
|
The target file to set as the project’s artifact. Default value: ${project.file} |
|
|
Switches creation of *.zip artifact on or off. Default value: true |
|
|
Switches creation of *.tar.gz artifact on or off. Default value: true |