dependencymanager/docs/whatsnew.mdtext - onos-felix - Gitiles

 # What's new in DependencyManager 4.0

 DependencyManager 4.0 has been significantly reworked to improve support for concurrency. The following principles form the basis of the new concurrency model in DM4.

  * All external events that influence the state of dependencies are recorded and given to the serial executor of the component. We record whatever data comes in, so when the actual job is run by the serial executor, we still have access to the original data without having to access other sources whose state might have changed since.
  * The serial executor of a component will execute a job immediately if it is being called by the thread that is already executing jobs.
  * If the serial executor of a component had not yet started a job, it will queue and start it on the current thread.
  * If the serial executor gets invoked from a different thread than the one currently executing jobs, the job will be put at the end of the queue. As mentioned before, any data associated with the event will also be recorded so it is available when the job executes.
  * State in the component and dependency can only be modified via the serial executor thread. This means we don't need explicit synchronization anywhere.

 DependencyManager 4 now also supports parallel execution of component wiring.

 Added support for parallelism: To allow components to be started and handled in parallel, you can now register in the OSGi service registry a ComponentExecutorFactory service that is used to get an Executor for the management of all components dependencies/lifecycle callbacks. See javadoc from the org.apache.felix.dm.ComponentExecutorFactory interface for more information.

 You can also take a look at the the org.apache.felix.dependencymanager.samples project, which is registering a ComponentExecutorFactory from org.apache.felix.dependencymanager.samples.tpool bundle.

 See also the following property in the org.apache.felix.dependencymanager.samples/bnd.bnd

 	org.apache.felix.dependencymanager.parallel=\
 		'!org.apache.felix.dependencymanager.samples.tpool, *',\

 Here, all components will be handled by Executors provided by the ComponentExecutorFactory, except those having a package starting with "org.apache.felix.dependencymanager.samples.tpool" (because the threadpool is itself defined using the Dependency Manager API).

 In addition, some new features have been implemented in dependency manager:

 * Auto Config Iterable fields: AutoConfig dependencies can be applied on Iterable<Service> fields in order to be able to traverse currently injected services safely. The Iterable must be parameterized with the Service type. See org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/Spellcheck.java for an example.

 * AutoConfig Map field: AutoConfig dependencies can be applied on a field with a Map<Service, Dictionary> type, allowing to traverse currently injected services safely, including service properties. The Map must be traversed using the Map.Entry iterator. See javadoc for DependencyManager.setAutoConfig().

 * Inject Configuration on separate callback instance: Configuration can be injected on a separate callback instance, like a CompositionManager for example. See an example in the samples, in org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/compositefactory/Activator.java.
 See FELIX-2706

 * Added propagate flag for Service Adapters: you can now choose to propagate or not adaptee service properties. See FELIX-4600

 * "Top" command in the shell: a "top" command is now available from the shell and can be used to display all top components sorted by their init/start elapsed time.

 * The Annotations plugin can now automatically generate a Require-Capability header on the Dependency Manager Runtime bundle.
 Use "add-require-capability=true" option in the plugin declaration property to enable this new feature (see FELIX-4676):
 **  -plugin: org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin; add-require-capability=true

 * The Configuration Dependency Configuration dependency now supports a "name" attribute, allowing to dynamically configure configuration pids from the @Init method. see FELIX-4777

 * Added a benchmark tool for dependency manager (not released, only available from the trunk, see dependencymanager/org.apache.felix.dependencymanager.benchmark/README

 * The Annotations "Factory Sets" are deprecated and have been replaced by a nice api exported by the runtime bundle. See FELIX-4684

 # What's changed in DependencyManager 4.0

 * The Annotations processor is not generating anymore the Import-Service/Export Service by default (no need to specify the "build-import-export-service=false" option in the
 annotations plugin if you don't need to generate automatically the deprecated headers.

 * The Dependency Manager metatype Annotations are now deprecated and it is encouraged to use standard bndtools metatypes.
 See org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/annot/DictionaryConfiguration.java for an example.
 You can also check http://www.aqute.biz/Bnd/MetaType for more information about the bnd metatypes annotations.
	# What's new in DependencyManager 4.0

	DependencyManager 4.0 has been significantly reworked to improve support for concurrency. The following principles form the basis of the new concurrency model in DM4.

	* All external events that influence the state of dependencies are recorded and given to the serial executor of the component. We record whatever data comes in, so when the actual job is run by the serial executor, we still have access to the original data without having to access other sources whose state might have changed since.
	* The serial executor of a component will execute a job immediately if it is being called by the thread that is already executing jobs.
	* If the serial executor of a component had not yet started a job, it will queue and start it on the current thread.
	* If the serial executor gets invoked from a different thread than the one currently executing jobs, the job will be put at the end of the queue. As mentioned before, any data associated with the event will also be recorded so it is available when the job executes.
	* State in the component and dependency can only be modified via the serial executor thread. This means we don't need explicit synchronization anywhere.

	DependencyManager 4 now also supports parallel execution of component wiring.

	Added support for parallelism: To allow components to be started and handled in parallel, you can now register in the OSGi service registry a ComponentExecutorFactory service that is used to get an Executor for the management of all components dependencies/lifecycle callbacks. See javadoc from the org.apache.felix.dm.ComponentExecutorFactory interface for more information.

	You can also take a look at the the org.apache.felix.dependencymanager.samples project, which is registering a ComponentExecutorFactory from org.apache.felix.dependencymanager.samples.tpool bundle.

	See also the following property in the org.apache.felix.dependencymanager.samples/bnd.bnd

	org.apache.felix.dependencymanager.parallel=\
	'!org.apache.felix.dependencymanager.samples.tpool, *',\

	Here, all components will be handled by Executors provided by the ComponentExecutorFactory, except those having a package starting with "org.apache.felix.dependencymanager.samples.tpool" (because the threadpool is itself defined using the Dependency Manager API).

	In addition, some new features have been implemented in dependency manager:

	* Auto Config Iterable fields: AutoConfig dependencies can be applied on Iterable<Service> fields in order to be able to traverse currently injected services safely. The Iterable must be parameterized with the Service type. See org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/Spellcheck.java for an example.

	* AutoConfig Map field: AutoConfig dependencies can be applied on a field with a Map<Service, Dictionary> type, allowing to traverse currently injected services safely, including service properties. The Map must be traversed using the Map.Entry iterator. See javadoc for DependencyManager.setAutoConfig().

	* Inject Configuration on separate callback instance: Configuration can be injected on a separate callback instance, like a CompositionManager for example. See an example in the samples, in org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/compositefactory/Activator.java.
	See FELIX-2706

	* Added propagate flag for Service Adapters: you can now choose to propagate or not adaptee service properties. See FELIX-4600

	* "Top" command in the shell: a "top" command is now available from the shell and can be used to display all top components sorted by their init/start elapsed time.

	* The Annotations plugin can now automatically generate a Require-Capability header on the Dependency Manager Runtime bundle.
	Use "add-require-capability=true" option in the plugin declaration property to enable this new feature (see FELIX-4676):
	** -plugin: org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin; add-require-capability=true

	* The Configuration Dependency Configuration dependency now supports a "name" attribute, allowing to dynamically configure configuration pids from the @Init method. see FELIX-4777

	* Added a benchmark tool for dependency manager (not released, only available from the trunk, see dependencymanager/org.apache.felix.dependencymanager.benchmark/README

	* The Annotations "Factory Sets" are deprecated and have been replaced by a nice api exported by the runtime bundle. See FELIX-4684

	# What's changed in DependencyManager 4.0

	* The Annotations processor is not generating anymore the Import-Service/Export Service by default (no need to specify the "build-import-export-service=false" option in the
	annotations plugin if you don't need to generate automatically the deprecated headers.

	* The Dependency Manager metatype Annotations are now deprecated and it is encouraged to use standard bndtools metatypes.
	See org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/annot/DictionaryConfiguration.java for an example.
	You can also check http://www.aqute.biz/Bnd/MetaType for more information about the bnd metatypes annotations.