JCRVLT-694 Document OSGi support (#90)
diff --git a/src/main/java/org/apache/jackrabbit/filevault/maven/packaging/mojo/GenerateMetadataMojo.java b/src/main/java/org/apache/jackrabbit/filevault/maven/packaging/mojo/GenerateMetadataMojo.java
index 5cb909d..888f8b4 100644
--- a/src/main/java/org/apache/jackrabbit/filevault/maven/packaging/mojo/GenerateMetadataMojo.java
+++ b/src/main/java/org/apache/jackrabbit/filevault/maven/packaging/mojo/GenerateMetadataMojo.java
@@ -335,7 +335,8 @@
private String importPackage;
/**
- * Defines the path under which the embedded bundles are placed. defaults to '/apps/bundles/install'
+ * Defines the default parent directory path in the package ZIP archive which contains the embedded bundles ({@code /} needs to be used as file separator).
+ * Must be relative to root entry {@code jcr_root}. Defaults to {@code apps/bundles/install}.
*/
@Parameter(property = "vault.embeddedTarget")
private String embeddedTarget;
@@ -355,7 +356,7 @@
* <tr><td>{@code filter}</td><td>{@link Boolean}</td><td>If set to {@code true} adds the embedded artifact location to the package's filter. Default = {@code false}.</td></tr>
* <tr><td>{@code isAllVersionsFilter}</td><td>{@link Boolean}</td><td>If {@code filter} is {@code true} and this is {@code true} as well, the filter entry will contain all versions of the same artifact (by creating an according filter pattern). Default = {@code false}.</td></tr>
* <tr><td>{@code excludeTransitive}</td><td>{@link Boolean}</td><td>If {@code true} only filters on direct dependencies (not on transitive ones). Default = {@code false}.</td></tr>
- * <tr><td>{@code target}</td><td>{@link String}</td><td>The parent folder location in the package where to place the embedded artifact. Falls back to {@link #embeddedTarget} if not set.</td></tr>
+ * <tr><td>{@code target}</td><td>{@link String}</td><td>The parent directory path in the package ZIP archive where to place the embedded artifact ({@code /} needs to be used as file separator). Must be relative to root entry {@code jcr_root}. Falls back to {@link #embeddedTarget} if not set.</td></tr>
* </table>
* All fields are optional. All filter criteria is concatenated with AND logic (i.e. every criterion must match for a specific dependency to be embedded).
* <br>
@@ -1028,7 +1029,7 @@
targetPath = embeddedTarget;
if (targetPath == null) {
final String loc = (prefix.length() == 0)
- ? "/apps/"
+ ? "apps/"
: prefix;
targetPath = loc + "bundles/install/";
getLog().info("No target path set on " + emb + "; assuming default " + targetPath);
@@ -1036,7 +1037,7 @@
}
targetPath = makeAbsolutePath(targetPath);
- targetPath = Constants.ROOT_DIR + "/" + targetPath;
+ targetPath = Constants.ROOT_DIR + targetPath;
targetPath = FileUtils.normalize(targetPath);
if (!targetPath.endsWith("/")) {
targetPath += "/";
diff --git a/src/site/markdown/osgi.md b/src/site/markdown/osgi.md
new file mode 100644
index 0000000..1fbff16
--- /dev/null
+++ b/src/site/markdown/osgi.md
@@ -0,0 +1,41 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# OSGi Support
+
+Although neither the [JCR specification](https://s.apache.org/jcr-2.0-spec) and nor the FileVault serialization format natively support OSGi bundles and configurations those are still supported to be automatically deployed from a certain repository location through 3rd party modules. This allows to embed them also in content packages so that the full code and content belonging to an OSGi application based on Apache Sling can be wrapped in a single content package.
+
+## Bundles and Configurations
+
+Embedding OSGi bundles and configurations is possible in the JCR (and therefore also in FileVault Content Packages). If they follow a certain format and location they can be automatically deployed/extracted into an OSGi feature model with either
+1. [Sling OSGi Installer](https://sling.apache.org/documentation/bundles/osgi-installer.html) and its [JCR Installer Provider](https://sling.apache.org/documentation/bundles/jcr-installer-provider.html) or
+2. [Sling Content-Package to Feature Model Converter](https://github.com/apache/sling-org-apache-sling-feature-cpconverter).
+
+For details on the OSGi configuration format refer to [Configuration Serialization Formats](https://sling.apache.org/documentation/bundles/configuration-installer-factory.html#configuration-serialization-formats). Bundles are embedded as simple files (i.e. `nt:file` nodes).
+
+## Packages
+
+Although only useful for edge cases (e.g. to install a package only on Sling distributions with a certain [run mode](https://sling.apache.org/documentation/bundles/sling-settings-org-apache-sling-settings.html)) also content packages can be embedded in container packages. The difference to regular sub packages is that those are not installed synchronously along with the container package, but are being picked up asynchronously through the JCR Installer Provider and then being queued for installation through the OSGi installer via its [Content Package Installer Factory](https://sling.apache.org/documentation/bundles/content-package-installer-factory.html).
+
+## Repository Location
+
+By default the Sling JCR Installer Provider and Sling Content-Package to Feature Model Converter only consider embedded bundles, configurations and packages inside the nodes `/libs/../install`/`/apps/../install` or `/libs/../install`/`/apps/../config` optionally suffixed by `.` followed by one or multiple run modes.
+
+## Maven Dependencies
+
+The FileVault Package Maven plugin supports automatically embedding OSGi bundles or packages in the right location in the generated package which are filtered from the project's Maven dependencies through its [`embeddeds` parameter](generate-metadata-mojo.html#embeddeds).
+It needs to be ensured that the embedded target path is set accordingly for the Sling JCR Installer Provider to pick it up.
diff --git a/src/site/site.xml b/src/site/site.xml
index eb6c186..20c1118 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -36,6 +36,7 @@
<item name="Validators" href="validators.html"/>
<item name="Classifier Support" href="classifiers.html"/>
<item name="Filtering" href="filtering.html"/>
+ <item name="OSGi" href="osgi.html"/>
</menu>
<menu ref="modules"/>
<menu ref="reports" inherit="bottom"/>
