Maven Sling Plugin
The Maven Sling Plugin provides a number of goals which may be of help while developping bundles for Sling:
- install - Install a bundle to a running Sling instance
- install-file - Install a bundle file to a running Sling instance
- deploy - Deploy a bundle to a OSGi Bundle Repository
- deploy-file - Deploy a bundle to a OSGi Bundle Repository
- assembly - Package an Assembly according to the project descriptor
- install-properties - Setup a sling_install.properties file from the project descriptor
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 the sling instance sending the bundle file together with flags indicating whether to start the bundle and what start level to assign the bundle.
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 |
| slingUrl | http://localhost:8080/sling | sling.url | The URL of the running Sling instance to which the bundle is installed |
| 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 |
| 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) |
| 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 |
| 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. |
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 deploy goal
The deploy goal uploads a bundle to a Sling OSGi Bundle Repository server implemenred 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 defualt 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
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 assembly goal
The assembly goal is a Maven lifecycle goal which should be specified as <packaging in the project descriptor.
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> .... <packaging>assembly</packaging> .... <build> .... <plugins> .... <plugin> <groupId>org.apache.sling</groupId> <artifactId>maven-sling-plugin</artifactId> </plugin> .... <plugins> .... <build> .... <project>
Configuration
| Parameter | Default Value | System Property Overwrite | Description |
|---|---|---|---|
| defaultStartLevel | 30 | sling.assemblies.startlevel.default | The default start level for bundles not listed in the startLevels property. Valid values are integers in the range [1 .. Integer.MAX_VALUE]. |
| startLevels | – | – | Startlevel mappings for included artifacts. Indexed by <groupId>.<artifactId>, value is numeric startlevel [1 .. Integer.MAX_VALUE] |
| versionPolicies | – | – | Version mapping for included artifacts. Indexed by <groupId>.<artifactId>, value is a policy string, which is either strict, the defualt value or latest". See notes for more information. |
| repositories | – | – | An optional comma-separated list of URLs of OSGi Bundle Repositories e.g. http://repohost.day.com/repository.xml - to use for the installation of the bundles. |
| embedded | false | sling.assemblies.embedded | Whether the bundles are embedded in the created JAR file or not. Default is to not embed the bundles. |
Notes
Bundles contained in an Assembly Bundle are referred to by their bundle symbolic name and a version range. Depending on the versionPolicy applied to the bundle, this version range is specified such that only bundles with the same major and minor number as defined by the dependency are accepted or that any version equal to or higher to the specified dependency is accepted. Requiring the same major and minor version number is defined by the strict policy while accepting any version higher than or equal to the declared one is defined by the latest policy. The defualt policy is strict.
The install-properties goal
This bundle generates the WEB-INF/sling_install.properties containing the referenced assemblies.
Use
To use the install-properties 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-properties</id> <goals> <goal>install-properties</goal> </goals> </execution> </executions> </plugin> .... <plugins> .... <build> .... <project>
Configuration
| Parameter | Default Value | System Property Overwrite | Description |
|---|---|---|---|
| defaultStartLevel | 30 | sling.assemblies.startlevel.default | The default start level for bundles not listed in the startLevels property. Valid values are integers in the range [1 .. Integer.MAX_VALUE]. |
| startLevels | – | – | Startlevel mappings for included artifacts. Indexed by <groupId>.<artifactId>, value is numeric startlevel [1 .. Integer.MAX_VALUE] |
| versionPolicies | – | – | Version mapping for included artifacts. Indexed by <groupId>.<artifactId>, value is a policy string, which is either strict, the defualt value or latest". See notes for more information. |
Notes
Bundles listed in the sling_install.properties file are referred to by their bundle symbolic name and a version range. Depending on the versionPolicy applied to the bundle, this version range is specified such that only bundles with the same major and minor number as defined by the dependency are accepted or that any version equal to or higher to the specified dependency is accepted. Requiring the same major and minor version number is defined by the strict policy while accepting any version higher than or equal to the declared one is defined by the latest policy. The defualt policy is strict.