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"/>