This is an automated email from the ASF dual-hosted git repository.
bdelacretaz pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-capabilities-jcr.git
The following commit(s) were added to refs/heads/master by this push:
new 8fe3318 Flesh out README
8fe3318 is described below
commit 8fe3318cc3232cc53d81144accb9db8239491dd0
Author: Bertrand Delacretaz <[email protected]>
AuthorDate: Thu Nov 1 15:51:02 2018 +0100
Flesh out README
---
README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 47 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index 7f832ac..c95967a 100644
--- a/README.md
+++ b/README.md
@@ -7,10 +7,54 @@ Sling Capabilities - JCR sources
This module is part of the [Apache Sling](https://sling.apache.org) project.
-It provides information about the JCR repository to the Sling Capabilities
module.
+It provides information about the JCR repository to the [Sling
Capabilities](https://github.com/apache/sling-org-apache-sling-capabilities)
module.
It is implemented separately to avoid making the core module dependent on JCR
APIs.
-TODO: complete this.
+Usage
+-----
+For now, this module's `SearchSource` provides just one capability that
indicates whether the Oak similarity search feature is available. Here's
typical JSON output of the `CapabilitiesServlet` when this source is active:
-TODO: add a link to these modules to the sling website bundles page.
+ {
+ "org.apache.sling.capabilities": {
+ "data": {
+ "org.apache.sling.jcr.search": {
+ "similarity.search.active": "false"
+ }
+ }
+ }
+ }
+
+To compute this value, the `SearchSource` needs to make a JCR query to find
out whether similarity search is available - that is the case if there is at
least one Oak index configuration which has `@useInSimilarity = true`.
+
+That query is configurable in the `SearchSource` component, with a default
value that should work for common cases.
+
+The cache lifetime of that value in the `SearchSource` component is also
configurable, with a default of 60 seconds. The component caches the query
result for that amount of time to avoid making too many queries.
+
+To execute this query, the `SearchSource` uses a Service User that needs read
access under `/oak:index`.
+
+The following feature model excerpt can be used to set that up. It also
creates a `/var/capabilities/public` path that every user can read. Resources
with the `sling/capabilities` resource type can be created under that path to
provide access to the capabilities. See the Capabilities module documentation
for more information.
+
+ "configurations": {
+
"org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended~cq-capabilities-jcr":
{
+ "user.mapping": [
+ "org.apache.sling.capabilities.jcr:search=[capabilities-search]"
+ ]
+ },
+ "org.apache.sling.capabilities.internal.CapabilitiesServlet": {
+ "resourcePathPatterns" : "/var/capabilities/.*"
+ }
+ },
+ "repoinit:TEXT|true": [
+ "create service user capabilities-search",
+ "",
+ "set ACL for capabilities-search",
+ "allow jcr:read on /oak:index",
+ "end",
+ "",
+ "create path /var/capabilities/public(nt:unstructured)",
+ "",
+ "set ACL on /var/capabilities/public",
+ "allow jcr:read for everyone",
+ "end"
+ ]
