[sling-org-apache-sling-jcr-base] branch master updated: Add info about RepositoryMount and add javadoc

[cz...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-jcr-base.git


The following commit(s) were added to refs/heads/master by this push:
     new e8fe5e0  Add info about RepositoryMount and add javadoc
e8fe5e0 is described below

commit e8fe5e004b5af1802bb2a76dbbb583a437f848ee
Author: Carsten Ziegeler <cz...@apache.org>
AuthorDate: Mon Aug 26 13:34:30 2019 +0200

    Add info about RepositoryMount and add javadoc
---
 README.md                                          | 20 ++++++++++++++-
 .../apache/sling/jcr/base/spi/RepositoryMount.java | 29 ++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 30aa2ab..9a6ccda 100644
--- a/README.md
+++ b/README.md
@@ -6,4 +6,22 @@
 
 This module is part of the [Apache Sling](https://sling.apache.org) project.
 
-The JCR base bundle provides JCR utility classes.
+The JCR base bundle provides JCR utility classes and support for repository mounts.
+
+# Repository Mount
+
+Apache Sling provides support for pluggable resource providers. While this allows for a very flexible and efficient
+integration of custom data providers into Sling, this integration is done on Sling's resource API level. Legacy code
+which may rely on being able to adapt a resource into a JCR node and continue with JCR API will not work with such
+a resource provider.
+
+To support legacy code, this bundle provides an SPI interface *org.apache.sling.jcr.base.spi.RepositoryMount* which
+extends *JackrabbitRepository* (and through this *javax.jcr.Repository*). A service registered as *RepositoryMount* registers
+itself with the service registration property *RepositoryMount.MOUNT_POINTS_KEY* which is a String+ property containing
+the paths in the JCR tree where the mount takes over the control of the JCR nodes. The *RepositoryMount* can registered
+at a single path or multiple.
+
+As *RepositoryMount* extends *JackrabbitRepository* the implementation of a mount needs to implement the whole JCR API.
+This is a lot of work compared to a *ResourceProvider*, therefore a *RepositoryMount* should only be used if legacy
+code using JCR API needs to be supported.
+
diff --git a/src/main/java/org/apache/sling/jcr/base/spi/RepositoryMount.java b/src/main/java/org/apache/sling/jcr/base/spi/RepositoryMount.java
index f009877..350aa19 100644
--- a/src/main/java/org/apache/sling/jcr/base/spi/RepositoryMount.java
+++ b/src/main/java/org/apache/sling/jcr/base/spi/RepositoryMount.java
@@ -20,8 +20,37 @@ package org.apache.sling.jcr.base.spi;
 
 import org.apache.jackrabbit.api.JackrabbitRepository;
 
+/**
+ * A {@code RepositoryMount} works similar to a resource provider and allows to
+ * connect custom data. But it works on the lower JCR API level. This way legacy
+ * code using JCR API can be supported as well. However, implementors of this
+ * interface need to implement the full JCR API - which is more complex than the
+ * resource provider. Therefore a repository mount should only be used for
+ * special cases where legacy code using JCR API is used.
+ * <p>
+ * The JCR base implementation supports only a single {@code RepositoryMount}.
+ * In case of several registrations, the one with the highest service ranking
+ * will be used.
+ * <p>
+ * The {@code RepositoryMount} must implement
+ * {@link JackrabbitRepository#login(javax.jcr.Credentials, String, java.util.Map)}
+ * in order to login against the custom data provider. It will get access to the
+ * JCR session through {@link #PARENT_SESSION_KEY}.
+ */
 public interface RepositoryMount extends JackrabbitRepository
 {
+    /**
+     * The key of the attribute holding the parent session when
+     * {@link JackrabbitRepository#login(javax.jcr.Credentials, String, java.util.Map)
+     * is called.
+     */
     String PARENT_SESSION_KEY = "org.apache.sling.jcr.base.RepositoryMount.PARENT_SESSION";
+
+    /**
+     * The repository needs to register itself with this property which is a String+
+     * property defining the paths in the JCR tree where the handling of the nodes
+     * is delegated to the mounter. The mounter can mount itself at various points
+     * in the JCR repository.
+     */
     String MOUNT_POINTS_KEY = "org.apache.sling.jcr.base.RepositoryMount.MOUNT_POINTS";
 }