Apache Sling Feature Model API Regions

Clone this repo:
  1. 6ecace9 SLING-12094 - Use GitHub for the Maven scm.url value by Robert Munteanu · 6 months ago master
  2. 942bef5 SLING-11709 - Set up Jira autolinks to all Sling Github projects by Robert Munteanu · 12 months ago
  3. f6ccb19 SLING-11051 - Fixing JavaDoc badge by Dan Klco · 2 years, 3 months ago
  4. 37a9cf1 SLING-10676 - remove SECURITY.md which is not needed by Bertrand Delacretaz · 2 years, 8 months ago
  5. 8bcac99 SLING-10676 - add or update SECURITY.md by Bertrand Delacretaz · 2 years, 8 months ago

Apache Sling

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

This small set of APIs aims to provide to Apache Sling users an easy-to-use layer to manipulate api-regions JSON extensions.

Motivation

The api-regions extensions gained popularity via the APIs Jar MOJO that, for each selected Apache Sling Feature Model file, generates multiple Java Archives, one for each declared section in the api-regions extension, containing declared APIs in each region.

During the time, business intelligence on top of api-regions extension will be required, i.e. analyzing the evolution of each region in each Apache Sling Feature Model file, to see what‘s removed and what’s added (just to mention few operations), so having a single APIs set to manipulate api-regions will be helpful avoiding code redundancies across multiple applications.

Quick how-to

api-regions extensions are generally obtained by parsing the JSON content in the api-regions declaration, i.e. given the following sample region:

[
  {
    "name": "base",
    "exports": [
      "org.apache.felix.inventory",
      "org.apache.felix.metatype"
    ]
  },
  {
    "name": "extended",
    "exports": [
      "org.apache.felix.scr.component",
      "org.apache.felix.scr.info"
    ]
  }
]

then obtaining simple APIs will look like:

import org.apache.sling.feature.Feature;
import org.apache.sling.feature.apiregions.model.ApiRegion;
import org.apache.sling.feature.apiregions.model.ApiRegions;
import org.apache.sling.feature.apiregions.model.io.json.ApiRegionsJSONParser;

...

Feature feature = [somehow obtained]
// parseApiRegions method can be invoked also passing a org.apache.sling.feature.Extension instance
// or a String which represents the JSON structure of an api-regions extension.
ApiRegions regions = ApiRegionsJSONParser.parseApiRegions(feature);

for (ApiRegion region : regions) {
    System.out.println("-" + region.getName());

    for (String api : region) {
        System.out.println(" * " + api);
    }

    System.out.println("--------");
}

That code will output:

- base
 * org.apache.felix.inventory
 * org.apache.felix.metatype
--------
- extended
 * org.apache.felix.scr.component
 * org.apache.felix.scr.info
 * org.apache.felix.inventory
 * org.apache.felix.metatype
--------

Note

Pleas take in account that each declared region in api-regions inherits declared APIs from the previous declared region.

APIs to create regions

Users can also use APIs to manually declare their api-regions instances:

omit imports for brevity;

...

ApiRegions apiRegions = new ApiRegions();
ApiRegion granpa = apiRegions.addNew("granpa");
granpa.add("org.apache.sling.feature.apiregions.model");

ApiRegion father = apiRegions.addNew("father");
father.add("org.apache.sling.feature.apiregions.model.io");

ApiRegion child = apiRegions.addNew("child");
child.add("org.apache.sling.feature.apiregions.model.io.json");

for (ApiRegion region : apiRegions) {
    System.out.println("-" + region.getName());

    for (String api : region) {
        System.out.println(" * " + api);
    }

    System.out.println("--------");
}

That code will output:

- granpa
 * org.apache.sling.feature.apiregions.model
--------
- father
 * org.apache.sling.feature.apiregions.model
 * org.apache.sling.feature.apiregions.model.io
--------
- child
 * org.apache.sling.feature.apiregions.model
 * org.apache.sling.feature.apiregions.model.io
 * org.apache.sling.feature.apiregions.model.io.json
--------

JSON serialization is available as well:

import org.apache.sling.feature.apiregions.model.io.json.ApiRegionsJSONSerializer

...

ApiRegionsJSONSerializer.serializeApiRegions(ApiRegions, System.out);

that will output:

[
  {
    "name":"granpa",
    "exports":[
      "org.apache.sling.feature.apiregions.model"
    ]
  },
  {
    "name":"father",
    "exports":[
      "org.apache.sling.feature.apiregions.model.io"
    ]
  },
  {
    "name":"child",
    "exports":[
      "org.apache.sling.feature.apiregions.model.io.json"
    ]
  }
]