Background

Content packages may contain OSGi bundles/configuration which are picked up asynchronously by the JCR Installer Provider. That means that after the installation of a package the contained bundle/configuration is usually not yet installed.

Overview

The Installer FileVault Package Install Hook allows to install bundles and configurations synchronously during FileVault/content package installation by feeding them directly to the OSGI Installer core. That way FileVault package dependencies can be used to not only depend on content of a package, but also on configurations and bundles contained in a package (the installer install hook has to be added to the package the dependency points to). The mechanism is useful for scenarios when a package contains custom oak restrictions (e.g. Sling Oak Restrictions) or other install hook(s) that use the install hook package property (e.g. installhook.myhook.class) to reference OSGi services that are provided by another bundle. Also see SLING-7790

NOTE: When using with a package that should be usable with both the Feature Model (usually without the OSGi Installer) and Provisioning Model (usually with the OSGi Installer), ensure you use version 1.1.0 of this hook that will auto-detect its environment and only become active when the OSGi Installer is present (see SLING-8948)

Installation Process

The Installer Vault Package Install Hook scans through the contained files and installs bundles (extension jar) and OSGi configurations with extension config (conf and node configurations are not supported). Runmode folders (e.g. install.publish or config.author) are supported. To perform the installation, the hook registers the installable resources to the OSGi installer core with the exact same digest as the JCR installer would do (hence the JCR installer that will also process the resource but without causing any change as the digest matches). Files that are already installed are ignored (this is checked using the InfoProvider).

Pitfalls

In some cases a synchronous OSGi installer task leads to unavailability of the method by which the package has been provided (like the Composum Package Manager]. This is often caused by the fact that the Dynamic Class Loader Provider restarts due to newly provided bundles or the whole Sling Repository restarts due to a newly provided OSGi configuration. Therefore only use this method for bundles which are not providing classes via the Dynamic Class Loader Provider (e.g. Sling Model classes used by scripts).

Configuration

To include the install hook into a content package, use the following code:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <id>copy-hook-into-package</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>copy</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>org.apache.sling</groupId>
                        <artifactId>org.apache.sling.installer.provider.installhook</artifactId>
                        <version>1.1.0</version>
                    </artifactItem>
                </artifactItems>
                <outputDirectory>${project.build.directory}/vault-work/META-INF/vault/hooks</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

The following package properties are supported (only installPathRegex is required):