The Artifact Repository Factory is useful both for the Feature Launcher and the Feature Runtime, and as such it must be easy to access both inside and outside an OSGi framework. The Feature Launcher Service implementation must provide an implementation of the Artifact Repository Factory interface. A user of the Artifact Repository Factory service may use the following ways to find an instance.

When outside OSGi:

When inside an OSGi framework:

A Local Repository is one that exists on a locally accessible file system. Note that this does not require that the file system is local, and technologies such as NFS or other network file systems would still be considered as Local Repositories. The key aspects of a Local Repository are that:

An Artifact Repository representing a Local Repository can be created using the createRepository(Path) method, passing in the path to the root of the repository. A NullPointerException must be thrown if the path is null and an IllegalArgumentException must be thrown if the path does not exist, or represents a file which is not a directory.

An Artifact Repository representing a Local Repository can also be created using the createRepository(URI,Map) method, passing a URI using the file scheme which points to the root of the repository. A NullPointerException must be thrown if the URI is null and an IllegalArgumentException must be thrown if the path does not exist, or represents a file which is not a directory.

Once created this Artifact Repository will search the supplied repository for any requested artifact data. Implementations are free to optimise checks using repository metadata.

A Remote Repository is one that exists with an accessible http or https endpoint for retrieving artifact data. Note that this does not require that the repository is on a remote machine, only that the means of accessing data is via HTTP requests. The key aspects of a Remote Repository are that:

An Artifact Repository representing a Remote Repository can be created using the createRepository(URI,Map) method, passing in the uri to the root of the repository. A NullPointerException must be thrown if the uri is null and an IllegalArgumentException must be thrown if the uri does not use the http or https scheme.

In addition to the repository URI the user may pass configuration properties in a Map. Implementations may support custom configuration properties, but those properties should use Reverse Domain Name keys. Keys not using the reverse DNS naming scheme are reserved for OSGi use. Implementations must ignore any configuration property keys that they do not recognise. All implementations must support the following properties:

Once created this Artifact Repository will search the supplied repository for any requested artifact data. Implementations are free to optimise checks using repository metadata.

Feature objects are expected to be immutable, and therefore a decorator cannot, and should not, change the feature object that is passed to them. Instead the decorator must create a new feature object which includes the decorated content.

To enable this both types of decorator are passed two builders, the first of which implements BaseFeatureDecorationBuilder and the second of which implements DecoratorBuilderFactory.

The former builder is similar to a FeatureBuilder but with three important differences:

The latter builder is similar to a BuilderFactory but it cannot create FeatureBuilder instances.

By using these two builders a decorated feature can be configured and created. This decorated feature can then be returned from the decorator. The ID of a decorated feature will always share the groupId, artifactId, version and type of the original feature, however the classifier may be changed using the setClassifier(String) method, and will default to DEFAULT_DECORATED_CLASSIFIER. Note that the only valid way to create a decorated feature is by using the builder. Any attempt to return a feature object which is not either:

is an error and will result in the operation being abandoned.

Decorators may be included using one of the relevant builder methods for a launch or runtime operation:

When registering a FeatureExtensionHandler the name of the extension to be handled must be passed, and cannot be null. This defines the name of the extension that the Feature Extension Handler will be used to process.

If multiple FeatureDecorator instances are registered then they will be called in the order that they were added.

If multiple FeatureExtensionHandler instances are registered for the same extension name then the earlier instances will be discarded. It is not possible to register more than one Feature Extension Handler for a single extension.

Instances of the Feature Launcher and Launch Builder are not required to be Thread Safe, and should not be shared between threads. Changing the configuration of a Launch Builder instance only affects that instance, and not any other instances that exist.

Framework launch properties are key value pairs which are passed to the OSGi framework as it is created. They can control many behaviours, including operations which happen before the framework starts, meaning that is not always possible to set them after startup.

Feature definitions that require particular framework launch properties can define them using a Feature Extension named FRAMEWORK_LAUNCHING_PROPERTIES. The Type of this Feature Extension must be JSON, where the value is a single JSON object. Each JSON property in this object represents a single Framework Launch Property. The name of each JSON property must be used as the name of a Framework Launch Property, unless the name starts with a single underscore _. The value of each property is used as the value of the Framework Launch Property, and must be a scalar type, that is a JSON string, number or boolean. If the value is a different JSON type then this must be treated as an error.

If the JSON property starts with a single underscore then it may be used for implementation specific behaviour, with the prefix _osgi reserved for future specifications. Implementation specific behaviours may permit JSON values to be any value JSON type.

If users require their Framework Launch Property name to start with an underscore then they must use two underscores __ in the JSON property name. When the implementation detects more than one underscore at the beginning of a JSON property defined in this extension the leading underscore must be removed, and the remaining string used as the Framework Launch Property name.

All implementations of the Feature Launcher must support this extension, and use it to populate the Framework Launch Properties. The version of this extension is 1.0.0, and may be declared in the extension JSON using the property FRAMEWORK_LAUNCHING_PROPERTIES_VERSION.

In addition to Framework Launch properties defined inside the Feature, users of the Feature Launcher can add and override Framework Launch Properties using one of the withFrameworkProperties method that permits a Map of framework properties to be provided. Any key value pairs defined in this map must take precedence over those defined in the Feature. A key with a null value must result in the removal of a key value pair if it is defined in the Feature.

When defining a feature it is not always possible to be framework independent. Sometimes specific framework APIs, or licensing restrictions, will require that a particular implementation is used. In this case a Feature Extension named LAUNCH_FRAMEWORK with Type ARTIFACTS can be used to list one or more artifacts representing OSGi framework implementations.

The list of artifacts is treated as a preference order, with the first listed artifact being used if available, and so on, until a framework is found. If a listed artifact is not an OSGi framework implementation then the Feature Launcher must log a warning and continue on to the next artifact in the list. If the Kind of the feature is MANDATORY and none of the listed artifacts are available then launching must fail with a LaunchException.

The Feature Launcher implementation may identify that an artifact is an OSGi framework implementation in any way that it chooses, however it must recognise framework implementations that provide the Framework Launch API using the service loader pattern, as described in the Launching and Controlling a Framework section of OSGi Core Release 8.

The following code snippet demonstrates a simple example of using the Feature Launcher to start an OSGi framework containing one or more bundles.

// Load the Feature Launcher
ServiceLoader<FeatureLauncher> sl = ServiceLoader.load(FeatureLauncher.class);
FeatureLauncher launcher = sl.iterator().next();
		
// Set up a repository
ArtifactRepository localRepo = launcher.createRepository(Paths.get("bundles"));
		
// Launch the framework
Framework fw = launcher
        .launch(Files.newBufferedReader(Paths.get("myfeature.json")))
        .withRepository(localRepo)
        .launchFramework();

fw.waitForStop(0);

    

In order to support the Zero Code goal of the Feature Launcher Service it is not sufficient to provide a Java API, it must also be possible to launch a feature from the command line in a standard way. To support this implementations of the Feature Launcher must provide an executable JAR file which allows a Feature to be launched from the command line. The general syntax for this command is:

java -jar <impl jar> [opts] [<feature json>]

In the above definition <feature json> is the JSON representation of the Feature to be launched, and opts are command line options. The following options must be supported:

If implementations wish to support any additional options these must only use long-form option names starting with --impl- to ensure that users know the launch command is not portable, and to avoid possible name clashes in future versions of the specification.

The first stage of launching is to determine the feature that should be launched by running the configured feature decoration handlers.

First the Feature Launcher must execute any registered FeatureDecorator instances in the order that they were registered. The feature returned by each decorator is used as input to the next.

Once the decoration is complete the Feature Launcher must iterate through the Feature Extensions defined by the feature. For each Feature Extension the launcher must:

If any of the decorators throws an AbandonOperationException then the launch operation must immediately fail.

Before a framework instance can be created the Feature Launcher must identify a suitable implementation using the following search order:

If no suitable OSGi framework implementation can be found then the Feature Launcher implementation must throw a LaunchException.

Once a suitable framework implementation has been located the Feature Launcher implementation must create and initialize a framework instance. Implementations are free to use implementation specific mechanisms for framework implementations that they recognise. The result of this initialization must be the same as if the Feature Launcher used the org.osgi.framework.launch.FrameworkFactory registered by the framework implementation to create the framework instance.

When creating the framework any framework launch properties defined in the Feature must be used. These are defined as described in Providing Framework Launch Properties and must include any necessary variable replacement as defined by Overriding Feature variables.

Once instantiated the framework must be initialised appropriately so that it has a valid BundleContext. Once initialised the framework is ready for the Feature Launcher implementation to begin populating the framework.

The Feature Launcher must iterate through the list of bundles in the feature, installing them in the same order that they are declared in the feature. If bundle start levels have been defined, as described in Setting the bundle start levels, then the Feature Launcher must ensure that the start level is correctly set for each installed bundle. If no start level metadata or extension is defined then all bundles are installed with the framework default start level.

If the installation of a bundle fails because it is determined by the framework to be a duplicate of an existing bundle then the Feature Launcher must treat the installation as a success. The start level of such a bundle must be set to the lower of its current value and the start level defined for the feature bundle that failed to install.

If a Feature defines one or more Feature Configurations then these cannot be guaranteed to be made available until the ConfigurationAdmin service has been registered. A Feature Launcher implementation may provide an implementation specific way to pre-register configurations, however in general the Feature Launcher should listen for the registration of the ConfigurationAdmin service and immediately create the defined configurations when it becomes available. As Configuration Admin is asynchronous configurations may be created and delivered in any order.

If the CONFIGURATION_TIMEOUT configuration property is set to 0, and one or more Feature Configurations are defined in the Feature being installed, then the implementation must throw a LaunchException unless it is capable of pre-registering those configurations in an implementation specific way.

Once all of the the bundles listed in the feature are installed, and any necessary configuration listener is registered, the implementation must start the OSGi framework. This action will automatically start the installed bundles as defined by the initial start level of the framework, and the start levels of the installed bundles.

The Feature Launcher implementation must delay returning control to the caller until all configurations have been created, subject to the timeout defined by CONFIGURATION_TIMEOUT. The default timeout is 5000 milliseconds, and it determines the maximum length of time that the Feature Launcher implementation should wait to begin creating the configurations. A value of -1 indicates that the Feature Launcher implementation must not wait, and must continue immediately, even if the configurations have not yet been created. If it is not possible to begin before the timeout expires then a LaunchException must be thrown.

Finally, if the minimumStartLevel has been set by the BUNDLE_START_LEVELS extension then the Feature Launcher implementation must check the current start level of the framework. If the current start level is less than the value of minimumStartLevel then the framework's start level must be set to this value.

Once the start process is complete the Framework instance must be returned to the caller.

The following failure modes must all result in a LaunchException being thrown:

If a launching failure is triggered by an exception, for example a BundleException then this must be set as the cause of the LaunchException that is thrown.

If the Feature Launcher implementation fails to launch a feature then any intermediate objects must be properly closed and discarded. For example if an OSGi framework instance has been created then it must be stopped and discarded.

Instances of the Feature Runtime are Thread Safe, regardless of whether the service is implemented as a singleton or otherwise. Any FeatureRuntime.OperationBuilder instances created by the Feature Runtime are not thread safe and must not be shared between threads.

Despite the Operation Builders not being Thread Safe the underlying Feature Runtime must remain Thread Safe, specifically if two Operation Builders complete at the same time then these calls should be handled sequentially such that there are never partially deployed Features present when installing, updating or removing a Feature.

An important role for any management agent is being able to introspect the system to discover its current state. The Feature Runtime enables this through the getInstalledFeatures() method, which returns a snapshot of the current state of the system.

The returned list of snapshots contains one InstalledFeature entry for each installed Feature, in the order that they were installed, and may be empty if no Features have been installed. If the framework was started using a Feature Launcher from the same implementation as the Feature Runtime then the Feature Runtime may choose to represent the launched Feature in the snapshot list. If the launched Feature is included in the snapshot list then it must set isInitialLaunch() to true. Launch features cannot be removed or updated by the Feature Runtime, and any attempt to do so must throw a FeatureRuntimeException

Each Installed Feature provides:

The InstalledBundle snapshots each represent a bundle installed by the Feature Runtime on behalf of the Feature. The Installed Bundle contains the following information:

In addition to bundles Features can contain configurations. The InstalledConfiguration snapshots each represent a configuration created by the Feature Runtime on behalf of the Feature. The Installed Configuration contains the following information:

Installing a Feature uses one of the install methods present on the Feature Runtime. These methods allow the caller to provide the Feature to be installed and return an FeatureRuntime.InstallOperationBuilder to allow the caller to configure their installation operation. Configuration of operations includes:

Once the operation is fully configured then the caller uses the install() method to begin the installation. The end result of installing a Feature is that all of the bundles listed in the Feature are installed, all of the Feature Configurations have been created, all bundles have been marked as persistently started, and the framework start level is at least the minimum level required by the Feature.

Start levels for the bundles in the Feature may be controlled as described in Setting the bundle start levels. If any bundles are installed with a start level higher than the current framework start level then they will be marked persistently started but will not start until the framework start level is changed.

In more complex cases, where multiple features are installed with overlapping bundles or configurations then Merging strategies will be applied to determine which bundles are installed, and what configuration properties will be used when creating or updating a configuration.

If a failure occurs during the installation of a Feature then the Feature Runtime must make every effort to return the system to its pre-existing state. After a failure no new bundles should be installed, any altered configurations returned to their previous states, and the framework start level should be the same as it was prior to the failed installation.

As with the Feature Launcher, in order to successfully locate the bundles listed in a feature the Feature Runtime must have access to one or more Artifact Repositories capable of locating the bundles. These Artifact Repositories are configured into each Operation Builder by the user.

A configured Feature Runtime will typically include one or more pre-defined Artifact Repositories. These pre-defined repositories are available to view via the getDefaultRepositories(). By default all Operation Builders will have access to these repositories when completing. This behaviour can be changed using the useDefaultRepositories(boolean) method.

Additional Artifact Repositories can be added to an Operation Builder by calling the addRepository(String,ArtifactRepository) method. The supplied name is used to identify the repository. If the supplied name is already used for an existing Artifact Repository then it will be replaced or, if the supplied Artifact Repository is null, removed. A named Artifact Repository added in this way will override a default Artifact Repository with the same name.

As described in Overriding Feature variables a feature may define zero or more overridable properties which can be used to alter the deployment of the feature. These properties may be configured into each Operation Builder by calling the withVariables(Map) method. The supplied Map contains the keys and values that will override the variables in the Feature.

Merge operations occur when two or more features reference the same, or similar, items to be installed. The purpose of a merge operation is to avoid unnecessary duplication, and to resolve conflicts.

Merging potentially applies whenever a Feature is installed, updated or removed, and may result in different outcomes depending on the strategy used. All runtime merge functions therefore receive a MergeOperationType indicating which type of operation is currently running.

public Stream<BundleMapping> mergeBundle(MergeOperationType operation,
		Feature feature, FeatureBundle toMerge,
		Collection<InstalledBundle> installedBundles,
		List<FeatureBundleDefinition> existingFeatureBundles) {

	Stream<BundleMapping> result;

	if (operation == MergeOperationType.REMOVE) {
		// Just keep everything the same
		result = installedBundles.stream()
				.filter(i -> !i.getOwningFeatures().isEmpty())
				.map(i -> new BundleMapping(i.getBundleId(),
						i.getOwningFeatures()));
	} else {
		// Find the Installed bundles we might replace
		Version v = RuntimeMerges.getOSGiVersion(toMerge.getID());

		List<InstalledBundle> sameMajor = new ArrayList<>();
		List<InstalledBundle> differentMajor = new ArrayList<>();

		installedBundles.forEach(i -> {
			if (i.getBundle().getVersion().getMajor() == v.getMajor()) {
				sameMajor.add(i);
			} else {
				differentMajor.add(i);
			}
		});

		// Bundles with a different major version stay the same
		result = differentMajor.stream()
			.filter(i -> !i.getOwningFeatures().isEmpty())
			.map(i -> new BundleMapping(i.getBundleId(),
						i.getOwningFeatures()));

		// Find the biggest existing version and see if it's bigger than v
		Optional<InstalledBundle> max = sameMajor.stream()
				.max((a, b) -> a.getBundle()
						.getVersion()
						.compareTo(b.getBundle().getVersion()))
				.filter(m -> m.getBundle().getVersion().compareTo(v) >= 0);

		// Use the old version if it's bigger, or the new if not
		ID key = max.isPresent() ? max.get().getBundleId()
				: toMerge.getID();

		List<ID> featureIds = sameMajor.stream()
				.flatMap(i -> i.getOwningFeatures().stream())
				.collect(Collectors.toList());

		result = Stream.concat(result,
				Stream.of(new BundleMapping(key, featureIds)));
	}
	return result;
}

public Map<String,Object> mergeConfiguration(MergeOperationType operation,
		Feature feature, FeatureConfiguration toMerge, InstalledConfiguration configuration,
		List<FeatureConfigurationDefinition> existingFeatureConfigurations) {

	boolean addedSomething = false;

	Map<String,Object> result = new HashMap<>();

	for (FeatureConfigurationDefinition fcd : existingFeatureConfigurations) {
		FeatureConfiguration fc = fcd.getFeatureConfiguration();
		if(fc.getValues() != null) {
			result.putAll(fc.getValues());
			addedSomething = true;
		}
	}
				
	if(operation != MergeOperationType.REMOVE && toMerge.getValues() != null) {
		result.putAll(toMerge.getValues());
		addedSomething = true;
	}

	return addedSomething ? result : null;
}

Removing a feature from the Feature Runtime Service uses the remove(ID) method to uninstall and remove a feature from the framework. Removing a feature is a comparatively simple operation, and therefore does not require the configuration of an FeatureRuntime.OperationBuilder.

Once the remove method returns the feature will have been removed from the Feature Runtime, and any links to installed bundles and configurations will have been removed. If this leaves any installed bundles or installed configurations with no owners then these will be uninstalled or deleted from the system as appropriate.

If a failure occurs during the removal of a feature then the Feature Runtime must make every effort to fully remove the feature, for example by continuing to remove installed bundles that no longer have any owners. Exceptions that occur must be logged, and upon completion the Feature Runtime must throw a FeatureRuntimeException which indicates the incomplete removal.

It is not an error to remove a feature which does not exist in the Feature Runtime and this must return without error, and without altering the state of the system. It is an error to attempt to remove any feature that returns true for isInitialLaunch(), and any attempt to do so must result in a FeatureRuntimeException.

Updating a Feature uses one of the update methods present on the Feature Runtime. These methods allow the caller to indicate which feature should be updated, and provider the new Feature definition to replace it with. The methods return an FeatureRuntime.UpdateOperationBuilder to allow the caller to configure their update operation. Configuration of operations includes:

Once the operation is fully configured then the caller uses the update() method to begin the update. The end result of updating a Feature is that all of the bundles listed in the new Feature are installed, all of the Feature Configurations in the new Feature have been created, all bundles have been marked as persistently started, and the framework start level is at least the minimum level required by the new Feature. In addition, any bundles and configurations from the old Feature that are not present in the new Feature will have been removed, and any configurations present in both the old and new Features will have been updated with new any new content.

At a high level an update operation is therefore superficially similar to performing a remove operation followed by an install operation. The key difference, however, is that any bundles and configurations shared by both features, or identified by a merge strategy, will not be removed, and instead will become owned by the new Feature.

As for installation, start levels for the bundles in the new Feature will be determined as described in Setting the bundle start levels. If any bundles are installed with a start level higher than the current framework start level then they will be marked persistently started but will not start until the framework start level is changed.

Where the feature update includes overlapping bundles or configurations then Merging strategies will be applied to determine which bundles are installed, and what configuration properties will be used when creating or updating a configuration.

If a failure occurs during the update of a Feature then the Feature Runtime must make every effort to return the system to its pre-existing state. After a failure no new bundles should be installed, any altered configurations returned to their previous states, and the framework start level should be the same as it was prior to the failed installation.

The Feature Installation process has four main phases:

The feature decoration phase must complete before any other phases can begin. The the bundle installation phase and the configuration creation phase may happen in any order, or even with interleaved steps, however the Feature Start phase must not begin until the bundle installation and configuration creation phases are complete.

The Feature removal process has four main phases:

The the feature removal and bundle stop phases may happen in any order, or even with interleaved steps. The same is true for the configuration deletion phase and the bundle removal phase, however these phases must not begin until the bundle stop phase is complete.

The Feature Update Process

The Feature Update Process can be viewed as an interleaved remove and installation operation, following the phases present in both.