SLING-10808 - Generate scripting capabilities from Jackrabbit FileVault content packages
* documented extraction of scripting capabilities from content packages
diff --git a/pom.xml b/pom.xml
index 211a764..f1172ba 100644
--- a/pom.xml
+++ b/pom.xml
@@ -47,7 +47,7 @@
<properties>
<sling.java.version>8</sling.java.version>
<maven.version>3.6.0</maven.version>
- <site.jira.version.id>12344664,12347157,12348422,12350010</site.jira.version.id>
+ <site.jira.version.id>12344664,12347157,12348422,12350010,12350474,12350606</site.jira.version.id>
<maven.site.path>${project.artifactId}-archives/${project.artifactId}-LATEST</maven.site.path>
<project.build.outputTimestamp>2021-08-31T07:51:46Z</project.build.outputTimestamp>
<github.project.id>apache/sling-scriptingbundle-maven-plugin</github.project.id>
@@ -286,4 +286,11 @@
</plugins>
</reporting>
+ <distributionManagement>
+ <site>
+ <id>staging</id>
+ <url>file:${project.build.directory}/staging</url>
+ </site>
+ </distributionManagement>
+
</project>
diff --git a/src/site/markdown/bnd.md b/src/site/markdown/bnd.md
index 9ff7a57..624f25e 100644
--- a/src/site/markdown/bnd.md
+++ b/src/site/markdown/bnd.md
@@ -1,3 +1,5 @@
+# bnd Plugin
+
Starting with version `0.3.0`, the JAR also provides a [bnd plugin](https://bnd.bndtools.org/chapters/870-plugins.html). The simplest configuration (where the defaults are used)
would look like:
@@ -26,4 +28,22 @@
properties. Multiple values need to be provided as a quoted comma-separated values list (e.g.
`sourceDirectories="src/main/scripts,src/main/resources/javax.script"`, `scriptEngineMappings="html:htl,js:rhino"`).
-For a general usage description please refer to [Usage](usage.html).
\ No newline at end of file
+For a general usage description please refer to [Usage](usage.html).
+
+## Working with [FileVault](https://jackrabbit.apache.org/filevault/index.html) content package projects
+
+Starting with version 0.5.0, the bnd plugin can be used to scan [FileVault](https://jackrabbit.apache.org/filevault/index.html)
+content package projects. The same concepts from the [generic usage](usage.html) instructions apply, with two differences:
+
+ 1. Since content packages contain the serialisation of resource properties, the Docview `.content.xml`
+ files will be parsed and the encountered `sling:resourceSuperType` properties will be directly used to generate the appropriate
+ OSGi capabilities, making the `extends` file redundant (besides, the `extends` files should not be packed in a content package
+ anyways).
+ 2. When delegating to another resource type, you can define this relationship in your component's
+ Docview `.content.xml` file, by using a new multi-value String property - `sling:requiredResourceTypes`. This property is only used
+ by the bnd plugin to generate the correct `Require-Capability` header values. An example is available
+ [here](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/blob/master/examples/org-apache-sling-scripting-content-package-with-bundle-attached/src/main/content/jcr_root/apps/sling/scripting/example-cp/hello/.content.xml).
+ When using the `sling:requiredResourceTypes` Docview property, the `requires` file is redundant.
+
+A trivial example of the bnd plugin configured to extract capabilities from a content package, together with the required plugins to also
+generate a `jar` file with the precompiled scripts can be seen [here](https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/blob/master/examples/org-apache-sling-scripting-content-package-with-bundle-attached/pom.xml).
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index b1bec3e..2cdaa10 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -3,12 +3,14 @@
#set($h3 = '###')
#set($h4 = '####')
-
$h2 Usage
-The plugin can be used either as a regular Maven plugin or as a [bnd plugin](bnd.html).
+The plugin can be used either as a regular Maven plugin or as a [bnd plugin](bnd.html). Its purpose is to extract the capabilities
+required for packaging the scripts (precompiled or not) into an OSGi bundle. Both versions of the plugin can be used for OSGi bundle
+projects, however the [bnd plugin](bnd.html) can also be used with [FileVault](https://jackrabbit.apache.org/filevault/index.html) content
+package projects.
-No matter which approach you choose, the plugin will by default look for scripts in two project directories:
+Both versions of 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
@@ -26,7 +28,8 @@
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).
+ 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
