| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| // |
| |
| === 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 `karaf:verify` goal. |
| |
| |kar |
| |The kar packaging generates a features.xml descriptor using the `karaf:features-generate-descriptor` and then packages a kar using the `karaf:features-create-kar` goal. |
| |
| |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 |
| |
| |`targetFolder` |
| |`File` |
| |The directory where the documentation output files are to be generated. Default value: ${project.build.directory}/docbkx/sources |
| |
| |`format` |
| |`String` |
| |The output format (docbx, asciidoc, or conf) of the commands documentation. Default value: docbx |
| |
| |`classLoader` |
| |`String` |
| |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 `src/main/history/dependencies.xml` for change tracking. |
| |
| |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 `target/history`. |
| |
| |overwriteChangedDependencies |
| |boolean (false) |
| |If true, the `src/main/history/dependencies.xml` file will be overwritten if it has changed. |
| |=== |
| |
| ====== 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 |
| |
| |`descriptors` |
| |`String[]` |
| |The list of features XML repositories to use for the verify |
| |
| |`features` |
| |`String[]` |
| |The list of features to verify. If not specified, all features in the descriptors will be verified. |
| |
| |`framework` |
| |`String[]` |
| |The features providing the Karaf framework (optional) |
| |
| |`javase` |
| |`String` |
| |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 |
| |
| |`descriptors` |
| |`String[]` |
| |List of features XML descriptors where the features are defined |
| |
| |`features` |
| |`String[]` |
| |List of features that bundles should be copied to the repository directory |
| |
| |`repository` |
| |`File` |
| |The directory where the bundles will be copied by the plugin goal |
| |=== |
| |
| ===== `karaf:create-kar` |
| |
| [NOTE] |
| ==== |
| Except in unusual circumstances, use the `<packaging>kar</packaging>` to run this goal. |
| ==== |
| |
| 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 |
| |
| |`destDir` |
| |`File` |
| | The target directory of the project. Default value: ${project.build.directory} |
| |
| |`targetServerDirectory` |
| |`File` |
| |The location of the server repository. Default value: ${project.build.directory}/assembly |
| |
| |`targetFile` |
| |`File` |
| |The target file to set as the project's artifact. Default value: ${project.file} |
| |
| |`archiveZip` |
| |`Boolean` |
| |Switches creation of *.zip artifact on or off. Default value: true |
| |
| |`archiveTarGz` |
| |`Boolean` |
| |Switches creation of *.tar.gz artifact on or off. Default value: true |
| |=== |
| |
| ===== `karaf:assembly` |
| |
| ==== Run, client, deploy goals |
| |
| ===== `karaf:run` |
| |
| ===== `karaf:client` |
| |
| ===== `karaf:deploy` |