THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
The component declarations are read when the declaring bundle is started and the respective components are verified and activated depending on their declaration.
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.
Component
First of all the component must be implemented in a simple Java class. The Declarative Services Specification basically places no restrictions on the contents of this class. If you make use of advanced functionality such as providing an activate() or deactivate() method or using service loopup by event strategy (see 112.3.1 Accessing Services) you will of course have to provide the respective methods.
...
This is of course a very simple and not very intelligently implemented comparator...
Declaration
The next step consists of writing the declaration. I usually put these files in the OSGI-INF folder of the bundle, but the files may be placed anywhere within the bundle or any of the bundle's fragments as long as its path is listed in the Service-Component bundle manifest header.
...
| Code Block |
|---|
Service-Component: OSGI-INF/sample.xml |
Activation
It may well be that the component needs to be notified, when it is activated and deactivated. For this, the component may implement an activate method and a deactivate method. Both methods must be public or protected and take a single argument, the org.osgi.service.ComponentContext. It is recommended for this method to the protected as it is only used by the Service Component Runtime and should of course not be part of the public API of the component.
...
Nothing more needs to be done as the Service Component Runtime automatically recognizes and calls these methods.
Service Binding
The next step would probably be to do some service binding. This is somewhat more overhead, as the referred to services must be declared. On the other hand, you do not have to care to listen for these services. As examples of these strategies we will first use the lookup strategy to access an OSGi HttpService and then we will use the event strategy to access an OSGi LogService (I personally prefer the event strategy, but your mileage may vary).
Looking up the Service
To use the service, the reference must be declared in the service declaration in an reference element. Here is the respective declaration for a log service to lookup:
...
| Code Block |
|---|
protected void activate(ComponentContext context)
{
HttpService http = ( HttpService ) context.locateService( "http" );
}
|
Receiving the Service
The event strategy works by declaring bind and unbind methods in the component descriptor. These methods take a single parameter of the type defined in the reference.interface attribute and must be declared public or protected. As with the activate and deactive it is recommended for the bind and unbind methods to be declared protected as they are generally not part of the public API of the component.
...
Note, that you may refer to the log field in the activate method as we declared the reference as required. In this case the reference is provided to the component in the bind method before the activate method is called.
Maven SCR Plugin
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.
Management
The OSGi Compendium specification defines no management API for Declarative Services. As of version 0.9.0-20071123.131249-8 a simple management 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.
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. |
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:
...
The ScrService allows access to all registered components, to a specific component by component ID or to all registered components of a specific bundle.
Summary
This tutorial just listed some very basic information on Declarative Service. To get more information, for example on hoe the Configuration Admin Service may be used to configure components, refer to the Declarative Services Sepecification in the OSGi Service Platform Service Compendium book.
...