OSGi has become 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 an application definition becomes unwieldy once the number of bundles reaches a certain level.

When developing large scale applications it is often the case that few people know the role of every single bundle or configuration item in the application. To keep the architecture understandable a grouping mechanism is needed that allows for the representation of parts of the application into larger entities that keep reasoning about the system manageable. In such a domain members of teams spread across an organization will need to be able to both develop new parts for the application as well as make tweaks or enhancements to parts developed by others such as adding configuration and resources or changing one or more bundles relevant to their part of the application.

The higher level constructs that define the application should be reusable in different contexts, for example if one team has developed a component to handle job processing, different applications should be able to use it, and if needed tune its configuration or other aspects so that it works in each setting without having to know each and every detail that the job processing component is built up from.

Applications are often associated with additional resources or metadata, for example database scripts or custom artifacts. By including these with the application definition, all the related entities are encapsulated in a single artifact.

By combining various applications or subsystems together, systems are composed of existing, reusable building blocks, where all these blocks can work together. Architects of these systems need to think about components without having to dive into the individual implementation details of each subcomponent. The Features defined in this specification can be used to model such applications. Features contain the definition of an application or component and can be composed into larger systems.

708.1.2 Entities

The following entities are used in this specification:

• Feature - A Feature contains a number of entities that, when provided to a launcher can be turned into an executable system. Features can also be building blocks which are assembled into larger systems.

• Bundles - A Feature can contain one ore more bundles.

• Capabilities and Requirements - A Feature can declare additional capabilities and requirements.

• Configuration - A Feature can contain configurations for the Configuration Admin service.

• Extension - A Feature can contain a number of extensions with custom content.

• Launcher - A launcher can turn one or more Features into an executable system.

• Processor - A Feature processor can read Features and perform a processing operation on them, such as validation, transformation or generation of new entities based on the Features.

• Properties - Framework properties can be specified in a Feature.

Figure 708.1 Features Entity overview

Features are defined by declaring JSON documents or by using the Feature API. Each Feature has a unique ID which includes a version. It can hold a number of entities, including a list of bundles, configurations, capabilities, requirements and others. Features are extensible, that is a Feature can also hold any number of custom entities which are related to the Feature.

Features may have dependencies on other Features. Features inherit the capabilities and requirements from all bundles listed in the Feature, and can also have additional capabilities and requirements declared on the Feature level.

Once created, a Feature is immutable. Its definition cannot be modified. However another Feature with a different identity can be created which is based on a given Feature using the prototype mechanism.

Additionally it’s possible to record caching related information in a Feature through transient extensions, however this cached content is not significant for the definition of the Feature or part of its identity.

group-id ':' artifact-id [ ':' type [ ':' classifier ] ] ':' version

{
  "id": "org.acme:acmeapp:1.0.0",

  "name": "The ACME app",
  "description": 
    "This is the main ACME app, from where all functionality can be reached."

  /*
    Additional Feature entities here
    ...
  */
}

BuilderFactory factory = // ... from Service Registry ...

FeatureBuilder builder = factory.newFeatureBuilder(
  new ID("org.acme", "acmeapp", "1.0.0"));
builder.setName("The ACME app");
builder.setDescription("This is the main ACME app, "
  + "from where all functionality can be reached.");

Feature f = builder.build();

Comments in the form of [2] JSMin (The JavaScript Minifier) comments are supported, that is, any text on the same line after // is ignored and any text between /* */ is ignored.

Features often list a number of bundles that implement the functionality provided by the Feature. Bundles are listed by referencing them in the bundles array so that they can be resolved from a repository. Bundles can have metadata associated with them, such as the relative start order of the bundle in the Feature. Custom metadata can also be provided. A single Feature can provide multiple versions of the same bundle, if desired.

Bundles are referenced using the identifier format described in Identifiers. This means that Bundles are referenced using their Maven coordinates. The bundles array can either contain String values referencing the bundles directly by their identifier, or JSON objects which can contain the bundle IDs with additional metadata.

The following example shows a simple Feature describing a small application with its dependencies:

{
  "id": "org.acme:acmeapp:1.0.1",
    
  "name": "The Acme Application",
  "license": "https://opensource.org/licenses/Apache-2.0",
  "isComplete": true,

  "bundles": [
    "org.osgi:org.osgi.util.function:1.1.0",
    "org.osgi:org.osgi.util.promise:1.1.1",
    {
      "id": "org.apache.commons:commons-email:1.5",

      // This attribute is used by custom tooling to 
      // find the associated javadoc
      "org.acme.javadoc.link": 
        "https://commons.apache.org/proper/commons-email/javadocs/api-1.5"
    },
    "com.acme:acmelib:1.7.2"      
  ]
   
  /* 
    Additional Feature entities here 
    ...
  */
}

BuilderFactory factory = // ... from Service Registry ...

FeatureBuilder builder = factory.newFeatureBuilder(
    new ID("org.acme", "acmeapp", "1.0.1"));
builder.setName("The Acme Application");
builder.setLicense("https://opensource.org/licenses/Apache-2.0");
builder.setComplete(true);

FeatureBundle b1 = factory.newBundleBuilder(
    ID.fromMavenID("org.osgi:org.osgi.util.function:1.1.0"))
  .build();

FeatureBundle b2 = factory.newBundleBuilder(
    ID.fromMavenID("org.osgi:org.osgi.util.promise:1.1.1"))
  .build();

FeatureBundle b3 = factory.newBundleBuilder(
    ID.fromMavenID("org.apache.commons:commons-email:1.1.5"))
  .addMetadata("org.acme.javadoc.link",
    "https://commons.apache.org/proper/commons-email/javadocs/api-1.5")
  .build();

FeatureBundle b4 = factory.newBundleBuilder(
    ID.fromMavenID("com.acme:acmelib:1.7.2"))
  .build();

builder.addBundles(b1, b2, b3, b4);

Feature f = builder.build();

Features support configuration using the OSGi Configurator syntax, see Configurator Specification. This can be specified with the configurations key in the Feature. A Launcher can apply these configurations to the Configuration Admin service when starting the system.

It is an error to define the same PID (or Factory PID) twice in a single Feature.

Example:

{
    "id": "org.acme:acmeapp:osgifeature:configs:1.0.0",
    "configurations": {
        "org.apache.felix.http": {
            "org.osgi.service.http.port": 8080,
            "org.osgi.service.http.port.secure": 8443
        }
    }    
}

When a Feature is launched in an OSGi framework it may be necessary to specify Framework properties. These can be provided in the Framework Properties section of the Feature. The Launcher must be able to satisfy the specified properties. If it cannot ensure that these are present in the running Framework the launcher must fail.

Example:

{
  "id": "org.acme:acmeapp:osgifeature:fw-props:2.0.0",
  "framework-properties": {
    "org.osgi.framework.system.packages.extra": 
      "javax.activation;version=\"1.1.1\"",
    "org.osgi.framework.bootdelegation": "javax.activation"
  }
}

Configurations and Framework Properties support late binding of values. This enables setting these items through a Launcher, for example to specify a database user name, server port number or other information that may be variable between runtimes.

Variables are declared in the variables section of the Feature and they can have a default value specified. The default can be of type String, number or boolean. Variables can also be declared to not have a default, which means that they must be provided with a value through the Launcher. This is done by specifying null as the default in the variable declaration.

Example:

{
    "id": "org.acme:acmeapp:osgifeature:configs:1.1.0",
    "variables": {
        "http.port": 8080,
        "db.username": "scott",
        "db.password": null
    },
    "configurations": {
        "org.acme.server.http": {
            "org.osgi.service.http.port:Integer": "${http.port}"
        },
        "org.acme.db": {
            "username": "${db.username}-user",
            "password": "${db.password}"
        }
    }    
}

Variables are referenced with the curly brace placeholder syntax: ${ variable-name } in the configuration value or framework property value section. To support conversion of variables to non-string types the configurator syntax specifying the datatype with the configuration key can be used, as in the above example.

Multiple variables can be referenced for a single configuration or framework property value and variables can be combined with text. Variable substitution is applied recursively, that is if the value of a variable is again a variable it must be substituted. If no variable exist with the given name, then the ${ variable-name } must be retained in the value.

Features inherit all capabilities and requirements from their bundles. Additional capabilities and requirements can be added to the Feature directly.

For example, a Feature can declare a set of bundles and configurations which together may provide an osgi.implementation capability, meaning that sum of these provide the implementation of a specification. Any kind of capability can be declared to be provided by the Feature. These capabilities can be used as part of the resolution process when a number of Features are resolved together.

Additional requirements can mean that a Feature is only complete, when these requirements are also satisfied, in addition to the requirements provided in the bundles that are part of the Feature.

Example:

{
  "id": "org.acme:acmeapp:osgifeature:capreq:1.0.0",
  
  // Requirements over and above the requirements in the bundles 
  // referenced by the Feature.
  "requirements": [
    {
      "namespace": "osgi.contract",
      "directives": {
        "filter": "(&(osgi.contract=JavaServlet)(version=3.1))"
      }
    }
  ],

  // Capabilities over and above the capabilities provided by the 
  // bundles referenced by the Feature.
  "capabilities": [
    {
      "namespace": "osgi.service",
      "attributes": {
        "objectClass:List<String>": 
          "org.osgi.service.http.runtime.HttpServiceRuntime"
      }
    }
  ]
}

Features can be extended with custom content. This makes it possible to keep entities and information relating to the Feature together with the rest of the Feature.

Custom content is provided through Feature extensions, and can be in one of the following formats:

Extensions can have a variety of consumers. For example they can be handled by a Feature Launcher or by an external tool which can process the extension at any point of the Feature life cycle.

Extensions can be marked as one of the following three kinds:

Extensions are specified as JSON objects under the extensions key in the Feature. A Feature can contain any number of extensions, as long as the extension keys are unique. It is recommended to use reverse DNS naming for extension keys to avoid name clashing of multiple extensions in a single Feature. Extensions names without DNS prefix are reserved for OSGi use.

{
    "id": "org.acme:acmeapp:2.0.0",
    
    "name": "The Acme Application",
    "license": "https://opensource.org/licenses/Apache-2.0",
    "isComplete": true,

    "bundles": [
        "org.osgi:org.osgi.util.function:1.1.0",
        "org.osgi:org.osgi.util.promise:1.1.1",
        "com.acme:acmelib:2.0.0"      
    ],
    
    "extensions": {
        "org.acme.mydoc": {
            "type": "text",
            "text": [
                "This application provides the main acme ",
                "functionality."
            ]
        }
    }
}

{
    "id": "org.acme:acmeapp:2.1.0",
    
    "name": "The Acme Application",
    "license": "https://opensource.org/licenses/Apache-2.0",
    "isComplete": true,

    "bundles": [
        "org.osgi:org.osgi.util.function:1.1.0",
        "org.osgi:org.osgi.util.promise:1.1.1",
        "com.acme:acmelib:2.0.0"      
    ],
    
    "extensions": {
        "execution-environment": {
            "type": "json",
            "json": {
                "environment-capabilities":
                    ["osgi.ee; filter:=\"(&(osgi.ee=JavaSE)(version=11))\""], 
                "framework": "org.osgi:core:6.0.0",
                "provided-features": ["org.acme:platform:1.1"]
            }
        }
    }
}

{
    "id": "org.acme:acmeapp:2.2.0",
    
    "name": "The Acme Application",
    "license": "https://opensource.org/licenses/Apache-2.0",
    "isComplete": true,

    "bundles": [
        "org.osgi:org.osgi.util.function:1.1.0",
        "org.osgi:org.osgi.util.promise:1.1.1",
        "com.acme:acmelib:2.0.0"      
    ],
    
    "extensions": {
        "org.acme.ddlfiles": {
            "kind": "mandatory",
            "type": "artifacts",
            "artifacts": ["org.acme:appddl:1.2.1"]
        }
    }
}

...

...

...