[sling-whiteboard] branch master updated: README

[bd...@apache.org]

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-whiteboard.git


The following commit(s) were added to refs/heads/master by this push:
     new c14d21c  README
c14d21c is described below

commit c14d21c7c26b463167f9f4c4586ab34cbc3743b6
Author: Bertrand Delacretaz <bd...@apache.org>
AuthorDate: Wed Jun 20 15:34:36 2018 +0200

    README
---
 capabilities/README.md | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/capabilities/README.md b/capabilities/README.md
index e23be1c..27d34da 100644
--- a/capabilities/README.md
+++ b/capabilities/README.md
@@ -1,16 +1,36 @@
 Sling Capabilities Module
 =========================
 
-This is a work in progress for a service that allows for creating Capabilities endpoints
+This servlet provided by this module allows for creating Capabilities HTTP endpoints
 on a Sling instance: Resources that provide information on which services are available,
 version levels etc.
 
-Capabilities are provided by `CapabilitiesSource` services, each of them having a unique
-identifier used to namespace its capabilities, and providing a number of capabilities
-as key/value pairs.
+For now, a single type of endpoint is provided: all Resources which have the
+`sling/capabilities` resource type will return the same set of Capabilities, generated
+by aggregating the output of all active `CapabilitiesSource` services.
 
-The `CapabilitiesServlet` is mounted on the `sling/capabilities` resource type, and produces
-output as shown below, by aggregating the data provided by all `CapabilitiesSource` services.
+This can be easily expanded to multiple sets of Capabilities if needed later on,
+using service properties to group or tag the `CapabilitiesSource` services.
+
+The tests provide simple `CapabilitiesSource` examples, that API is as follows:
+
+    @ProviderType
+    public interface CapabilitiesSource {
+
+        /** @return the namespace to use to group our capabilities.
+         *  That name must be unique in a given Sling instance.
+         */
+        String getNamespace();
+
+        /** @return zero to N capabilities, each being represented by
+         *      a key/value pair.
+         * @throws Exception if the capabilities could not be computed.
+         */
+        Map<String, Object> getCapabilities() throws Exception;
+    }
+
+The `CapabilitiesServlet` produces output as in the example below, where two
+`CapabilitiesSource` services are available:
 
     $ curl -s -u admin:admin http://localhost:8080/tmp/cap.json | jq .
     {