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 2.x and JDK 1.5 or higher. Maven Sling Plugin provides the following goals:
| Goals |
Description |
|---|---|
| sling:deploy | Deploy a OSGi-bundle into a running Sling instance. |
| sling:deploy-file | Deploy a OSGi-bundle into a running Sling instance without requiring a project descriptor file. |
| sling:install | Install a OSGi-bundle into a running Sling instance |
| sling:install-file | Install a OSGi-bundle into a running Sling instance without requiring a project descriptor file. |
| sling:uninstall | Uninstall a 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.0.5-SNAPSHOT</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> <version>2.0.5-SNAPSHOT</version> </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 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 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. It's also possible to HTTP PUT instead of POST for WebDAV.
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 |
| 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 |
| 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) |
| 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 |
| mountByFS | false | sling.mountByFS | To configure FS ResourceProvider for initial content files (useful for testing) |
| 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. |
| 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 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 POSTrequest. 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/sling | sling.url | The URL of the running Sling instance to which the bundle should be uninstalled |
| 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 |
| usePut | false | sling.usePut | In the uninstall goal, a HTTP DELETE will be used. |
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. |