Apache
Home » Documentation » Development

Maven Sling Plugin

The Maven Sling Plugin provides a number of goals which may be of help while developping bundles for Sling. To run the plugin you need at least Maven 3.x and JDK 1.6 or higher. Maven Sling Plugin provides the following goals:

Name Description
sling:deploy Deploy an OSGi-bundle into the OBR running on a Sling instance.
sling:deploy-file Deploy an OSGi-bundle into the OBR running on a Sling instance without requiring a project descriptor file.
sling:install Install an OSGi-bundle into a running Sling instance.
sling:install-file Install an OSGi-bundle into a running Sling instance without requiring a project descriptor file.
sling:uninstall Uninstall an OSGi-bundle from a running Sling instance.
sling:validate Validate JSON files in module (used for initial content loading).

Usage

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.sling</groupId>
          <artifactId>maven-sling-plugin</artifactId>
          <version>2.1.6</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>org.apache.sling</groupId>
        <artifactId>maven-sling-plugin</artifactId>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

For more information, see "Guide to Configuring Plug-ins"

The deploy goal

The deploy goal uploads a bundle to a Sling OSGi Bundle Repository server implemented by the sling-obr bundle, which may be located on a remote system. The plugin places an HTTP POST request to the server sending the bundle file. 

Use

To use the deploy goal of the Maven Sling Plugin define the following elements in the <plugins> section of the POM:

<?xml version="1.0" encoding="ISO-8859-1"?>
<project>
  ....
  <build>
    ....
    <plugins>
      ....
      <plugin>
        <groupId>org.apache.sling</groupId>
        <artifactId>maven-sling-plugin</artifactId>
        <executions>
          <execution>
            <id>deploy-bundle</id>
            <goals>
              <goal>deploy</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ....
    <plugins>
    ....
  <build>
  ....
<project>

Configuration

The deploy goal may be configured in the <configuration> element using the following properties:

Parameter Default Value System Property Overwrite Description
skip false sling.deploy.skip Whether to skip this step even though it has been configured in the project to be executed. The main use of this setting is preventing deployment of the bundle to a Sling OSGi Bundle Repository server if it is known that there is none or if such an upload is not required.
buildDirectory ${project.build.directory} - The path of the file to be installed
jarName ${project.build.finalName}.jar - The name of the file to be installed
obr - obr The URL of the running Sling instance to which the bundle is installed. Note that this parameter is required and has no default value. It must always be specified in the configuration section or on the command line.

The deploy-file goal

The deploy-file goal is equivalent to the deploy goal except, that the deploy-file does not require a project descriptor file while the deploy goal does. In other words the deploy-file goal may used to upload any bundle file available to a Sling OBR server instance.

Use

The deploy-file goal may only be used from the command line by explicitly calling it as in:

$ mvn org.apache.sling:maven-sling-plugin:deploy-file -Dsling.file=<file> -Dobr=<url>

Specifying the bundle file to upload with the sling.file property is required.

Configuration

The deploy-file supports similar configuration parameters as the deploy goal with the exception of the skip parameter which makes no sense. In addition, all parameters must be specified on the command line by setting system properties. The bundleFileName parameter specified as the sling.file system property as well as the obr URL are required by the deploy-file goal.

Parameter Default Value System Property Overwrite Description
bundleFileName ${project.build.directory}/${project.build.finalName}.jar sling.file The path and name of the file to be installed
obr - obr The URL of the running Sling instance to which the bundle is installed. Note that this parameter is required and has no defualt value. It must always be specified in the configuration section or on the command line.

Example: To deploy the bundle file someBundle.jar to the OBR running at [http://obr.sample.org](http://obr.sample.org) you might use the goal as follows:

$ mvn org.apache.sling:maven-sling-plugin:deploy-file -Dsling.file=someBundle.jar -Dobr=http://obr.sample.org

The install goal

The install goal uploads a bundle to a running sling instance, which may be located on a remote system. The plugin places an HTTP POST request to Felix Web Console. It's also possible to HTTP PUT instead of POST leveraging the WebDAV bundle from Sling. Since version 2.1.8 you can also leverage the Sling POST servlet for that.

Use

To use the install goal of the Maven Sling Plugin define the following elements in the <plugins> section of the POM:

<?xml version="1.0" encoding="ISO-8859-1"?>
<project>
  ....
  <build>
    ....
    <plugins>
      ....
      <plugin>
        <groupId>org.apache.sling</groupId>
        <artifactId>maven-sling-plugin</artifactId>
        <executions>
          <execution>
            <id>install-bundle</id>
            <goals>
              <goal>install</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ....
    <plugins>
    ....
  <build>
  ....
<project>

Configuration

The install goal may be configured in the <configuration> element using the following properties:

Parameter Default Value System Property Overwrite Description
skip false sling.install.skip Whether to skip this step even though it has been configured in the project to be executed. The main use of this setting is preventing installation of the bundle to a running Sling installation if it is known that there is none or if such an upload is not required, for example when building the bundle in an automated build system such as Confluence.
bundleFileName ${project.build.directory}/${project.build.finalName}.jar sling.file The path and name of the file to be installed. Only applies when POSTing to Felix Web Console.
bundleStart true sling.bundle.start Whether to start the bundle after installing it. If the bundle is just updated, this parameter is ignored even if the bundle is currently stopped. Only applies when POSTing to Felix Web Console.
bundleStartLevel 20 sling.bundle.startlevel The start level to set on the installed bundle. If the bundle is already installed and therefore is only updated this parameter is ignored. The parameter is also ignored if the running Sling instance has no StartLevel service (which is unusual actually). Only applies when POSTing to Felix Web Console.
slingUrl http://localhost:8080/system/console sling.url The URL of the running Sling instance to which the bundle is installed. The default does only work for deployment via WebConsole.
slingUrlSuffix sling.urlSuffix An optional url suffix which will be appended to the sling.url for use as the real target url. This allows to configure different target URLs in each POM, while using the same common sling.url in a parent POM. This is typically only used in conjunction with WebDAV or SlingPostServlet deployment methods.
user admin sling.user The name of the user to authenticate as with the running Sling instance given by the slingUrl parameter
password admin sling.password The password of the user to authenticate as with the running Sling instance given by the slingUrl parameter
deploymentMethod WebConsole sling.deploy.method Only available since version 2.1.8 (see also SLING-5335).
Allowed values:
WebConsole, uses the Felix Web Console REST API for deployment (HTTP POST). This is the default. Make sure that slingUrl points to the Felix Web Console in that case (http://<yourhost:yourport>/system/console).
WebDAV, uses WebDAV for deployment (HTTP PUT). Make sure that slingUrl points to the entry path of the Sling WebDAV bundle (usually below regular Sling root URL). Issues an HTTP Delete for the uninstall goal.
SlingPostServlet, uses the Sling Post Servlet for deployment (HTTP POST). Make sure that slingUrl points a path which is handled by the Sling POST Servlet (usually below regular Sling root URL).
mimeType application/java-archive sling.mimeType The content type / mime type used for WebDAV or Sling POST deployment.
usePut false sling.usePut If a simple HTTP PUT should be used instead of the standard POST to the felix console. In the uninstall goal, a HTTP DELETE will be used. Deprecated since version 2.1.8 (see also SLING-5335). Use deploymentMethod=WebDAV instead.
refreshPackages true sling.refreshPackages Whether to refresh the packages after installing the uploaded bundle. If this property is set to true, the PackageAdmin.refreshPackages(Bundle) method is called after installing or updating the bundle. Only applies when POSTing to Felix Web Console

Intermediate Node Creation

For all deploymentMethods except WebDAV the bundle is not directly deployed within the OSGi container, but rather being uploaded to the JCR and from there on being picked up by the JCR Installer Provider asynchronously, which takes care of deploying it in the OSGi container. For both other deployment methods, intermediate nodes (i.e. inexisting parent nodes) are automatically created. The primary type of those intermediate nodes depend on the deployment method

The install-file goal

The install-file goal is equivalent to the install goal except, that the install-file does not require a project descriptor file while the install goal does. In other words the install-file goal may used to upload any bundle file available to a running Sling instance.

Use

The install-file goal may only be used from the command line by explicitly calling it as in:

$ mvn org.apache.sling:maven-sling-plugin:install-file -Dsling.file=<file>

Specifying the bundle file to upload with the sling.file property is required.

Configuration

The install-file supports the same configuration parameters as the install goal with the exception of the skip parameter which makes no sense. In addition, all parameters must be specified on the command line by setting system properties. The bundleFileName parameter specified as the sling.file system property is required by the install-file goal.

For a description of the parameters see the configuration section of the install goal above.

Example: To upload the bundle file someBundle.jar you might use the goal as follows:

$ mvn org.apache.sling:maven-sling-plugin:install-file -Dsling.file=someBundle.jar

The uninstall goal

The uninstall goal uninstalls a bundle from a running sling instance, which may be located on a remote system. The plugin uninstalles a bundle via a HTTP POST{}request. It's also possible to use HTTP DELETE instead of POST for WebDAV.

Use

To use the uninstall goal of the Maven Sling Plugin define the following elements in the <plugins> section of the POM:

<?xml version="1.0" encoding="ISO-8859-1"?>
<project>
  ....
  <build>
    ....
    <plugins>
      ....
      <plugin>
        <groupId>org.apache.sling</groupId>
        <artifactId>maven-sling-plugin</artifactId>
        <executions>
          <execution>
            <id>uninstall-bundle</id>
            <goals>
              <goal>uninstall</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ....
    <plugins>
    ....
  <build>
  ....
<project>

Configuration

The uninstall goal may be configured in the <configuration> element using the following properties:

Parameter Default Value System Property Overwrite Description
bundleFileName ${project.build.directory}/{project.build.finalName}.jar sling.file The path and name of the file to be uninstalled
slingUrl http://localhost:8080/system/console sling.url The URL of the running Sling instance on which the bundle should be uninstalled. The default does only work for deployment via WebConsole.
slingUrlSuffix sling.urlSuffix An optional url suffix which will be appended to the sling.url for use as the real target url. This allows to configure different target URLs in each POM, while using the same common sling.url in a parent POM. This is typically only used in conjunction with WebDAV or SlingPostServlet deployment methods.
user admin sling.user The name of the user to authenticate as with the running Sling instance given by the slingUrl parameter
password admin sling.password The password of the user to authenticate as with the running Sling instance given by the slingUrl parameter
deploymentMethod WebConsole sling.deploy.method Only available since version 2.1.8 (see also SLING-5335).
Allowed values:
WebConsole, uses the Felix Web Console REST API for deployment (HTTP POST). This is the default. Make sure that slingUrl points to the Felix Web Console in that case (http://<yourhost:yourport>/system/console).
WebDAV, uses WebDAV for deployment (HTTP PUT). Make sure that slingUrl points to the entry path of the Sling WebDAV bundle (usually below regular Sling root URL). Issues an HTTP Delete for the uninstall goal.
SlingPostServlet, uses the Sling Post Servlet for deployment (HTTP POST). Make sure that slingUrl points a path which is handled by the Sling POST Servlet (usually below regular Sling root URL).
usePut false sling.usePut If a simple HTTP PUT should be used instead of the standard POST to the felix console. In the uninstall goal, an HTTP DELETE will be used. Deprecated since version 2.1.8 (see also SLING-5335). Use deploymentMethod=WebDAV instead.

The validate goal

The validate goal checks the JSON code of a bundle.

Use

To use the validate goal of the Maven Sling Plugin define the following elements in the <plugins> section of the POM:

<?xml version="1.0" encoding="ISO-8859-1"?>
<project>
  ....
  <build>
    ....
    <plugins>
      ....
      <plugin>
        <groupId>org.apache.sling</groupId>
        <artifactId>maven-sling-plugin</artifactId>
        <executions>
          <execution>
            <id>validate-bundle</id>
            <goals>
              <goal>validate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ....
    <plugins>
    ....
  <build>
  ....
<project>

Configuration

The validate goal may be configured in the <configuration> element using the following properties:

Parameter Default Value System Property Overwrite Description
skip false sling.validation.skip Whether to skip the validation
skipJson false sling.validation.skipJson Whether to skip the JSON validation. At the time, there's no difference between skip and skipJson because only JSON files will be validated by now.
Rev. 1736400 by kwin on Thu, 24 Mar 2016 07:40:14 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.