The
OSGi Compendium Release 7 specification contains version 1.4 of the
Declarative Services specification which includes a number of exciting new features.
If you are not familiar with Declarative Services (DS), it is the dependency injection model for OSGi programming that fully supports OSGi modularity and services and the dynamic nature of both. Declarative Services uses a declarative model for publishing, finding and binding to OSGi services. This model simplifies the task of authoring OSGi services by performing the work of registering the service and handling service dependencies. This minimizes the amount of code a programmer has to write; it also allows service components to be loaded only when they are needed. As a result, bundles need not provide a
BundleActivator class to collaborate with others through the service registry.
Declarative Services was introduced as an OSGi specification in 2005 supporting method injection. DS has been updated to add an annotation-based programming model in version 1.2 and to add support for field injection, component property types, and introspection in version 1.3. Version 1.4 of DS now adds support for constructor injection, activation fields, enhancements to component property types, and a number of smaller enhancements.
Service Component
A Service Component is a Java class which can be optionally registered as an OSGi service and can optionally use OSGi services. The runtime for DS is called Service Component Runtime (SCR) and uses component descriptions in the bundle (in XML form) to instantiate and wire components and services together. The component descriptions are used by SCR as a performance choice so that SCR can avoid processing all classes in a bundle to search for annotations at runtime. But writing XML is not really great for developers, so DS provides annotations which can be used in source code. Tooling, such as
Bnd, is then used to generate the component description XML from the annotations during bundle building. So when the following example service component is included in a bundle by Bnd, Bnd will process the annotations and generate the component description XML for the component in the bundle.
@Component
public class ExampleImpl implements Example {
@Reference(service=LoggerFactory.class)
private Logger logger;
@Override
public void say(String message) {
logger.info(message);
}
}
<scr:component name="example.provider.ExampleImpl"
xmlns:scr="http://www.osgi.org/xmlns/scr/v1.3.0">
<implementation class="example.provider.ExampleImpl"/>
<service>
<provide interface="example.api.Example"/>
</service>
<reference field="logger"
interface="org.osgi.service.log.LoggerFactory"
name="Logger"/>
</scr:component>
Constructor Injection
Prior to 1.4, DS supported method injection:
private Example example;
@Reference
void setExample(Example example) {
this.example = example;
}
and field injection:
@Reference
private Example example;
New to DS 1.4 is support for
constructor injection:
private final Example example;
@Activate
public ExampleImpl(@Reference Example example) {
this.example = example;
}
The
Activate annotation is used to mark the constructor to be used by SCR for constructor injection. By default, SCR will use the public no-parameter constructor. Since, by their nature, constructors can only be called once per object instance, only
static policy references can be used for constructor injection. For dynamic policy references, you will need to use either field or method injection.
Both
scalar and multiple cardinality references are supported for constructor injection. Here is an example of multiple cardinality where the type of the referenced service is determined from the generic signature of the parameter.
private final List<Example> examples;
@Activate
public ExampleImpl(@Reference List<Example> examples) {
this.examples = examples;
}
In addition to injecting the service objects for referenced services, you can also inject objects related to referenced services just as you can also do for method and field injection.
@Activate
public ExampleImpl(
@Reference
ServiceReference<Example> sr,
@Reference
ComponentServiceObjects<Example> so,
@Reference(service=Example.class)
Map<String,Object> serviceProps,
@Reference
Map.Entry<Map<String,Object>,Example> tuple) {
…
}
Finally, constructor injection also supports passing activation objects to the component constructor.
Activation objects are the objects you can pass to the activate method. Any constructor parameter not annotated with
Reference must be an activation object.
public @interface Props {
int my_port() default 8080;
}
@Activate
public ExampleImpl(
ComponentContext context,
BundleContext bc,
Map<String,Object> componentProps,
Props props) {
…
}
Activation Fields
In addition to supporting injecting
activation objects using constructor injection, and also method injection via the
activate method, DS 1.4 adds support for field injection of activation objects. A field of the type of an activation object can be annotated with
Activate and SCR will inject the activation object into the field after object construction.
@Activate
private ComponentContext context;
@Activate
private BundleContext bc;
@Activate
private Map<String,Object> componentProps;
@Activate
private Props props;
Component Property Type Enhancements
Component property types were added to DS in version 1.3. A component property type is an annotation that is used to both define and consume component properties in a type safe manner. For example, we can define the following component property type:
public @interface Props {
int my_port() default 8080;
}
When this component property type is used in a component:
@Activate
private Props props;
it both defines the component property named
my.port (
the annotation element names are mapped to component property names) and sets its value to
8080 in the generated component description. SCR will also generate an instance of the component property type which can be injected into the component instance and then be used to access the component property in a type safe manner.
int my_port = props.my_port();
And since DS supports
type conversion for the component property value, even if the component property value was a string value of
"8080", your component implementation does not need to worry.
Lets say you wanted to set the
my.port component property for your component to a value other than
8080 and could not change the declaration of the component property type (because other components might also use the same component property type), in DS 1.3 you would have to use a non-type-safe string:
@Component(property={"my.port:Integer=9080"})
New for DS 1.4 is the ability to also use component property types to annotate components and set property values in a type-safe manner. To use a component property type in this way, you must annotate the component property type with
ComponentPropertyType. This meta-annotation lets Bnd know the annotation on the component class must be processed as a component property type for setting component property values.
@ComponentPropertyType
public @interface Props {
int my_port() default 8080;
}
@Component
@Props(my_port=9080)
public class ExampleImpl implements Example {
@Activate
private Props props;
…
}
Now when Bnd processes the component during bundle creation, the generated component description will set the value of the
my.port component property to
9080.
There is also special support for component property types which are
single-element annotations and
marker annotations. For a single-element annotation, the
component property name for the
value element is derived from the component property type name instead of the element name
value. For a marker annotation, a component property name is derived from the component property type name, just as for single-element annotations, and the component property value is
Boolean.TRUE. Marker annotations are only useful for setting a component property to the value
true. They cannot be used to get a property value since they have no elements to call from your component implementation.
Sometimes component property names can be long. For example,
osgi.http.whiteboard.servlet.name. In order to make using component property types more friendly in source code, DS supports the use of the
PREFIX_ final field so that shorter element names can be mapped to longer component property names. For example, if we need the component property name
com.acme.server.port and we don't want to name the element
com_acme_server_port or name the single-element annotation
ComAcmeServerPort, we can use the
PREFIX_ final field to add a name prefix to the mapped component property name.
@ComponentPropertyType
public @interface ServerPort {
String PREFIX_ = "com.acme.";
int value() default 8080; // com.acme.server.port property
}
This new support for component property types is so useful, you will see we have defined quite a number of them throughout many of the R7 specifications to make using those specifications with DS much nicer. The DS spec defines some component property types for
basic service properties and both the updated
Http Whiteboard and the new
JAX-RS Whiteboard specifications define component property types specific to their specifications.
And There is More
I just touched on, what I feel, are the major updates for Declarative Services in the new version 1.4 specification which is part of OSGi Compendium Release 7. Make sure to check out the
Changes section in the spec to see all the updates for 1.4.
PS. While the DS 1.4 specification is done, tooling and runtimes which support all of these new features may still be under development (at the time of this writing).
Want to find out more about OSGi R7?
This meeting will be a workshop focusing on the recent OSGi Release 7 and there are three talks which will include a review on whats new in Release 7, the updated OSGi enRoute for R7 and an intro to gecko.io. In addition there will be a Q&A and discussion session. The full agenda is available here.
