Apache Sling Feature Model API Regions Extension

Clone this repo:
  1. afbe3d4 SLING-10307 : Report warnings/errors on configurations by Carsten Ziegeler · 5 days ago master
  2. 0056295 [maven-release-plugin] prepare for next development iteration by Carsten Ziegeler · 3 weeks ago
  3. 05294b4 [maven-release-plugin] prepare release org.apache.sling.feature.extension.apiregions-1.2.0 by Carsten Ziegeler · 3 weeks ago org.apache.sling.feature.extension.apiregions-1.2.0
  4. 438db28 Use latest release feature model 1.2.2 by Carsten Ziegeler · 3 weeks ago
  5. d6459ef Update documentation and correct package export version by Carsten Ziegeler · 5 weeks ago

Apache Sling

Build Status Test Status Coverage Sonarcloud Status JavaDoc Maven Central feature License

Apache Sling API Regions Extension for the Feature Model

This component contains extensions relating to the API Regions component. Read the documentation about API Regions for more information.

Feature Model Analysers

This component also contains Feature Model Analysers. They are contributed through the Service Loader mechanism to the set of Analysers.

Documentation can be found here: Apache Sling Feature Analyser . These can be run as part of the ‘analyse-features’ goal with the slingfeature-maven-plugin.

These analysers relate to Java 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.

  • api-regions-dependencies: This analyser checks that packages in API regions listed earlier in the API-Regions declaration have no dependency on API regions listed later in the list. This include Import-Package style dependencies and also uses-clause type dependencies. Later API regions also include packages from earlier declared API regions, but not the other way around.

    • 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.
  • 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-exportsimports: Checks bundle import/export package statements for consistency and completeness. If API Regions are used this analyser includes this information as part of the check, to ensure that bundles don't import packages of which they have no visibility because of API Regions restrictions.

  • 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:
    • order: A comma separated list of the region names declaring the order in which they should be found. Not all regions declared must be present, but if they are present this order must be obeyed.
  • api-regions-crossfeature-dups: This analyser checks whether the same package is exported into the same API Region from multiple features. It can prevent against unwanted results when packages are exported by a bundle in a platform feature in an API Region such as global as well as by a non-platform bundle. 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.

    • Configuration parameters:
    • regions: a comma separated list of regions to check. If not specified all regions found are checked. This configuration item can be used to exclude certain regions from the check.
    • definingFeatures: comma separated list the features IDs that are allowed to define the API. If overlapping exports are done into the selected regions from other features this will cause an error. The suffix * is supported as a wildcard at the end of the feature ID. If this configuration is not specified, the list of defining features is built up from all features that opt-in to the API regions and ones that don't opt-in are assumed to be non-defining.
    • warningPackages: if packages listed here are found to overlap, a warning instead of an error is reported. Supports either literal package names (e.g. javax.servlet) or wildcards with an asterisk at the end (e.g. javax.*).
    • ignoredPackages: packages listed here are completely ignored in the analysis. Supports literal package names or wildcards with an asterisk at the end.

These analysers relate to Configuration API Region definitions in Feature Models:

  • configuration-api : This analyser validates the OSGi configurations and framework properties based on the configuration API described in an extension.

Extensions

The following extensions are registered via the ServiceLoader mechanism:

org.apache.sling.feature.builder.MergeHandler

Merge handlers are called when features are merged during the aggregation process:

  • APIRegionMergeHandler - This handler knows how to merge API Regions extensions
  • ConfigurationApiMergeHandler - This handlers knows how to merge Configuration API extensions

Additional Extensions

The following extensions are also implemented by this component and made available through the Service Loader mechanism:

  • org.apache.sling.feature.launcher.spi.extensions.ExtensionHandler
  • org.apache.sling.feature.launcher.spi.Launcher
  • org.apache.sling.feature.scanner.spi.ExtensionScanner