You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by kw...@apache.org on 2023/03/10 19:24:13 UTC
[jackrabbit-filevault-package-maven-plugin] 01/01: JCRVLT-694 Document OSGi support
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/document-osgi-support
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault-package-maven-plugin.git
commit d8ee249e25676f561e51d0442d16c4a4260ac013
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Fri Mar 10 20:24:05 2023 +0100
JCRVLT-694 Document OSGi support
Clarify embedded target
---
.../maven/packaging/mojo/GenerateMetadataMojo.java | 4 +--
src/site/markdown/osgi.md | 37 ++++++++++++++++++++++
src/site/site.xml | 1 +
3 files changed, 40 insertions(+), 2 deletions(-)
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 d9296f2..dc37d3d 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
@@ -334,7 +334,7 @@ public class GenerateMetadataMojo extends AbstractMetadataPackageMojo {
private String importPackage;
/**
- * Defines the path under which the embedded bundles are placed. defaults to '/apps/bundles/install'
+ * Defines the parent directory path in the package ZIP archive which contains the embedded bundles ({@code /} needs to be used as file separator). Defaults to {@code /apps/bundles/install}.
*/
@Parameter(property = "vault.embeddedTarget")
private String embeddedTarget;
@@ -354,7 +354,7 @@ public class GenerateMetadataMojo extends AbstractMetadataPackageMojo {
* <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). 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>
diff --git a/src/site/markdown/osgi.md b/src/site/markdown/osgi.md
new file mode 100644
index 0000000..656f733
--- /dev/null
+++ b/src/site/markdown/osgi.md
@@ -0,0 +1,37 @@
+<!--
+ 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 the JCR spec and also the FileVault serialization format don't natively support OSGi bundles and configurations, they are still supported through 3rd party modules.
+
+## 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).
+
+## Repository Location
+
+By default the Sling JCR Installer Provider and Sling Content-Package to Feature Model Converter only consider bundles and configurations 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 placing OSGi bundles 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"/>