You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by cz...@apache.org on 2020/03/27 06:27:02 UTC

[sling-org-apache-sling-feature-extension-apiregions] branch master updated: Move api region documentation to extension

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-feature-extension-apiregions.git


The following commit(s) were added to refs/heads/master by this push:
     new e264d9f  Move api region documentation to extension
e264d9f is described below

commit e264d9f055d1fe780811c52ae98c6b32c5cc9587
Author: Carsten Ziegeler <cz...@apache.org>
AuthorDate: Fri Mar 27 07:26:35 2020 +0100

    Move api region documentation to extension
---
 README.md           | 16 ++++++-------
 docs/api-regions.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index bd06f86..188c987 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,8 @@
 
 # Apache Sling API Regions extension
 
-This component contains extensions relating to the API Regions component. For more information about API Regions see
-https://github.com/apache/sling-org-apache-sling-feature/blob/master/apicontroller.md
+This component contains extensions relating to the API Regions component.
+Read the documentation about [API Regions](docs/api-regions.md) for more information.
 
 The following extensions are registered via the ServiceLoader mechanism:
 
@@ -18,7 +18,7 @@ Merge handlers are called when features are merged during the aggregation proces
 
 This component also contains Feature Model Analysers they are contributed through the Service Loader mechanism to the set of Analysers.
 
-These analysers relate to API Region definitions in Feature Models. 
+These analysers relate to API Region definitions in Feature Models.
 
 * `api-regions`: This analyser ensures that packages listed as exports in API-Regions sections are actually exported by a bundle that's part of the feature.
 
@@ -26,12 +26,12 @@ These analysers relate to API Region definitions in Feature Models.
   * Configuration parameters:
   * `exporting-apis`: the name of the region that provides the visible APIs.
   * `hiding-apis`: the name of the region that is 'hidden' i.e. not as visible as the exporting one. The
-packages in the `exporting-api` cannot depend on any packages from this region. 
+packages in the `exporting-api` cannot depend on any packages from this region.
 
 * `api-regions-duplicates`: This analyser ensures that packages are only listed in one region
 in a given feature. If the same package is listed in multiple regions this will be an error.
 
-* `api-regions-check-order`: This analyser checks that regions are defined in the specified 
+* `api-regions-check-order`: This analyser checks that regions are defined in the specified
 order and that the same region is only declared once. Later regions inherit the packages
 expose in earlier regions in the list, so the order is important.
   * Configuration parameters:
@@ -41,9 +41,9 @@ order must be obeyed.
 * `api-regions-crossfeature-dups`: This analyser checks whether there are exported packages in a feature model
 that does _not_ opt in to the API Regions (i.e. it does not have an API-Regions section) that overlap with exported
 packages from API regions in other feature models. It can prevent against unwanted results when packages are
-exported from the outside which should be exported from an API Region. 
-This analyser only provides a useful result when run on 
-an aggregate feature model, i.e. a feature model that was created by aggregating a number of other feature models. It uses the 
+exported from the outside which should be exported from an API Region.
+This analyser only provides a useful result when run on
+an aggregate feature model, i.e. a feature model that was created by aggregating a number of other feature models. It uses the
 `feature-origins` metadata to find the features that bundles were initially declared in. It then matches this with the `feature-origins` found in the `api-regions` section. Exports from  bundles from features that don't
 declare `api-regions` are compared to declared exports in the `api-regions` section. If there is overlap an error
 is reported.
diff --git a/docs/api-regions.md b/docs/api-regions.md
new file mode 100644
index 0000000..412d8ea
--- /dev/null
+++ b/docs/api-regions.md
@@ -0,0 +1,66 @@
+# API Regions
+
+If you're assembling a platform (in contrast to a final application) out of several features and provide this platform for customers to build their application on top of, additional control of the API provided by the platform is needed. The bundles within the features provide all kinds of APIs but you might not want to expose all of these as extension points. You would rather want to use some of them internally within either a single feature or share within your platform features.
+
+# Visibility of API
+
+A feature exports some api, however there are different types of clients of the API:
+
+* Bundles shipped as part of the platform
+* Application bundles using the platform
+
+We can generalize this by saying that API is either globally visible (to every client) or only visible to features within the same context. Usually this is referred to as a "region": The platform spawns its own region and a customer application has its own region, too. In theory there could be several customer applications running in the same framework on top of the platform, and each application has its own region.
+
+Without any further information, API is globally visible by default. However, for platform features we want the opposite as we want to ensure that newly added API is not visible to all bundles by default.
+
+A feature can have an additional extension JSON named api-regions. The following example exposes some packages to the global region and an additional package to the platform region. Exports declared earlier in the api-regions array also apply to later elements in the array, so the `platform` region also contains all exports declared for the `global` region.
+
+Note that the `global` region is a predefined region that exports the listed packages to everyone. Other region names can be chosen freely. Packages listed in these other regions are only exposed to bundles in features that are in the same region.
+
+    "api-regions:JSON|optinal" : [
+        {
+            "name": "global",
+            "exports": [
+                "# Export Sling's resource API in the global region",
+                "org.apache.sling.resource.api",
+                "org.apache.sling.resource.api.adapter",
+                "org.apache.sling.resource.api.auth",
+                "org.apache.sling.resource.api.request",
+                "org.apache.sling.resource.api.resource"
+            ]
+        },{
+            "name": "platform",
+            "exports": [
+                "# Export the scheduler API in the platform region.",
+                "# All exports in earlier regions defined here also apply.",
+                "org.apache.sling.commons.scheduler"
+            ]
+        }
+    ]
+
+Of course the above mentioned packages need to be exported by some bundle within the feature.
+By exporting packages to a given region, a feature automatically also sees all packages available to that region (or regions).
+
+A feature can also just consume packages from a region, without having to export any packages to it. This can be done by exporting an empty list of packages. For example:
+
+    "api-regions:JSON|optional" : [
+        {
+            "name": "platform",
+            "exports": []
+        }
+    ]
+
+If the api-regions extension is missing or the api-regions information is missing, it is assumed that all packages are exported to the "global" region and all packages in the global region are visible to the feature.
+
+If a feature exports no packages and only wants to have visibility of packages from the global region, this can be specified as follows:
+
+    "api-regions:JSON|optional" : [
+        {
+            "name": "global",
+            "exports": []
+        }
+    ]
+
+To support feature inheritance, [this module](../README.md) containing an extension handler must be registered which will merge the extension.
+
+A number of API region related analysers/validators exist. Documentation can be found here: https://github.com/apache/sling-org-apache-sling-feature-analyser . These can be run as part of the 'analyse-features' goal with the [slingfeature-maven-plugin](https://github.com/apache/sling-slingfeature-maven-plugin#analyse-features-analyse-features).