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 <[email protected]>
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",
