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/04/28 14:53:51 UTC
[sling-org-apache-sling-feature] branch master updated: Update
feature docs
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.git
The following commit(s) were added to refs/heads/master by this push:
new b02b7e2 Update feature docs
b02b7e2 is described below
commit b02b7e21a6def8d3381d9a27db503cf4b7571a4d
Author: Carsten Ziegeler <cz...@apache.org>
AuthorDate: Tue Apr 28 14:13:56 2020 +0200
Update feature docs
---
docs/features.md | 38 +++++++++++++++++++++-----------------
1 file changed, 21 insertions(+), 17 deletions(-)
diff --git a/docs/features.md b/docs/features.md
index 835cbf6..52e5933 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -1,6 +1,7 @@
# Features
A feature is the central entity for the Feature Model. A feature is described through a JSON object and can contain:
+
* Metadata like a unique identifier, description etc.
* OSGi bundles
* OSGi configurations
@@ -13,7 +14,7 @@ Each feature must specify a unique identifier. Other attributes like `title`, `d
## Feature Identity
-A feature has a unique identifier. Maven coordinates (https://maven.apache.org/pom.html#Maven_Coordinates) provide a well defined and accepted way of uniquely defining such an id. The coordinates include at least a group id, an artifact id, a version and optionally a type and classifier.
+A feature has a unique identifier. [Maven coordinates](https://maven.apache.org/pom.html#Maven_Coordinates) provide a well defined and accepted way of uniquely defining such an id. The coordinates include at least a group id, an artifact id, a version and optionally a type and classifier.
While group id, artifact id, version and the optional classifier can be freely choosen for a feature, the type/packaging is defined as `slingosgifeature`.
@@ -26,7 +27,7 @@ Maven coordinates are used to define the feature id and to refer to artifacts co
In some cases only the coordinates are specified as a string in one of the above mentioned formats. In other cases, the artifact is described through a JSON object. In that case, the *id* property holds the coordinates in one of the formats.
-```
+```json
Example for specifying a feature id using a Maven id:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0"
@@ -44,7 +45,7 @@ Same id specified as a Maven url:
Features are defined as a JSON object. An example feature file can be found here: [feature-model.json](feature-model.json)
and the JSON Schema for feature files is available from here: [Feature-1.0.0.schema.json](../src/main/resources/META-INF/feature/Feature-1.0.0.schema.json).
-Comments in the form of [JSMin (The JavaScript Minifier)](https://www.crockford.com/javascript/jsmin.html) comments are supported, that is, any text on the same line after // is ignored and any text between /* */ is ignored.
+Comments in the form of [JSMin (The JavaScript Minifier)](https://www.crockford.com/javascript/jsmin.html) comments are supported, that is, any text on the same line after `//` is ignored and any text between `/* */` is ignored.
Java API for Serialization/Deserialization into/from this format is part of this module.
@@ -52,13 +53,13 @@ Java API for Serialization/Deserialization into/from this format is part of this
Features typically declare one or more bundles that provide the behaviour of the feature. The bundles are not stored inside the feature but referenced via their Maven coordinates in the `bundles` section of the feature model. The bundles are defined using an array. Each bundle is referenced either by a string value in that array or by a JSON object which at least must have an `id` property for the bundle coordinates. Additional metadata can also be placed inside that object. It is possib [...]
-```
+```json
A feature with bundles:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
"bundles" : [
// defining a bundle by just using the id
- "org.apache.sling:org.apache.sling.api:2.1.14",
+ "org.apache.sling:org.apache.sling.api:2.1.14",
// defining a bundle by using an object
{
"id" : "org.apache.sling:org.apache.sling.engine:2.5.0",
@@ -79,7 +80,7 @@ specification](https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurat
The configuration section contains set of configuration dictionaries each with a `persistence identifier` (PID) key to target a specific PID in the `Configuration Admin Service` and zero or more configuration values for this PID. Factory configurations can be addressed using the `factory PID` and a name by starting with the factory PID, appending a tilde, and then appending the name. This ensures a well-known name for the factory configuration instance. In the case of single configuratio [...]
-```
+```json
A feature with configurations:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -105,7 +106,7 @@ In most cases, configurations belong to a bundle. The most common use case is a
Instead of defining configurations globally for the feature as seen above, a configuration can be specified as part of a bundle.
-```
+```json
A feature with a configuration attached to a bundle:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -120,14 +121,14 @@ A feature with a configuration attached to a bundle:
}
}
]
-```
}
+```
## OSGi Framework properties
Apart from OSGi configurations, sometimes OSGi framework properties are used for configurations. Framework properties are key value pairs where the value is a string. They can be specified with the 'framework-properties' key in the feature:
-```
+```json
A feature with framework properties:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -144,7 +145,7 @@ In order to avoid a concept like *Require-Bundle* a feature does not explicitly
Features can also explicitly declare additional requirements they have over and above the ones coming from the bundles. This is done in the `requirements` section of the feature. Each requirement has a namespace and optional directives and attributes.
-```
+```json
A feature declaring additional requirements:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -161,7 +162,7 @@ A feature declaring additional requirements:
Features can declare additional capabilities that are provided by the feature in addition to the capabilities provided by the bundles. For example a number of bundles might together provide an `osgi.implementation` capability, which is not provided by any of those bundles individually. The Feature can be used to add this capability to the provided set. These additional capabilities are specified in the `capabilities` section of the feature. Each capability has a namespace and optional di [...]
-```
+```json
A feature declaring additional capabilities:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -191,19 +192,20 @@ Custom content can have one of the following formats/types:
* An array of artifacts
The extension can have one of the following states:
+
* 'required' : Required extensions need to be processed by tooling
* 'optional' : Optional extensions might be processed by tooling, for example they might contain environment specific parts
* 'transient': Transient extensions are cache like extensions where tooling can store additional information to avoid reprocessing of down stream tooling. However such tooling must work without the transient extension being available.
Extensions are declared in the feature by adding a JSON structure with a key following this syntax:
-```
+```json
"extention-name:<type>|{optional|required|transient}": JSON Structure
```
For example, the following declaration defines an extension with name `api-regions` using the type `JSON`. The declaration also states that if no plugin is present that knows about this extension it should be ignored and execution should continue.
-```
+```json
"api-regions:JSON|optional" : [
{"name": "global"}
]
@@ -213,7 +215,7 @@ For example, the following declaration defines an extension with name `api-regio
Variables can be declared with the 'variables' key in the feature. This can be used for late binding of values, for example when launching a feature.
-```
+```json
A feature declaring variables:
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -232,7 +234,7 @@ Variables can be used in the values of framework properties and in the values of
Features can be declared _from scratch_ or they can use another pre-existing feature as a prototype. Using a prototype is especially useful to make minor adjustments to an existing feature and use the modified feature instead of the original, for example replacing a single bundle.
-```
+```json
A feature using a prototype:
{
"id" : "org.apache.sling:my-sling-core-feature:slingosgifeature:1.0.0",
@@ -246,6 +248,7 @@ A feature using a prototype:
```
If a feature uses a prototype, the following parts are copied from the prototype into the feature:
+
* Variables
* Bundles
* Configurations
@@ -256,6 +259,7 @@ If a feature uses a prototype, the following parts are copied from the prototype
Then the removal instructions of the prototype object are handled next.
Finally, the contents from the prototype is then overlayed with the definitions from the feature using the prototype. In detail this means:
+
* Variables from the feature overwrite variables from the prototype.
* A clash of artifacts (such as bundles) between the prototype and the feature is resolved by picking the version from the feature, not its prototype. Artifact clashes are detected based on Maven Coordinates, not on the content of the artifact. So if a prototype defines a bundle with artifact ID `org.sling:somebundle:1.2.0` and the feature itself declares `org.sling:somebundle:1.0.1` in its `bundles` section, the bundle with version `1.0.1` is used.
* Configurations will be merged by default, the ones from the feature potentially overwriting configurations from the prototype:
@@ -269,7 +273,7 @@ Finally, the contents from the prototype is then overlayed with the definitions
A feature might be self-contained, for example a feature describing a complete application has no external dependencies. Such a feature can be marked as `complete` indicating
that all its dependencies and requirements are met by capabilities inside the feature.
-```
+```json
A feature marked as complete
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
@@ -279,7 +283,7 @@ A feature marked as complete
Features can also be marked as `final`. Such a feature cannot be used as a prototype for another feature, similar to the final classifier on a class file in Java.
-```
+```json
A feature marked as final
{
"id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",