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 f314be0 Restructure documentation
f314be0 is described below
commit f314be010fafdc151e58c57bdb1a59407bc6078d
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Fri Mar 27 07:10:51 2020 +0100
Restructure documentation
---
{diagrams => docs/diagrams}/Develop.jpg | Bin
{diagrams => docs/diagrams}/RunningSystem.jpg | Bin
docs/extensions.md | 34 ++++
docs/feature-archives.md | 3 +
readme.md => docs/features.md | 211 ++++++++---------------
readme.md | 232 +++-----------------------
6 files changed, 126 insertions(+), 354 deletions(-)
diff --git a/diagrams/Develop.jpg b/docs/diagrams/Develop.jpg
similarity index 100%
rename from diagrams/Develop.jpg
rename to docs/diagrams/Develop.jpg
diff --git a/diagrams/RunningSystem.jpg b/docs/diagrams/RunningSystem.jpg
similarity index 100%
rename from diagrams/RunningSystem.jpg
rename to docs/diagrams/RunningSystem.jpg
diff --git a/docs/extensions.md b/docs/extensions.md
new file mode 100644
index 0000000..a2d9978
--- /dev/null
+++ b/docs/extensions.md
@@ -0,0 +1,34 @@
+# Available Feature Extensions
+
+The Feature Model is extensible, meaning that it can be augmented with custom
content in a number of ways. Some extensions are supported out of the box.
Other extensions are available through additional modules.
+
+## Built-in extension: content-packages
+
+This extension of type `ARTIFACTS` allows listing content packages which will
+be installed by the launcher. Example:
+
+```
+"content-packages:ARTIFACTS|required":[
+ "org.apache.sling.myapp:my-content-package:zip:1.0.0"
+]
+```
+
+## 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.
+Example:
+
+```
+"repoinit:TEXT|required":[
+ "create path /content/example.com(mixin mix:referenceable)",
+ "create path (nt:unstructured) /var"
+]
+```
+
+As initializing the repository is usually important for Sling based
applications
+the extension should be marked as required as in the example above.
+
+## Further extensions
+
+* [API Controller and API Regions](../apicontroller.md)
diff --git a/docs/feature-archives.md b/docs/feature-archives.md
new file mode 100644
index 0000000..d00051e
--- /dev/null
+++ b/docs/feature-archives.md
@@ -0,0 +1,3 @@
+# Feature Archives
+
+TBD
diff --git a/readme.md b/docs/features.md
similarity index 58%
copy from readme.md
copy to docs/features.md
index cdc509a..5c62c5b 100644
--- a/readme.md
+++ b/docs/features.md
@@ -1,23 +1,3 @@
-[<img
src="http://sling.apache.org/res/logos/sling.png"/>](http://sling.apache.org)
-
- [](https://builds.apache.org/job/Sling/job/sling-org-apache-sling-feature/job/master)
[](https://builds.apache.org/job/Sling/job/sling-org-apache-sling-feature/job/master/test_results_analyzer/)
[ 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,
-requirements and custom artifacts.
-
# Features
A feature is the central entity for the Feature Model. A feature is described
through a JSON object and can contain:
@@ -117,17 +97,85 @@ A feature with configurations:
}
}
}
-
```
+## OSGi Framework properties
+
+TBD
+
## Requirements and Capabilities
In order to avoid a concept like *Require-Bundle* a feature does not
explicitly declare dependencies to other features. These are declared by the
required capabilities, either explicit or implicit. The implicit requirements
are calculated by inspecting the contained bundles (and potentially other
artifacts like content packages).
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.
+```
+A feature declaring additional requirements:
+{
+ "id" :
"org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
+ "requirements" : [
+ {
+ "namespace" : "osgi.implementation",
+ "attributes" : {
+ "name" : "value"
+ },
+ "directives" : {
+ "name" : "value"
+ }
+ }
+ ]
+}
+```
+
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.
+```
+A feature declaring additional capabilities:
+{
+ "id" :
"org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
+ "capabilities" : [
+ {
+ "namespace" : "osgi.implementation",
+ "attributes" : {
+ "name" : "value"
+ },
+ "directives" : {
+ "name" : "value"
+ }
+ }
+ ]
+}
+```
+
+## Extensions
+
+The Feature Model is extensible, meaning that it can be augmented with custom
content in a number of ways. 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 in
[apicontroller.md](../apicontroller.md) is an example of enhancing the feature
functionality.
+
+Custom content can have one of the following formats/types:
+
+* Plain text
+* A JSON structure (object or array)
+* 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:
+
+```
+"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.
+
+```
+"api-regions:JSON|optional" : [
+ {"name": "global"}
+]
+```
+
## Final and Complete Features
Features can also be marked as `final` and/or `complete`.
@@ -139,7 +187,6 @@ that all its dependencies are met by capabilities inside
the feature, i.e. it ha
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.
-
## Prototype
Features can be declared _from scratch_ or they can use another pre-existing
feature as a prototype. In this case
@@ -168,123 +215,3 @@ overrides the one coming from the prototype.
`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.
-
-# Extensions
-
-The Feature Model is extensible, meaning that it can be augmented with custom
content in a number of ways.
-
-Custom content can have one of the following formats:
-
-* Plain text
-* a JSON array
-* 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
-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
-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
-merge operations on all the feature models these are provided with.
-
-Extensions are declared in the JSON Feature file using the following syntax:
-
-```
-"extention-name:<type>|{optional|required|transient]": [ json array ]
-```
-
-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
-should continue.
-
-```
-"api-regions:JSON|optional" : [
- {"name": "global"}
-]
-```
-
-# Managing Features
-
-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.
-
-
-# Available Feature Extensions
-
-The feature model implementation supports some extensions out of the box.
Other extensions are available through additional modules.
-
-## Built-in extension: content-packages
-
-This extension of type `ARTIFACTS` allows listing content packages which will
-be installed by the launcher. Example:
-
-```
-"content-packages:ARTIFACTS|required":[
- "org.apache.sling.myapp:my-content-package:zip:1.0.0"
-]
-```
-
-## 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.
-Example:
-
-```
-"repoinit:TEXT|required":[
- "create path /content/example.com(mixin mix:referenceable)",
- "create path (nt:unstructured) /var"
-]
-```
-
-As initializing the repository is usually important for Sling based
applications
-the extension should be marked as required as in the example above.
-
-## Further extensions
-
-* [API Controller and API Regions](apicontroller.md)
-
-# Launching
-
-A launcher for feature models is available in this project:
https://github.com/apache/sling-org-apache-sling-feature-launcher
-
-# Tooling
-
-The primary tooling around the feature model is provided through Maven by the
Sling Feature Maven Plugin:
https://github.com/apache/sling-slingfeature-maven-plugin
-
-See the readme of the plugin for more information.
-
-# References
-
-The links below provide additional information regarding the Feature Model.
-
-* [Requirements](requirements.md)
-* [File
format](https://github.com/apache/sling-org-apache-sling-feature-io/blob/master/design/feature-model.json)
-
-* [Prototype](prototype.md)
diff --git a/readme.md b/readme.md
index cdc509a..2a3bbae 100644
--- a/readme.md
+++ b/readme.md
@@ -18,196 +18,28 @@ the details of the various components that the feature is
built up from. It allo
on reusable components and includes everything related to this application,
including bundles, configuration, framework properties, capabilities,
requirements and custom artifacts.
-# Features
+## Features
-A feature is the central entity for the Feature Model. A feature is described
through a JSON object and can contain:
+In a nutshell, 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
-## Feature Metadata
+Read the [documentation about features](docs/features.md)
-Each feature must specify a unique identifier. Other attributes like `title`,
`description`, `vendor` name, and `license` are optional.
+## Feature Archives
-## Feature Identity
+Feature archives allow to distribute a feature together with all its
referenced binaries.
-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.
+Read the [documentation about feature archives](docs/feature-archives.md)
-While group id, artifact id, version and the optional classifier can be freely
choosen for a feature, the type/packaging is defined as `slingosgifeature`.
+## Feature Extensions
-## Maven Coordinates
+The Feature Model is extensible, meaning that it can be augmented with custom
content in a number of ways. Some extensions are supported out of the box.
Other extensions are available through additional modules.
-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:
-
-* 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 ] ] ] ]*
-
-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.
-
-```
-Example for specifying a feature id using a Maven id:
-{
- "id" :
"org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0"
-}
-
-Same id specified as a Maven url:
-{
- "id" :
"org.apache.sling/org.apache.sling.core.feature/1.0.0/slingosgifeature"
-}
-
-```
-
-## Feature File Format
-
-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.
-
-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 available
from https://github.com/apache/sling-org-apache-sling-feature-io.
-
-## OSGi 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 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"
- }
- ]
-}
-```
-
-Multiple versions of a bundle with the same group ID, artifact ID (,classifier
and type) are allowed.
-
-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.
-
-## OSGi Configurations
-
-OSGi configurations are specified in the `configurations` section of the
feature model as a JSON object. The format for configurations is using the
standard OSGi configuration resource format as defined by the [OSGi Configurator
-specification](https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html).
-
-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 [...]
-
-```
-A feature with configurations:
-{
- "id" :
"org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
- "configurations" : {
- // single configuration
- "org.apache.sling.engine.MainServlet" : {
- "title" : "Apache Sling",
- "allowPost" : true,
- "port:Integer" : "8080"
- },
- // a factory configuration
- "org.apache.sling.logging.Logger~core" : {
- "name" : "core",
- "level" : "DEBUG"
- }
- }
-}
-
-```
-
-## Requirements and Capabilities
-
-In order to avoid a concept like *Require-Bundle* a feature does not
explicitly declare dependencies to other features. These are declared by the
required capabilities, either explicit or implicit. The implicit requirements
are calculated by inspecting the contained bundles (and potentially other
artifacts like content packages).
-
-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.
-
-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.
-
-## Final and Complete Features
-
-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.
-
-## 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.
-
-
-## Prototype
-
-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.
-
-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.
-
-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
-`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
-`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.
-
-# Extensions
-
-The Feature Model is extensible, meaning that it can be augmented with custom
content in a number of ways.
-
-Custom content can have one of the following formats:
-
-* Plain text
-* a JSON array
-* 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
-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
-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
-merge operations on all the feature models these are provided with.
-
-Extensions are declared in the JSON Feature file using the following syntax:
-
-```
-"extention-name:<type>|{optional|required|transient]": [ json array ]
-```
-
-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
-should continue.
-
-```
-"api-regions:JSON|optional" : [
- {"name": "global"}
-]
-```
+Read the [documentation about available extensions](docs/extensions.md)
# Managing Features
@@ -221,12 +53,12 @@ the tooling is accessible through the
slingfeature-maven-plugin: https://github.
The following diagrams show a typical workflow when working with feature files:
-<img src="diagrams/Develop.jpg" width="700"/>
+<img src="docs/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"/>
+<img src="docs/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
@@ -234,46 +66,22 @@ they are validated for completeness and optionally
additional features are pulle
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 Aggregation
-# Available Feature Extensions
-
-The feature model implementation supports some extensions out of the box.
Other extensions are available through additional modules.
-
-## Built-in extension: content-packages
-
-This extension of type `ARTIFACTS` allows listing content packages which will
-be installed by the launcher. Example:
-
-```
-"content-packages:ARTIFACTS|required":[
- "org.apache.sling.myapp:my-content-package:zip:1.0.0"
-]
-```
-
-## 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.
-Example:
-
-```
-"repoinit:TEXT|required":[
- "create path /content/example.com(mixin mix:referenceable)",
- "create path (nt:unstructured) /var"
-]
-```
-
-As initializing the repository is usually important for Sling based
applications
-the extension should be marked as required as in the example above.
-
-## Further extensions
+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
+merge operations on all the feature models these are provided with.
-* [API Controller and API Regions](apicontroller.md)
# Launching
A launcher for feature models is available in this project:
https://github.com/apache/sling-org-apache-sling-feature-launcher
+
# Tooling
The primary tooling around the feature model is provided through Maven by the
Sling Feature Maven Plugin:
https://github.com/apache/sling-slingfeature-maven-plugin
![http://sling.apache.org/res/logos/sling.png"/](http://sling.apache.org/res/logos/sling.png"/){kind=link}
