150 Configurator Specification

150.1 Introduction

OSGi defines a model to provide bundles with configurations. This is specified in the Configuration Admin specification where a configuration is identified by a persistent identity (PID). A PID is a unique token, recommended to be conforming to the symbolic name syntax. A configuration consists of a set of properties, where a property consists of a string key and a corresponding value. The type of the value is limited to the primitive types and their wrappers, Strings, or Java Arrays/List/Vector of these.

This specification defines a mechanism to feed configurations into the Configuration Admin Service through configuration resources. A single configuration resource can feed multiple PIDs with configuration and multiple configuration resources can be provided in one or more bundles.

150.2 Entities

The following entities are used in this specification.

  • Configuration Admin Service - Standard service to configure OSGi-based systems. See Configuration Admin Service Specification.

  • Configuration Resource - A JSON resource in a bundle containing configurations. This resource is processed by an implementation of this specification.

  • Extendee - The extendee is a bundle containing configuration resources. It is extended by an implementation of this specification.

  • Configurator - The Configurator implements the behavior specified in this specification. It processes configuration resources and passes the configuration dictionary on to the Configuration Admin Service.

  • Configuration dictionary - The configuration information when it is passed to the Configuration Admin Service. It consists of a Dictionary object with a number of properties and identifiers.

  • Persistent Identity (PID) - A configuration dictionary is associated with a unique PID to identify the destination of this data. See The Persistent Identity.

  • Configuration Object - Implements the Configuration interface and contains the configuration dictionary for a Managed Service or one of the configuration dictionaries for a Managed Service Factory. These objects are manipulated by configuring bundles.

  • Coordinator Service - The coordinator groups related operations to optimize handling of these operations. Using the coordinator with configuration updates can minimize the volatility in the system. See Coordinator Service Specification.

Figure 150.1 Configurator Entity Overview

Configurator Entity Overview

150.3 Configuration Resources

The Configurator is processing configuration resources containing configurations. The resources can either be part of a bundle or be provided to the Configurator on startup.

150.3.1 Configuration Resource Format

The format for a configuration resource is [1] JSON (JavaScript Object Notation) and it must be UTF-8 encoded. An example configuration resource has the following structure:

{
    // Resource Format Version
    ":configurator:resource-version" : 1,

    // First Configuration
    "pid.a": {
           "key": "val",
           "some_number": 123
        },

    // Second Configuration
    "pid.b": {
           "a_boolean": true
        }
}

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.

Configuration resources provide a set of configuration dictionaries each with a PID key to target a specific PID in the Configuration Admin Service and zero or more configuration values for this PID. Keys starting with the prefix :configurator: contain information about the resource or instructions for the Configurator and therefore are not interpreted as PIDs containing configurations. If a key contains an invalid PID, this entry is ignored and the Configurator should log an error with the Log Service if available.

The Configurator defines the following special keys on the resource level.

Table 150.1 Resource-level Configurator Keys

Key Value type Syntax Description

:configurator:

 resource-version

Number integer > 0 The version of the configuration resource format. This specification only supports version 1. If this entry is omitted then version 1 is assumed. Resources specifying an unsupported or invalid version are ignored and the Configurator should log an error with the Log Service if available.

:configurator:

 symbolic-name

String symbolic-name The symbolic name of the configuration resource. If not specified the symbolic name of the bundle containing the resource is used. Mandatory for configuration resources that do not reside in a bundle.
:configurator:version String version The version of this configuration resource. If not specified the version of the bundle containing the resource is used. Mandatory for configuration resources that do not reside in a bundle.

150.3.2 PIDs, Factory Configurations and Targeted PIDs

Configuration resources provide a set of configuration dictionaries each with a PID key to target a specific PID in the Configuration Admin Service.

Factory configurations can be addressed using the factory PID and a name by starting with the factory PID, appending a tilde ('~' \u007e), and then appending the name. This ensures a well-known name for the factory configuration instance. The PID for such a configuration is exactly this key. The Configurator must use the getFactoryConfiguration methods on Configuration Admin Service to create or obtain configurations with the given factory PID and name.

Targeted PIDs are supported through the configuration resource. In the case of single configurations, the full targeted PID is used as the key. For factory configurations, the key is assembled by chaining the targeted factory PID, a tilde ('~' \u007e), and the name.

The Configurator obtains all configurations with the location value of ? to allow the configurations to be received by multiple bundles.

The Configurator uses the Configuration.updateIfDifferent method on the configuration object to avoid any volatility in the system if the configuration applied has not been changed.

150.3.3 Configuration Dictionary

A configuration dictionary for the Configuration Admin Service is specified through a JSON object in the configuration resource. It is introduced using the PID as the key. The value is a JSON object containing the configuration dictionary.

The Configurator removes any comments and all properties where the key is starting with the special prefix :configurator: from the configuration object before converting it to a configuration dictionary that is provided to the Configuration Admin Service.

The Configurator defines special keys that can be used within the configuration object.

Table 150.2 PID-level Configurator Keys

Key Value type Syntax Description
:configurator:policy String default or force Specifies the overwrite policy on configurations set by non-Configurator sources. See Overwrite Policies.
:configurator:ranking Number integer The ranking of this configuration. If multiple bundles provide configuration for the same PID ranking rules are used to decide which configuration gets applied, see Ranking.

150.3.4 Data Types

Configuration values support data types as specified with the Filter Syntax in the OSGi Core Specification. Configuration resources are specified in JSON, which supports a more basic set of data types. The following table describes how values are converted from JSON to configuration values.

Table 150.3 JSON Conversions

JSON type To Java type
Boolean Boolean
Number

Whole number: Long

Floating point number: Double

String String
Array Array, or if requested Collection. Contents are boxed. If the array contents are of the same JSON type, the associated Java type is used as the array type. Otherwise the array elements are converted to String and a String[] array is used.
Object Literal object as JSON String

If a specific data type is required for a configuration, the Configurator can be instructed to convert the JSON value to a given data type. The target type can be specified by adding a colon : and the desired data type to the property name. Supported data types are String, Integer, Long, Float, Double, Byte, Short, Character and Boolean. Additionally arrays of Scalar or primitive types are supported and Collection of scalar. The primitive types that can be specified for arrays are: int, long, float, double, byte, short, char, boolean. For Collection the Configurator picks a suitable implementation that preserves order. Both bare Collection as well as typed collections that use the generics style notation are supported. If a requested conversion cannot be performed, then the configuration is not processed and the Configurator implementation should log an error.

An example configuration resource with typed data:

{
  "my.pid": {      
    "port:Integer" : 300,
    "an_int_array:int[]" : [2, 3, 4],
    "an_Integer_collection:Collection<Integer>" : [2, 3, 4],
    "complex": {
      "a" : 1,
      "b" : "two"
    }
  }
}

The above configuration gets converted to a configuration dictionary with the following entries (in pseudo Java language):

Integer port = 300;
int[]   an_int_array = {2, 3, 4};
Collection<Integer> an_Integer_collection = {2, 3, 4};
String  complex = "{ \"1\" : 1, \"b\" : \"two\" }"

As an alternative of specifying data types for the Configurator, consumers of configuration can convert the configuration values to the desired type by using the OSGi Converter see Converter Specification. A convenient way to convert a configuration map to the desired data types is by using the Converter to convert it to an annotation instance or by using a Declarative Services component property type.

150.3.4.1 Binary Data

In some cases binary data is associated with configurations such as certificates, security keys or other resources. The Configurator can manage this binary data. The bundle developer places the binaries in a location in the extendee and references it from the configuration resource, marking its type as binary:

{
  "my.config": {
    "security.enabled": true,
    "public.key:binary" : "/OSGI-INF/files/mykey.pub"
  }
}

When the Configurator applies the configuration, it extracts the binary file to a public area on the file system. The Configurator creates a subdirectory with as name the PID of the configuration. The PID must be URL-encoded to ensure that it does not contain characters that are illegal on a file system. The binary file is extracted in this subdirectory. The Configurator then applies the configuration with as value for the binary entry the absolute path of the extracted binary file.

A binary data property can also specify an array of binary resources by declaring the binary[] data type. Each resource referenced is extracted as a separate file on the file system and the value of the property will be an array of strings, each string being the full path of one extracted binary.

By default a directory called binaries in the bundle data area of the Configurator implementation is used. An alternative location can be specified via the configurator.binaries framework property. The value of this property must be an absolute path on the file system to which the Configurator has write access. If the directory does not exist the Configurator will create it. If the Configurator cannot write to this location, it logs an error and uses the default location instead.

When a configuration is removed, its associated binary files are also removed from the file system. When a configuration is updated, associated binary files are updated, if necessary. In the case of an update the Configurator should use a different filename for the extracted binary file to avoid any open file lock issues.

150.3.5 Ranking

The order in which the Configurator processes bundles is not defined. To control which configurations are in effect configuration ranking can be used. Configuration ranking is similar to service ranking; it is an integer which defaults to 0. Configurations with a higher ranking are preferred over configurations with a lower ranking. When multiple configurations arrive over time it is possible that the Configurator changes the effective configuration if a higher ranked configuration arrives later. The design of the Configurator is such that the effective set of configurations once the system stabilizes is consistent, regardless of the order in which bundles are installed and processed.

The ranking of a configuration can be specified by adding the :configurator:ranking property. The value of this property is converted to an Integer as defined by the Converter specification. If the value cannot be converted a warning should be logged. When multiple configurations for a given PID have the same ranking the bundle providing the configuration with the lowest bundle ID is preferred. If multiple configurations for the same PID with the same ranking are specified within a single bundle, the first one encountered is used.

The following example shows two bundles with a configuration resource containing a configuration for the same PID:

Resource in Bundle A:
{
  "my.pid": {      
    "port:Integer" : 300,
    ":configurator:ranking" : 100
  }
}

Resource in Bundle B:
{
  "my.pid": {      
    "port:Integer" : 100,
    ":configurator:ranking" : 10
  }
}

Bundle A contains the configuration with the higher ranking. Therefore, regardless of the installation order of bundle A and B, the configuration from Bundle A will be in effect after both bundles are installed and processed by the Configurator.

150.3.6 Overwrite Policies

In an IT operations scenario configurations are often updated by a systems administrator to suit the deployments requirements. In such scenarios it may be undesirable to have these modifications overwritten by a software update which includes a configuration resource. In other cases, bundles with configuration resources are used to enforce best practices or compliance with corporate guidelines, which should replace any previous manual settings. This specification defines policies to define the overwrite behavior of the Configurator when configurations have been set or modified by another entity.

Configuration policies are set by specifying the :configurator:policy property. Accepted values are default and force. This policy defines the behavior when a configuration to be applied was set by another entity in the system, or if it was modified by someone from the values set by the Configurator. The default value for this property is default. If the specified value is invalid an error is logged and the default value is used.

Table 150.4 Applying Configurations: Overwrite Policies

Policy value Action
default No action
force Configuration is added

The Configurator must keep track of configuration change count values to identify configurations that were changed by other entities or administrators.

When a bundle that provides configuration resources is uninstalled, the Configurator removes any configurations that it has provided on behalf of this bundle from the system. Before it removes a configuration the Configurator checks with the Configuration Admin Service whether the configuration it has provided has been changed by another entity. If the configuration has not been changed by another entity it is removed. If it has been changed then whether the configuration is removed depends on the value of the configurator:policy property:

Table 150.5 Removing externally modified configurations

Policy value Action
default No action
force Configuration is removed

When a configuration is removed the Configurator checks whether another, lower ranked, configuration resource is available. If present the Configurator sets this configuration.

The following examples explain the two policy options. In the first example Bundle A contains a configuration for the PID my.pid without specifying the policy. In this case the default policy is used:

{
  "my.pid": {      
    "port:Integer" : 300
  }
}

The following actions demonstrate the behavior of the default policy:

  1. The framework is started without any configuration for PID my.pid.

  2. Bundle A is installed, the Configurator creates the configuration for PID my.pid.

  3. An administrator manually changes the configuration for PID my.pid.

  4. Bundle A is updated with an updated configuration for PID my.pid. The Configurator detects the manual change of the configuration in Configuration Admin Service and does not apply the updated configuration from the bundle.

  5. Bundle A is uninstalled. The Configurator detects the manual change of the configuration in Configuration Admin Service and does not delete the configuration.

In the second example Bundle A contains a configuration for the PID my.pid this time with the overwrite policy set to force.

{
  "my.pid": {      
    "port:Integer" : 300,
    ":configurator:policy" : "force"
  }
}

The following actions demonstrate the behavior of the force policy:

  1. The framework is started without any configuration for PID my.pid.

  2. Bundle A is installed, the Configurator creates the configuration for PID my.pid.

  3. An administrator manually changes the configuration for PID my.pid.

  4. Bundle A is updated with an updated configuration for PID my.pid. The Configurator applies the updated configuration.

  5. Bundle A is uninstalled. The Configurator detects the manual change of the configuration in Configuration Admin Service and deletes the configuration.

150.4 Bundle Configuration Resources

The Configurator follows the OSGi extender model and looks for JSON configuration resources in installed bundles, if the bundle has opted-in to be processed. In order to get processed, a bundle must require the Configurator extender:

Require-Capability: osgi.extender;
  filter := "(&(osgi.extender=osgi.configurator)
              (version>=1.0)(!(version>=2.0)))"

The Configurator must ensure to only process bundles that it is wired to by the resolver.

By default the configuration resources are in the OSGI-INF/configurator directory in the bundle.

Configuration files are UTF-8 encoded and have the .json file extension. Files not having this extension are ignored. The Configurator processes the configuration resources within a single bundle in lexical order using the full resource path for sorting.

150.5 Initial Configurations

When the Configurator starts it calls bundleContext.getProperty("configurator.initial") to obtain initial configurations from the runtime environment. If this property is available its value is processed as follows:

  1. If the value starts with a left curly bracket ('{' \u007B), ignoring any leading white space, the Configurator will interpret the value as a literal configuration JSON resource.

  2. Otherwise the value is treated as a comma-separated list of URLs. The Configurator will read the resource at each URL and parse it as a JSON Configuration resource. If any errors occur during this process they are logged and the URL is skipped. The URLs are processed in alphabetical order of their provided value.

The ranking of these configurations can be set in the configuration resource as described in Ranking. The Configurator treats the initial configurations as being provided from a bundle with the bundle id -1.

If the framework is restarted, the Configurator needs to check whether the provided initial configurations are different than on the previous startup. The implementation is free to use whatever is appropriate to perform this check, like comparing last modified for the URLs or using a hash etc. If the provided configuration is different than on a previous startup, this is treated like a bundle update with an updated configuration.

150.6 Life Cycle

The Configurator uses the Configuration Admin Service. Therefore the Configurator implementation should require the Configuration Admin Service through a service requirement. The Configurator should not start processing configuration resources until it has runtime access to the Configuration Admin Service.

The Configurator uses the Configuration Admin Service that is visible to both the Configurator itself as well as the bundle that is being processed. If there are multiple candidates, the service with the highest ranking is used. If there is no Configuration Admin Service visible to both the bundle that is processed and the Configurator, the processing is delayed until such a service becomes available.

When the Configurator starts, it processes all started bundles and applies configurations provided by those bundles. From then on, the Configurator processes bundles as they enter the STARTING state. The Configurator should process as many bundles as possible in a single pass to minimize volatility for PIDs where multiple configurations with different rankings are provided.

When a bundle containing configuration resources is updated, the configurations must be updated in the Configuration Admin Service to which they were originally provided, keeping in mind that the system might have been restarted in-between. One way of keeping track of the original Configuration Admin Service is via the bundle location of the bundle providing the service. If this service is not available the Configurator must attempt to apply the updated configuration when this Configuration Admin Service re-appears.

Configurations remain in the system until the bundle that provided the configurations is uninstalled. When this happens, the Configurator must uninstall the configurations from the Configuration Admin Service to which it originally installed it as is the case with updates. If this Configuration Admin Service is not available at this time, the Configurator must remember the configurations that are to be removed, and remove them when the Configuration Admin Service re-appears at a later time.

When the Configurator becomes active, it must check whether configurations that it installed previously are still valid. If the bundles that provided these configurations have been uninstalled, the associated configurations must be removed. If a bundle is updated the associated configurations are also updated. The Configurator calls updateIfDifferent on the configuration to avoid volatility in the system if the actual configuration values did not change.

When updating or removing configurations, the Configurator must take the Overwrite Policies into account. This means that for certain policy values an externally modified configuration is not replaced or removed.

When a bundle that provides the Configuration Admin Service is uninstalled, the Configurator considers all configurations previously provided to that Configuration Admin Service as not yet applied. If another Configuration Admin Service is or becomes visible to both the Configurator and the bundle containing configuration resources, the Configurator will provide the configurations to this Configuration Admin Service as new.

When the Configurator is stopped or uninstalled the configurations applied will remain in the system.

150.7 Grouping and Coordinations

The Coordinator Service Specification defines a mechanism for multiple parties to collaborate on a common task without a priori knowledge of who will collaborate in that task. The Configurator must participate in such scenarios to coordinate with provisioning or configuration tasks.

Whenever the Configurator is processing configuration resources and interacting with the Configuration Admin Service, the Configurator must check whether a Coordinator Service is present. If it is present, the Configurator checks for an implicit coordination on the current thread. If such an implicit coordination exists, the Configurator does not need to create one. However, if such an implicit coordination is not present, the Configurator starts an implicit coordination on the current thread when interacting with the Configuration Admin Service and ends this coordinator when it is finished doing the current set of work. The Configurator does not need to delay applying any changes to the Configuration Admin Service until the coordination ends.

150.8 Security

When Java permissions are enabled, the Configurator must perform the following security procedures.

150.8.1 Configuration Permission

The Configurator manages configurations on behalf of the bundle containing the configuration resources. Therefore the Configurator needs to have the ConfigurationPermission[*,org.osgi.service.cm.ConfigurationPermission.CONFIGURE].

Every bundle has the implicit right to receive and configure configurations with a location that exactly matches the Bundle's location or that is null. Therefore the extendee does not need to special permissions.

150.8.2 Service Permission

The Configurator needs ServicePermission[<interface>, GET] for the Coordinator service.

The extendee needs ServicePermission[<interface>, GET] for the Configuration Admin Service.

150.8.3 Configuration Admin Service

The Configurator does get the Configuration Admin Service on behalf of the extendee. Therefore the extendee needs to be included in permission checks for getting the Configuration Admin Service. The Configurator needs to perform the required calls to ensure the extendee has the necessary permission to get the Configuration Admin Service.

150.8.4 File Permission

If binaries are used, the Configurator needs to have read/write/delete permission to the configured directory to store the binaries.

A bundle using a binary referenced from a configuration needs to have read permission to correct sub directory of the configured binary directory. The subdirectory is named after the PID of the configuration.

By default binaries are stored in the bundle data are of the Configurator. While this works without Java security enabled, permission configuration for the extendees gets challenging as the location of the bundle data area is only known at runtime. Therefore with Java security enabled, the directory holding the binaries should be configured to allow permission configuration for the extendees.

150.9 Capabilities

150.9.1 osgi.extender Capability

The Configurator implementation bundle must provide the osgi.extender capability with name osgi.configurator with the version of this specification:

Provide-Capability: osgi.extender;
     osgi.extender="osgi.configurator";
     version:Version="1.0"

This capability must follow the rules defined for the osgi.extender Namespace.

Bundles providing configuration resources must require the osgi.extender capability to opt in to being processed by the Configurator. The default location for configuration resources is in OSGI-INF/configurator. A bundle can specify alternate locations for configuration resources through the configurations attribute. The value of this attribute is of type String or List<String>. Each value represents a path inside the bundle. This path is always relative to the root of the bundle and may start with a slash /. A path value of / indicates the root of the bundle. The Configurator uses Bundle.findEntries to find all resources with the .json extension in this location. Sub directories are not considered. If the configuration attribute specifies multiple paths, these are visited in the order specified. Duplicate paths are ignored. Paths that do not exist in the bundle are logged as an error and skipped. Resources in a single directory are processed in alphabetical order. For example:

Require-Capability: osgi.extender;
     filter:="(&(osgi.extender=osgi.configurator)
             (version>=1.0)(!(version>=2.0)))";
     configurations="resources/configs"

To simplify the creation of this requirement the RequireConfigurator annotation can be used. This annotation allows the configurations attribute to be defined is a value other than the default is needed.

@RequireConfigurator("resources/configs")

150.10 osgi.configuration Namespace

Configuration resources define configuration for one or more PIDs. To declare what configuration is being provided, the osgi.configuration capability namespace can be used. Configuration resources and bundles can define the osgi.configuration capability for each configuration that they define. This capability should have resolve time effectiveness.

The osgi.configuration Namespace supports the attributes defined in the following table and ConfigurationNamespace.

Table 150.6 osgi.configuration namespace definition

Name Kind M/O Type Syntax Description
service.pid CA O String qname

Defines the PID of the configuration.

service.factoryPid CA O String qname

Defines the factory PID if this is a factory configuration.


Note that at least one of service.pid or service.factorypid must be defined. If the configuration is a standard configuration then only the service.pid is used. If the configuration is a factory configuration with an automatically generated identity then only the service.factoryPid is used. If the configuration is a factory configuration with a specified identity then both the service.pid and service.factoryPid are used.

150.11 Configuration Resources in a Repository

The configuration file format in Configuration Resources defines a portable representation of configurations for the Configuration Admin Service. Whilst the Configurator implementation is necessary to process these configurations when they are packaged inside a bundle or provided on startup, these files can also offer significant value to other tools for deployment and management outside of the Configurator usage.

If configuration resources are used in an OSGi repository, in order to integrate with querying and the resolution process, the configuration resources should define the appropriate capabilities.

In addition to the common requirements and capabilities, a standalone configuration resource must declare the following capabilities when in an OSGi repository:

  • An osgi.content capability. The mime type of the configuration resource should be application/vnd.osgi.configuration+json.

  • An osgi.identity capability. This capability requires that each resource define a symbolic name and version. These can be obtained from the mandatory :configurator:symbolic-name and :configurator:version keys in the configuration resource. As type attribute the string osgi.configuration must be used.

150.12 org.osgi.service.configurator

Version 1.0

Configurator Package Version 1.0.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.configurator; version="[1.0,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.configurator; version="[1.0,1.1)"

150.12.1 Summary

150.12.2 public final class ConfiguratorConstants

Defines standard constants for the Configurator services.

150.12.2.1 public static final String CONFIGURATOR_BINARIES = "configurator.binaries"

Framework property specifying the directory to be used by the Configurator to store binary files.

If a value is specified, the Configurator will write all binaries to the given directory. Therefore the Configurator bundle needs read and write access to this directory.

If this property is not specified, the Configurator will store all binary files in its bundle private data area.

150.12.2.2 public static final String CONFIGURATOR_EXTENDER_NAME = "osgi.configurator"

The name of the extender capability attribute for the Configurator

150.12.2.3 public static final String CONFIGURATOR_INITIAL = "configurator.initial"

Framework property specifying initial configurations to be applied by the Configurator on startup.

If the value of this property starts with a '{' (ignoring leading whitespace) it is interpreted as JSON and directly feed into the Configurator.

Otherwise the value is interpreted as a comma separated list of URLs pointing to JSON documents.

150.12.2.4 public static final String CONFIGURATOR_SPECIFICATION_VERSION = "1.0"

The version of the extender capability for the Configurator specification

150.12.2.5 public static final String POLICY_DEFAULT = "default"

Value for defining the default policy.

PROPERTY_POLICY

150.12.2.6 public static final String POLICY_FORCE = "force"

Value for defining the force policy.

PROPERTY_POLICY

150.12.2.7 public static final String PROPERTY_POLICY = ":configurator:policy"

Configuration property for the configuration policy.

Allowed values are POLICY_DEFAULT and POLICY_FORCE

POLICY_DEFAULT, POLICY_FORCE

150.12.2.8 public static final String PROPERTY_PREFIX = ":configurator:"

Prefix to mark properties as input for the Configurator when processing a configuration resource.

150.12.2.9 public static final String PROPERTY_RANKING = ":configurator:ranking"

Configuration property for the configuration ranking.

The value of this property must be convertible to a number.

150.12.2.10 public static final String PROPERTY_RESOURCE_VERSION = ":configurator:resource-version"

Global property in the configuration resource specifying the version of the resource format.

Currently only version 1 is defined for the JSON format and therefore the only allowed value is 1 for this property. If this property is not specified, 1 is assumed.

150.12.2.11 public static final String PROPERTY_SYMBOLIC_NAME = ":configurator:symbolic-name"

Global property in the configuration resource specifying the symbolic name of the configuration resource. If not specified the symbolic name of the bundle containing the resource is used. Mandatory for configuration resources that do not reside in a bundle

150.12.2.12 public static final String PROPERTY_VERSION = ":configurator:version"

Global property in the configuration resource specifying the version of the resource. If not specified the version of the bundle containing the resource is used. Mandatory for configuration resources that do not reside in a bundle.

150.13 org.osgi.service.configurator.annotations

Version 1.0

Configurator Annotations Package Version 1.0.

This package contains annotations that can be used to require the Configurator extender.

Bundles should not normally need to import this package as the annotations are only used at build-time.

150.13.1 Summary

150.13.2 @RequireConfigurator

This annotation can be used to require the Configurator extender. It can be used directly, or as a meta-annotation.

This annotation allows users to define custom locations that should be searched for configuration files using RequireConfigurator.value()

CLASS

TYPE, PACKAGE

150.13.2.1 String[] value default {}

This attribute can be used to define one or more locations that the configurator must search, in order, for configuration files.

If no locations are defined then the Configurator default of /OSGI-INF/configurator will be used.

A list of bundle locations containing configuration files

150.14 org.osgi.service.configurator.namespace

Version 1.0

Configurator Namespace Package Version 1.0.

Bundles should not need to import this package at runtime since all the types in this package just contain constants for capability and requirement namespaces specified by the OSGi Alliance.

150.14.1 Summary

150.14.2 public final class ConfigurationNamespace
extends Namespace

Configuration Capability and Requirement Namespace.

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

Immutable

150.14.2.1 public static final String CONFIGURATION_NAMESPACE = "osgi.configuration"

Namespace name for configuration capabilities and requirements.

Also, the capability attribute used to specify the name of the extension.

150.14.2.2 public static final String FACTORY_PID_ATTRIBUTE = "service.factoryPid"

The capability attribute contains the factory PID if this is a factory configuration. The value of this attribute must be of type String.

150.14.2.3 public static final String SERVICE_PID_ATTRIBUTE = "service.pid"

The capability attribute contains the PID of the configuration. The value of this attribute must be of type String.

150.15 References

[1]JSON (JavaScript Object Notation) https://www.json.org

[2]JSMin (The JavaScript Minifier) https://www.crockford.com/javascript/jsmin.html