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 503fe88 Update feature model documentation, create clearer structure
503fe88 is described below
commit 503fe88bb2705e9f57afc3f98d1ef73dba1f3a0f
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Mar 26 18:43:20 2020 +0100
Update feature model documentation, create clearer structure
---
readme.md | 189 +++++++++++++++++++++++++++++++++++++-------------------------
1 file changed, 112 insertions(+), 77 deletions(-)
diff --git a/readme.md b/readme.md
index ad28e08..95cbbaf 100644
--- a/readme.md
+++ b/readme.md
@@ -4,107 +4,103 @@
# The Sling OSGi Feature Model
-OSGi is a platform capable of running large applications for a variety of
purposes, including rich client applications,
-server-side systems and cloud and container based architectures.
+OSGi is a platform capable of running large applications for a variety of
purposes, including rich client applications,
+server-side systems and cloud and container based architectures.
-As these applications are generally based on many bundles, describing each
bundle individually in the application
-definition becomes unwieldy once the number of bundles reaches a certain
level. Additionally, OSGi has no mechanism to describe other elements of the
application definition, such as configuration or custom artifacts.
+As these applications are generally based on many bundles, describing each
bundle individually in the application
+definition becomes unwieldy once the number of bundles reaches a certain
level. Additionally, OSGi has no mechanism to describe other elements of the
application definition, such as configuration or custom artifacts.
While bundles already provide a good way to define rather small, coherent
modules, there is often a need to distribute or provision a set of such bundles
together with some configuration. Or if you want to build a set of applications
(for example microservices) which share certain parts
(like a foundation) the need for a higher level building block arises.
-The Sling OSGi Feature Model introduces such a higher level building block to
describe OSGi applications or parts of it that encapsulates
-the details of the various components that the feature is built up from. It
allows the description of an entire OSGi-based application based
-on reusable components and includes everything related to this application,
including bundles, configuration, framework properties, capabilities,
+The Sling OSGi Feature Model introduces such a higher level building block to
describe OSGi applications or parts of it that encapsulates
+the details of the various components that the feature is built up from. It
allows the description of an entire OSGi-based application based
+on reusable components and includes everything related to this application,
including bundles, configuration, framework properties, capabilities,
requirements and custom artifacts.
# Features
-Features are the central concept of the Feature Model. Features are typically
defined in a Feature file which is
-a JSON file. An example feature file can be found here:
https://github.com/apache/sling-org-apache-sling-feature-io/blob/master/design/feature-model.json
-and the JSON Schema for feature files is available from here:
https://github.com/apache/sling-org-apache-sling-feature-io/blob/master/src/main/resources/META-INF/feature/Feature-1.0.0.schema.json.
-Serialization/Deserialization into/from this format is available from
https://github.com/apache/sling-org-apache-sling-feature-io.
-
-All features have a unique identity.
-Features can have an optional `title`, `description`, `vendor` name, `license`.
+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
+* OSGi Framework properties
+* Extensions - a plugin mechanism to add additional information to the feature
-Features typically reference one or more bundles that provide the behaviour of
the feature. These
-bundles may have external dependencies. Dependencies can be satisfied by other
features or bundles.
+## Feature Metadata
-Features can define OSGi Configurations that will be provided into the runtime
and features can also declare additional requirements and capabilities over and
above the ones coming from the bundles
-that are part of the feature.
+Each feature must specify a unique identifier. Other attributes like `title`,
`description`, `vendor` name, and `license` are optional.
-Features can be declared _from scratch_ or they can use another pre-existing
feature as a prototype. In this case
-the new feature starts off as a feature identical to its prototype, with some
exceptions:
+## Feature Identity
-* it does not get the prototype's identity.
-* bundles, configurations and framework properties can be removed from the
prototype, in the `removals` section.
-* anything declared in the feature definition of a feature based on a
prototype adds or overrides to
-what came from the prototype.
+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.
-Features can also be marked as `final` and/or `complete`.
-A `final` feature cannot be used as a prototype for another feature. A feature
marked as `complete` indicates
-that all its dependencies are met by capabilities inside the feature, i.e. it
has no external dependencies.
+While group id, artifact id, version and the optional classifier can be freely
choosen for a feature, the type/packaging is defined as `slingosgifeature`.
-A Feature Launcher can be used to launch features into a running process with
an OSGi Framework.
-The launcher is typically fed with a number of feature files that should be
launched together.
-Overrides for variables defined in the feature models can be provided on the
launcher commandline.
+## Maven Coordinates
-Tooling exists to analyze and validate features, and to aggregate and merge
multiple features into a single
-feature, which can be used to create higher level features from a combination
of lower-level ones. Most of
-the tooling is accessible through the slingfeature-maven-plugin:
https://github.com/apache/sling-slingfeature-maven-plugin
+Maven coordinates are used to define the feature id and to refer to artifacts
contained in the feature, e.g. bundles, content packages or other features.
There are two supported ways to write down such a coordinate:
-The following diagrams show a typical workflow when working with feature files:
+* Using a `Maven id` which uses a colon as a separator for the parts:
*groupId:artifactId[:type[:classifier]]:version* as defined in [Maven
Coordinates](https://maven.apache.org/pom.html#Maven_Coordinates)
+* Using a `Maven URL` : *'mvn:' group-id '/' artifact-id [ '/' [version] [ '/'
[type] [ '/' classifier ] ] ] ]*
-<img src="diagrams/Develop.jpg" width="700"/>
-
-Features are authored as JSON Feature Files.
-The slingfeature-maven-plugin provides analyzers and aggregators that check
features and can combine them into larger features. The maven plugin can also
be used to publish features to a Maven Repository.
+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.
-<img src="diagrams/RunningSystem.jpg" width="700"/>
-To create a running system from a number of feature files, features are
selected from a Maven Repository,
-they are validated for completeness and optionally additional features are
pulled in through the OSGi Resolver
-(not yet implemented). A final system feature has no unresolved dependencies.
It is passed to the Feature Launcher
-along with optional additional features the provide functionality on top of
what is defined in the system feature.
-The Feature Launcher creates a running process containing an OSGi Framework
provisioned with the feature's contents.
-
-## Feature Identity
+```
+Example for specifying a feature id using a Maven id:
+{
+ "id" :
"org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0"
+}
-A feature has a unique id. 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.
+Same id specified as a Maven url:
+{
+ "id" :
"org.apache.sling/org.apache.sling.core.feature/1.0.0/slingosgifeature"
+}
-While group id, artifact id, version and the optional classifier can be freely
choosen for a feature, the type/packaging is defined as `slingosgifeature`.
+```
-## Maven Coordinates
+## Feature File Format
-Maven coordinates are used to define the feature id and to refer to artifacts
contained in the feature, e.g. bundles, content packages or other features.
There are two supported ways to write down such a coordinate:
+Features are defined as a JSON object. An example feature file can be found
here:
https://github.com/apache/sling-org-apache-sling-feature-io/blob/master/design/feature-model.json
+and the JSON Schema for feature files is available from here:
https://github.com/apache/sling-org-apache-sling-feature-io/blob/master/src/main/resources/META-INF/feature/Feature-1.0.0.schema.json.
-* Using a colon as a separator for the parts:
groupId:artifactId[:type[:classifier]]:version as defined in
https://maven.apache.org/pom.html#Maven_Coordinates
-* Using a mvn URL: `'mvn:' group-id '/' artifact-id [ '/' [version] [ '/'
[type] [ '/' classifier ] ] ] ]`
+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.
-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.
+Java API for Serialization/Deserialization into/from this format is available
from https://github.com/apache/sling-org-apache-sling-feature-io.
+## OSGi Bundles
-## Bundles
+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 [...]
-A feature normally declares a number of bundles that are provided through the
feature. The bundles are not stored inside the feature
-but referenced via their Maven Coordinates in the `bundles` section of the
feature model.
+```
+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",
+ // defining a bundle by using an object
+ {
+ "id" : "org.apache.sling:org.apache.sling.engine:2.5.0",
+ "info" : "This is the core implementation of Apache Sling"
+ }
+ ]
+}
+```
-Individual bundles are either referenced as a string value in the `bundles`
array in the feature model, or they can be specified
-as objects in the `bundles` array. In that case the `id` for the bundle must
be specified. Additional metadata can also be placed
-here. It is possible to mix bundles specified by just the id (string) and
object in a single array.
+Multiple versions of a bundle with the same group ID, artifact ID (,classifier
and type) are allowed.
-Multiple versions of a bundle with the same group ID and artifact ID are
allowed. In this case both must be specified in the
-`bundles` section.
+Bundles usually have requirements, for example they contain package imports -
such requirements can be satisfied either by other bundles from the same or
other features. Or in other words, a feature must not be complete and fulfill
all requirements mentioned within the parts of the feature.
-## Configuration
+## OSGi Configurations
OSGi Configuration Admin configuration is specified in the `configurations`
section of the feature model.
-The configurations are specified following the format defined by the OSGi
Configurator
-specification:
https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html
+The configurations are specified following the format defined by the OSGi
Configurator
+specification:
https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html
-Variables declared in the Feature Model variables section can be used for late
binding of variables,
+Variables declared in the Feature Model variables section can be used for late
binding of variables,
they can be specified with the Launcher, or the default from the variables
section is used.
Factory configurations can be specified using the named factory syntax, which
separates
@@ -118,30 +114,69 @@ 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 Model.
-Features can declare additional capabilities that are provided by the feature
in addition to the capabilities provided by
+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.
+by any of those bundles individually. The Feature can be used to add this
capability to the provided set.
+
+Additional capabilities are specified in the `capabilities` section of the
Feature Model.
+
+Features can define OSGi Configurations that will be provided into the runtime
and features can also declare additional requirements and capabilities over and
above the ones coming from the bundles that are part of the feature.
+
+Features can be declared _from scratch_ or they can use another pre-existing
feature as a prototype. In this case
+the new feature starts off as a feature identical to its prototype, with some
exceptions:
+
+* it does not get the prototype's identity.
+* bundles, configurations and framework properties can be removed from the
prototype, in the `removals` section.
+* anything declared in the feature definition of a feature based on a
prototype adds or overrides to what came from the prototype.
+
+Features can also be marked as `final` and/or `complete`.
+A `final` feature cannot be used as a prototype for another feature. A feature
marked as `complete` indicates
+that all its dependencies are met by capabilities inside the feature, i.e. it
has no external dependencies.
+
+A Feature Launcher can be used to launch features into a running process with
an OSGi Framework.
+The launcher is typically fed with a number of feature files that should be
launched together.
+Overrides for variables defined in the feature models can be provided on the
launcher commandline.
+
+Tooling exists to analyze and validate features, and to aggregate and merge
multiple features into a single
+feature, which can be used to create higher level features from a combination
of lower-level ones. Most of
+the tooling is accessible through the slingfeature-maven-plugin:
https://github.com/apache/sling-slingfeature-maven-plugin
+
+The following diagrams show a typical workflow when working with feature files:
+
+<img src="diagrams/Develop.jpg" width="700"/>
+
+Features are authored as JSON Feature Files.
+The slingfeature-maven-plugin provides analyzers and aggregators that check
features and can combine them into larger features. The maven plugin can also
be used to publish features to a Maven Repository.
+
+<img src="diagrams/RunningSystem.jpg" width="700"/>
+
+To create a running system from a number of feature files, features are
selected from a Maven Repository,
+they are validated for completeness and optionally additional features are
pulled in through the OSGi Resolver
+(not yet implemented). A final system feature has no unresolved dependencies.
It is passed to the Feature Launcher
+along with optional additional features the provide functionality on top of
what is defined in the system feature.
+The Feature Launcher creates a running process containing an OSGi Framework
provisioned with the feature's contents.
+
+
-Additional capabilities are specified in the `capabilities` section of the
Feature Model.
## Prototype
A feature can be defined based on a prototype. This means that the feature
starts out as a copy of the feature prototype.
Everything in the prototype is copied to the new feature, except for its `id`.
The new feature will get a new, different ID.
-The prototype is processed with regard to the defined elements of the feature
itself.
+The prototype is processed with regard to the defined elements of the feature
itself.
This processing happens as follows:
* Removal instructions for a prototype are handled first.
* A clash of artifacts (such as bundles) between the prototype and the feature
is resolved by picking the version defined last, which
is the one defined by 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
+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, i.e. the definition in the feature
overrides the one coming from the prototype.
* Configurations will be merged by default, later ones potentially overriding
newer ones:
* If the same property is declared in more than one feature, the last one
wins - in case of an array value, this requires redeclaring all values (if they
are meant to be kept).
* Later framework properties overwrite newer ones.
* Capabilities and requirements are appended - this might result in
duplicates, but that doesn't really hurt in practice.
-* Extensions are handled in an extension specific way, by default the contents
are appended. In the case of extensions of type
+* Extensions are handled in an extension specific way, by default the contents
are appended. In the case of extensions of type
`Artifact` these are handled just like bundles. Extension merge plugins can be
configured to perform custom merging.
Prototypes can provide a useful way to manipulate existing features. For
example to replace a bundle in an existing feature and deliver this as a
modified feature.
@@ -157,16 +192,16 @@ Custom content can have one of the following formats:
* An array of Artifacts
Custom content be useful to co-locate metadata with its associated feature or
-to enhance the feature model with new functionality. The API Regions described
+to enhance the feature model with new functionality. The API Regions described
in [apicontroller.md](apicontroller.md) is an example of enhancing the feature
functionality.
-When creating aggregates, extensions are merged into the resulting aggregate
feature. There are
+When creating aggregates, extensions are merged into the resulting aggregate
feature. There are
default rules for aggregating extension content, which essentially is appending
all the extension content of a given type. However custom merge plugins can
also
be provided. After the merge a postprocessor is always run which can perform
-additional operations based on the extension content. Note that both the
-aggregate task of the `slingfeature-maven-plugin` as well as the launcher
perform
+additional operations based on the extension content. Note that both the
+aggregate task of the `slingfeature-maven-plugin` as well as the launcher
perform
merge operations on all the feature models these are provided with.
Extensions are declared in the JSON Feature file using the following syntax:
@@ -177,7 +212,7 @@ Extensions are declared in the JSON Feature file using the
following syntax:
For example, the following declaration defines an extension with name
`api-regions`
which is specified as JSON. The declaration also states that if no plugin is
-present that knows about this extension it should be ignored and execution
+present that knows about this extension it should be ignored and execution
should continue.
```
@@ -200,7 +235,7 @@ be installed by the launcher. Example:
## Built-in extension: repoinit
This extension is of type `TEXT`. It allows the specification of Sling
Repository
-Initialization statements which will be executed on the repository at startup.
+Initialization statements which will be executed on the repository at startup.
Example:
```
