| #set($h1 = '#') |
| #set($h2 = '##') |
| #set($h3 = '###') |
| #set($h4 = '####') |
| |
| |
| $h2 Usage |
| |
| The plugin can be used either as a regular Maven plugin or as a [bnd plugin](bnd.html). |
| |
| No matter which approach you choose, the plugin will by default look for scripts in two project directories: |
| |
| 1. `src/main/scripts` - this folder will contain scripts that will be pre-compiled |
| 2. `src/main/resources/javax.script` - this folder will contain scripts that will be embedded as is |
| |
| The structure in these source directories should then follow the normal way of structuring scripts in an Apache Sling application. For more |
| details, check the [Sling Scripting](https://sling.apache.org/documentation/bundles/scripting.html#resource-script-naming-conventions) |
| page. In addition to the normal way of structuring scripts in the file tree, the plugin provides some additional features: |
| |
| 1. Resource Type Versioning<br/> |
| This works by putting the scripts in a folder that follows this simple naming convention: `<resourceType>/<version>/`. The `<version>` |
| should be a valid semantic version (e.g. `1.0.0`) |
| |
| 2. Defining explicit extends relationships (similar to the `sling:resourceSuperType` property)<br/> |
| An `extends` file in the resource type folder (versioned or not) allows defining this explicit relationship. This file must contain a |
| single line with the `resourceType` used for the `extends` capability attribute followed by a `;version=<version-range>`; in this |
| case, the plugin will set the `extends` attribute to the given `resourceType` and generate a `Require-Capability` for that |
| `resourceType` with the given version range. To generate an optional capability header (when the bundled script extends from |
| a non-bundle, resource script), append `;resolution:=optional` to the line. The line must comply with the OSGI common header syntax from [OSGI Core R7 ยง3.2.4](http://docs.osgi.org/specification/osgi.core/7.0.0/framework.module.html#framework.common.header.syntax). |
| |
| 3. Defining an explicit requirement, without an inheritance relationship (e.g. delegation to another resource type)<br/> |
| A `requires` file (assuming the same conventions and syntax as for the `extends` file) will generate a `Require-Capability` for each |
| line based on the given `resourceType` and version range. |
| |
| 4. The Resource Type can have the form of a path or of a Java package name (e.g. `com.mydomain.components.image`). When the resource type |
| is defined as a package name, the resource type label will be the last subpackage (i.e. for `com.mydomain.components.image`, the |
| resource type label will be `image`). |
| |
| $h3 Defining scripts |
| As an example, let's assume the following layout: |
| ``` |
| src/main/resources/javax.script/ |
| org.foo/1.0.0 |
| foo.POST.html |
| ``` |
| |
| This will generate following `Provide-Capability`: |
| |
| ``` |
| sling.servlet; |
| sling.servlet.resourceTypes:List<String>="org.foo"; |
| sling.servlet.methods:List<String>=POST; |
| version:Version="1.0.0" |
| ``` |
| |
| For more complex examples head over to https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples. |
| |
| $h3 Configure Maven Plugin |
| |
| When used as a Maven plugin, the generated `Require-Capability` and `Provide-Capability` headers values are made available via |
| Maven project properties: |
| |
| ``` |
| ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| ``` |
| |
| That makes it reasonably straightforward to use the plugin by just adding it into your build and use the two properties in the manifest |
| writing instructions of another plugin like the `maven-bundle-plugin`: |
| |
| ``` |
| <plugin> |
| <groupId>${project.groupId}</groupId> |
| <artifactId>${project.artifactId}</artifactId> |
| <version>${project.version}</version> |
| <executions> |
| <execution> |
| <phase>prepare-package</phase> |
| <goals> |
| <goal>metadata</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| <plugin> |
| <groupId>org.apache.felix</groupId> |
| <artifactId>maven-bundle-plugin</artifactId> |
| <extensions>true</extensions> |
| <configuration> |
| <instructions> |
| <Provide-Capability> |
| ${org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability} |
| </Provide-Capability> |
| <Require-Capability> |
| osgi.extender;filter:="(&(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))", |
| ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| </Require-Capability> |
| </instructions> |
| </configuration> |
| </plugin> |
| ``` |
| |
| The `osgi.extender` requirement is mandatory to have the bundle wired up to the Apache Sling Servlets Resolver, but this should be manually |
| defined by the developers, so that their bundle is correctly wired up to whatever version of the Servlets Resolver is available on the |
| destination platform. |