Overview

The DDF Marketplace provides a browser based interface to applications that can be downloaded and installed to the DDF Framework. These are applications that are in addition to the DDF "out-of-the-box" components.

The DDF components are packaged as Karaf features, which are collections of OSGi bundles. These features can be installed/uninstalled using the DDF Admin Console or command line console. DDF Marketplace applications also consist of one or more OSGi bundles, and possibly supplemental external files. These Marketplace application are packaged as Karaf kar files for easy download and installation.

A kar file is a Karaf-specific archive format named KAR (Karaf ARchive). Its format is a jar file which contains a feature descriptor file and one or more OSGi bundle jar files. The feature descriptor file identifies the application's name and the set of bundles that need to be installed, and any dependencies on other features that may need to be installed.

Creating a KAR File

The recommended method for creating a KAR file is to use the features-maven-plugin which has a create-kar goal (available as of Karaf v2.2.5, which DDF 2.X is based upon). This goal reads all of the features specified in the features descriptor file. For each feature in this file it resolves the bundles defined in the feature. All bundles are then packaged into the kar archive.

An example of using the create-kar goal is shown below:

<plugin>
            <groupId>org.apache.karaf.tooling</groupId>
            <artifactId>features-maven-plugin</artifactId>
            <version>2.2.5</version>
            <executions>
                <execution>
                    <id>create-kar</id>
                    <goals>
                        <goal>create-kar</goal>
                    </goals>
                    <configuration>
                        <descriptors>
                            <!-- Add any other <descriptor> that the features file may reference here -->
                        </descriptors>
                        <!--
                        Workaround to prevent the target/classes/features.xml file from being included in the
                        kar file since features.xml already included in kar's repository directory tree. 
                        Otherwise, features.xml would appear twice in the kar file, hence installing the
                        same feature twice. 
                        Refer to Karaf forum posting at http://karaf.922171.n3.nabble.com/Duplicate-feature-repository-entry-using-archive-kar-to-build-deployable-applications-td3650850.html
                        -->                            
                        <resourcesDir>${project.build.directory}/doesNotExist</resourcesDir>

                        <!-- 
                        Location of the features.xml file. If it references properties that need to be filtered, e.g., ${project.version}, it will need to be
                        filtered by the maven-resources-plugin.
                        -->
                        <featuresFile>${basedir}/target/classes/features.xml</featuresFile>

                        <!-- Name of the kar file (.kar extension added by default). If not specified, defaults to ${project.build.finalName} -->
                        <finalName>ddf-ifis-${project.version}</finalName>
                    </configuration>
                </execution>
            </executions>
 </plugin>

Examples of how kar files are created for DDF components can be found in the DDF source code under the ddf/distribution/ddf-kars directory.

The .kar file generated should be deployed to the application author's maven repository. The url to the application's kar file in this maven repository should be the installation url used when creating a listing in the DDF Marketplace for the application.

Including Data Files in a KAR File

Sometimes the developer may need to include data or configuration file(s) in a KAR file. An example of this would be a properties file for the JDBC connection properties of a catalog provider.

It is recommended that:

• Any data/configuration files be placed under the src/main/resources directory of the maven project. (Sub-directories under src/main/resources can be used, e.g., etc/security)
• The maven project's pom file should be updated to attach each data/configuration file as an artifact (using the build-helper-maven-plugin)
• Add each data/configuration file to the KAR file by using the <configfile> tag in the KAR's features.xml file

Installing a KAR File

When the user downloads a Marketplace application by clicking on the Installation link, the application's kar file is downloaded. This kar file should be placed in the <DDF_INSTALL_DIR>/deploy directory of the running DDF instance. DDF then detects that a file with a .kar file extension has been placed in this monitored directory, unzips the kar file into the <DDF_INSTALL_DIR>/system directory, and installs the bundle(s) listed in the kar file's feature descriptor file. The user can then go to the Admin Console's Features tab and verify the new feature(s) is installed.

Installing a KAR File for DDF 2.0.0 Release

DDF 2.0.0 is based on Karaf v2.2.2, which has a bug in the KAR deployer. Therefore a more manual approach to install a kar file is required rather than just dropping the kar file in the <DDF_INSTALL_DIR>/deploy directory.

After downloading the Marketplace application's kar file:

1. Copy the kar file to a temp directory
2. Unjar the kar file in this temp directory
3. Edit the etc/org.ops4j.pax.url.mvn.cfg configuration file. Uncomment the org.ops4j.pax.url.mvn.repositories property if it is commented out.
   Append the org.ops4j.pax.url.mvn.repositories property with file:<temp_dir>/<kar_root_dir>/repository
4. Restart DDF
5. Add the kar's feature repository URL, either using the command line console or Features tab in the Admin Console

Example:

Assume the Marketplace application's kar file is named new-app-1.2.3.kar

1. Copy new-app-1.2.3.kar to /my_kars temp directory
2. unjar xvf /my_kars/new-app-1.2.3.kar
3. Edit the <DDF_INSTALL_DIR>/etc/org.ops4j.pax.url.mvn.cfg configuration file and append file:/my_kars/new-app-1.2.3/repository to the org.ops4j.pax.url.mvn.repositories property
4. Restart DDF
5. At the ddf@local> prompt enter features:addurl file:/my_kars/new-app-1.2.3/repository/new-app/1.2.3/new-app-1.2.3-features.xml
6. At the ddf@local> prompt enter features:list and the new feature(s) loaded by the kar file should be displayed and active