gradle-karaf-plugin

Features

• ✓ Karaf features

• ✓ Karaf KAR

• ❏ Karaf custom distribution

• ❏ Nice documentation

Tasks

Automatically generate Karaf feature file in /build/karaf/features

gradle generateFeatures

Automatically generate Karaf repo (system directory) in /build/karaf/repo

gradle generateRepo

Automatically generate Karaf kar file in /build/karaf/kar

gradle generateKar

Description

The gradle-karaf-plugin is designed to automate the process of creating Apache Karaf feature, repo, and kar files.

This plugin generates the desired karaf files by utilizing the native gradle configurations mechanism. As gradle automatically determines all direct and transitive dependencies, a complete list of dependencies is provided to the plugin for a given set of configurations.

As OSGi can only install bundles, standard jars must be wrapped to add necessary manifest information specifying the jar’s import and export packages. To simply this process Karaf provides a native wrap tool that can be run during jar/bundle installation. This plugin determines if each dependency is already a bundle and adds the wrap tag if it is not (see example below).

Notes

• Considering that gradle automatically "promotes" dependency version conflicts, only a single version of a dependency is avalible per each gradle configuration. As OSGi bundles can mandate certain versions of dependencies, it is likely that multiple versions of a jar/bundle are needed. In this case, it is recommended to add another gradle configuration, perhaps "karaf", and specify the other dependency version under this new configuration. Include both configurations to the karaf→features→feature→configurations statement (see example below). This will result in both versions of the dependency being added to the feature/kar file.

• Karaf 4 support requires the xsd version be at least 1.3.0.

• This plugin is an extension of the previous gradle-karaf-feature-plugin

Requirements

• Gradle 3.0+

Usage

plugins {
    id 'com.github.lburgazzoli.karaf' version '0.0.49'
}

repositories {
    mavenCentral()
}

Or for compatibility with old versions of Gradle:

apply plugin: 'com.github.lburgazzoli.karaf'

buildscript {
    dependencies {
        classpath "gradle.plugin.com.github.lburgazzoli:gradle-karaf-plugin:0.0.49"
    }
}

repositories {
    mavenCentral()
}

Example

build.gradle

plugins {
    id 'java' //required only for runtime configuration
    id 'com.github.lburgazzoli.karaf' version '0.0.49'
}

repositories {
    mavenCentral()
}

group   = 'com.github.lburgazzoli'
version = '0.0.1'

configurations {
    foo
    bar
    // This will avoid adding transitive dependencies
    baz {
        transitive = false
    }
}

dependencies {
    runtime 'com.google.guava:guava:19.0'

    foo 'commons-io:commons-io:2.4'

    bar (
      'com.fasterxml.jackson.core:jackson-core:2.7.0',
      'com.fasterxml.jackson.core:jackson-databind:2.7.0',
      'com.fasterxml.jackson.core:jackson-annotations:2.7.0'
    )

    baz 'com.squareup.retrofit2:retrofit:2.0.0'
}

karaf {
    features {
        // See section below for karaf 4 support if using 1.3.0
        xsdVersion  = '1.2.0'
        name = "${project.name}-${version}"
        outputFile = file("${project.buildDir}/karaf/features/${project.name}-${project.version}-feature.xml")
        version     = '4.0.0' // Your project version
        description = 'Karaf features'

        // Include the current project, false by default
        includeProject = false

        // Add in extra repositories to the features xml file
        repository "mvn:org.apache.karaf.features/standard/4.0.0/xml/features"

        // Define a feature named 'my-feature1' with dependencies from runtime configuration (default if java plugin is enabled) and 'foo'
        feature {
            name        = 'my-feature1'
            description = 'Includes runtime and foo dependencies'

            // Include one or more additional configuration
            configuration 'foo'
        }

        // Define a feature named 'my-feature2' with dependencies from 'bar' and 'baz' configurations
        feature {
            name        = 'my-feature2'
            description = 'Includes runtime, bar and baz dependencies'

            // Override configurations
            configurations 'bar', 'baz'
        }

        feature {
            name        = 'my-feature3'
            description = 'Feature with capabilities'

            // Override configurations
            configurations 'foo', 'bar'

            // Add feature dependency (newest)
            feature 'aries-proxy'

            // Customize artifacts with group 'com.fasterxml.jackson.core'
            bundle ('com.fasterxml.jackson.core') {
                attribute 'start-level', '20'
            }

            conditional('bundle') {
                bundle 'commons-io:commons-io'
            }
            capability('osgi.service') {
                effective = 'active'
                extra     = 'objectClass=org.apache.aries.blueprint.services.ParserService'
            }

            capability('osgi.extender') {
                extra     = 'osgi.extender="osgi.blueprint";uses:="org.osgi.service.blueprint.container,org.osgi.service.blueprint.reflect";version:Version="1.0"'
            }
        }

        // Define a feature named 'my-feature4'
        feature {
            name        = 'my-feature4'
            description = 'Feature with config file'

            configurations 'foo'

            // Add configFile entry
            configFile {
                filename = "/etc/my-file.xml"
                uri      = "mvn:com.my.company/my.artifact/${project.version}/xml/my-file"
            }

            // Add configFile entry and copy a local file to the kar repository
            configFile {
                filename = '${karaf.etc}/my.Config.cfg'
                file     = file("resources/my.Config.cfg")
                uri      = "mvn:com.my.company/my.artifact/${project.version}/cfg/features"
                override = true // (optional) Override existing configuration files within karaf. False by default
            }
        }
    }

    // Enable generation of an OSGi bundles repository, laid out as a Maven 2 repository based on
    // the features defined above. This can be used to provision the 'system' directory of a
    // custom Karaf distribution.
    // To generate repo use generateRepo, assemble or install
    repo {
    }

    // Enable generation of Karaf Archive KAR based on features defined above.
    // To generate kar either use generateKar, assemble or install
    kar {
        // Optionally set the kar name, default is:
        //
        //     ${features.name}-${features.version}.kar
        //
        // Extension is automatically set to .kar
        archiveName = 'foo'
    }
}

Generated Result from "gradle generateFeatures"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<features xmlns="http://karaf.apache.org/xmlns/features/v1.2.0" name="my.project-0.0.1">
  <repository>mvn:org.apache.karaf.features/standard/4.0.0/xml/features</repository>
  <feature name="my-feature1" version="0.0.1" description="Includes runtime and foo dependencies">
    <bundle>mvn:com.google.guava/guava/19.0</bundle>
    <bundle>mvn:commons-io/commons-io/2.4</bundle>
  </feature>
  <feature name="my-feature2" version="0.0.1" description="Includes runtime, bar and baz dependencies">
    <bundle>mvn:com.fasterxml.jackson.core/jackson-core/2.7.0</bundle>
    <bundle>mvn:com.fasterxml.jackson.core/jackson-annotations/2.7.0</bundle>
    <bundle>mvn:com.fasterxml.jackson.core/jackson-databind/2.7.0</bundle>
    <!--
        as squareup's jars a re not OSGi ready, the plugin automatically adds wrap instruction
    -->
    <bundle>wrap:mvn:com.squareup.retrofit2/retrofit/2.0.0</bundle>
  </feature>
  <feature name="my-feature3" version="0.0.1" description="Feature with capabilities">
    <feature>aries-proxy</feature>
    <bundle start-level="20">mvn:com.fasterxml.jackson.core/jackson-core/2.7.0</bundle>
    <bundle start-level="20">mvn:com.fasterxml.jackson.core/jackson-annotations/2.7.0</bundle>
    <bundle start-level="20">mvn:com.fasterxml.jackson.core/jackson-databind/2.7.0</bundle>
    <conditional>
      <condition>bundle</condition>
      <bundle>mvn:commons-io/commons-io/2.4</bundle>
    </conditional>
    <capability>osgi.service;effective:='active';resolution:='mandatory';objectClass=org.apache.aries.blueprint.services.ParserService</capability>
    <capability>osgi.extender;effective:='resolve';resolution:='mandatory';osgi.extender="osgi.blueprint";uses:="org.osgi.service.blueprint.container,org.osgi.service.blueprint.reflect";version:Version="1.0"</capability>
  </feature>
  <feature name="my-feature4" version="0.0.1" description="Feature with config file">
    <configfile finalname="/etc/my-file.xml">mvn:com.my.company/my.artifact/0.0.1/xml/my-file</configfile>
    <configfile finalname="${karaf.etc}/my.Config.cfg" override="true">mvn:com.my.company/my.artifact/0.0.1/cfg/features</configfile>
    <bundle>mvn:commons-io/commons-io/2.4</bundle>
  </feature>
</features>

Karaf 4 Support

Karaf 4 features xsd v1.3.0 partially supported

<feature version="1.2.3" dependency="true">dependent-feature</feature>

To generate this stuff

1. Set xsdVersion to 1.3.0

2. Use dependency with configuration closure

karaf {
  features {
    xsdVersion = '1.3.0'
    name = "${project.name}-${version}"
    outputFile = file("${project.buildDir}/karaf/features/${project.name}-feature.xml")
    mainFeature {
      name = 'main-feature-name'
      feature('dependent-feature') {
        dependency = true              //false by default
        version = "1.2.3"              //empty by default
      }
    }
  }
}

generated file build/karaf/features/project1-feature.xml will look like below

<features xmlns='http://karaf.apache.org/xmlns/features/v1.3.0' name='featuresName'>
  <feature name='main-feature-name' version='1.0.0'>
    <feature version="1.2.3" dependency="true">dependent-feature</feature>
  </feature>
</features>