...
The Apache Felix Service Component Runtime described by the OSGi Desclarative Declarative Services Specification is implemented by the org.apache.felix.scr
bundle. As specified, the components must be declared in XML-formatted descriptor files which in turn must be listed in the Service-Component
header of the declaring bundle.
The component declarations are read when the declaring bundle is started and the respective components are verified and activated depending on their declaration.
The Apache Felix Declarative Services implementation with the OSGi Declarative Services Specification Version 1.1 passes the OSGi CT.
Example
To help you get a head start, here is an example of using Declarative Services. You will find more examples in the trunk/examples
folder of the Apache Felix Project.
...
To simplify the tasks of generating the SCR Desriptor and adding the Service-Component
header to the bundle manifest, the Apache Felix Maven SCR Plugin may be used. This helps keeping the descriptor and the code in sync especially during development.
...
.
Configuration
The Apache Felix Declarative Services implementation can be configured with Framework properties which are read on startup of the implementation bundle and Configuration Admin Service configuraiton which is provided by the Configuration Admin Service to the service PID org.apache.felix.scr.ScrService
.
The following properties are supported:
Property | Default Value | Description |
---|---|---|
| 1 | Defines a logging level at which messages are logged. This configuration property is converted to an
|
| | sets the log level to |
| | Disables logging completely if set to |
| | Enables Component Factory functionality not compliant with the Declarative Services 1.1 specification if set to |
| | Enables workaround functionality to pass the OSGi CT. Generally this property should not be set to |
| | Whether or not to keep instances of delayed components once they are not referred to any more. The Declarative Services specifications suggests that instances of delayed components are disposed off if there is not used any longer. Setting this flag causes the components to not be disposed off and thus prevent them from being constantly recreated if often used. Examples of such components may be EventHandler services. The default is to dispose off unused components. See FELIX-3039 for details. |
This configuration mechanism is implemented in the ScrConfiguration and its helper classes.
Non-Standard Component Factory Behaviour
Note |
---|
If you don't know what this section is about, just ignore it and leave the |
Versions of the Apache Felix Declarative Services implementation prior to 1.2.0 supported handling of Component Factory components which is not specification compliant.
This behaviour assumes the component name of the Component Factory component to be Service Factory PID and each configuration with this Service Factory PID causes the service component runtime to actually create and activate an instance of the Component Factory component automatically. This is not foreseen by the specification which defines instantiation of Component Factory components as being purely application controled and not configuration induced.
To have components instantiated with factory configurations, regular components should be used. This case each factory configuration instance will create a component instance.
If you know that you are using Component Factory components depending on this non-standard behaviour you may set the ds.factory.enabled
configuration property to true
(the default of this property is false
thus disabling this functionality for specification compliance).
For details also refer to FELIX-1416
Administration
The OSGi Compendium specification defines no management administrative API for Declarative Services. As of version 0.9.0-20071123.131249-8 a simple management administrative API is provided the Apache Felix implementation. The bundle itself also has a Felix Shell Command providing easy commands to introspect the states of the registered components.
The Apache Felix Web Console has built-in support for Declarative Services administration based on this API.
Shell Command
The management API is made available to the Felix Shell as the scr
command with a short list of subcommands:
Synopsis | Description |
---|---|
| Show help of the specific |
| List registered components of the bundle specified by |
| Show a complete information dump of the given component. This dump includes the name, status, provided services and information on the service references. |
| Enable the given component if not already enabled. If the component is already destroyed or enabled, this command has no effect. |
| Disable the given component if not already disabled. If the component is already destroyed or disabled, this command has no effect. |
The administrative API commands are also available in the Gogo shell where the subcommand names must be prefixed with the name space scr
. Thus the list
command corresponds to scr:list
in the Gogo shell.
API Use
The API consists of the main interface org.apache.felix.scr.ScrService
and two helper interfaces org.apache.felix.scr.Component
describing a registered component and org.apache.felix.scr.Reference
describing a single reference of a registered component. To access the management API, client applications just ask for the ScrService
as usual:
...