This document describes the set of functions provided by the Service Component Runtime Bundle. It also contains a developer's guide to managing OSGi services by the means defined in the OSGi Declarative Services Specification Release 4.2.

Contents:

• Bundle Information
  • Bundle JAR
  • Symbolic Name
  • Import
  • Export
• Overview
  • Service Component
  • Service Component Runtime
  • Component Description
  • Component Context
  • Component Factories
  • Component Properties
• Service Component API
• Creating a Component
  • Component Description Manifest Header
  • Component Description Elements
  • Providing a Service
  • Referencing a Service
    • Lookup Model
    • Event Model
  • Using the Component Factory service
  • Using a Service Factory
  • Providing Configurable Component Properties
• Services
  • Pluggable Commands
• Console Commands
• System Properties
• References

Bundle Information

Bundle JAR

The JAR file of the Service Component Runtime bundle is fw.scr.jar , located in the bundles directory.

Symbolic Name

The symbolic name of the Service Component Runtime bundle is com.prosyst.mbs.scr .

Import

Export

None.

Overview

The Service Component Runtime bundle provides an implementation of the Service Component Runtime according to the OSGi Declarative Services Specification Release 4.2.

The specification defines a declarative model of using OSGi services that allows delaying the creation of the service object till the moment it will be actually used. Using the declarative services model provides the following benefits:

• Delayed creation of service objects and their class loaders.
• Reduced startup time and memory footprint.
• Low resource requirements as the model is applicable on resource constrained systems.
• Simplified mechanism for authoring services.
• Simplified programming model provided by a lightweight API.
• Decreased amount of required code.

Service Component

The declarative services model defines a service component as main unit for manipulating with OSGi services functionality.

A service component is an entity consisting of a Java class and its XML description, which can register or reference a service in a lazy fashion. Both, service component's Java class and its description are packed in a bundle that is deployed in the OSGi framework where it functions like any traditional OSGi bundle.

A service component has the following features:

• Its lifecycle is contained in its bundle's lifecycle.
• It is uniquely identified by its implementation class.
• It can provide services to the OSGi framework.
• It can reference services provided by other components and traditional OSGi bundles in the framework.
• It can be configured through the OSGi Configuration Admin service.

A service component will be referred to as component and its XML description as component description from now on in this document.

Service Component Runtime

The Service Component Runtime (SCR) is the module that manages the components and their lifecycle. It performs the following functions:

• Track component dependencies and manage their dynamics.
• Activate the component when its dependencies are met.
• Publish the component in the service registry on its activation.
• Create the component instance when the component is going to be used.
• Dispose component instances when they are no longer used.

Component Context

A component may receive its Component Context through its activate method. Component Context can be used to locate services declared in the component's description. It can be used also to enable or disable components from the component's bundle.

Component Description

The declaration of a component in an XML format is the component description . It uniquely identifies the component to the SCR and provides information about the component's functionality that will be used by the SCR to perform its management operations.

The component description provides information for:

• The name of the component
• The name of the Java class implementing the component
• Services provided by the component
• Services referenced by the component
• Configurable properties of the component

Component Factories

The declarative services model supports producing multiple instances of the same component type in compliance with the Service Factory concept in the OSGi framework.

Multiple instances of same component type can be produced by:

• A Component Factory service - It is registered as an OSGi service by the SCR and it can create multiple instances of a component.
• A Managed Service Factory - If defined in a Configuration Metatype XML, the SCR can produce a Managed Service Factory for a component with a set of properties. For each newly produced configuration instance from the SCR-provided Managed Service Factory, the SCR produces a new component instance. If the component registers a service, for each component instance a new service object will be created with property values taken from the configuration instance.
• A Service Factory - A component can be declared in its description to use a Service Factory without need to implement an org.osgi.framework.ServiceFactory . It will produce new instances of the component for each referencing bundle or component. The properties of the service provided by the component will be the same for all newly produced component instances.

Note: A component cannot be declared as a factory component and use a Managed Service Factory and Service Factory at the same time. You have to choose only one of these factories to produce new instances of the same component type.

Component Properties

A component can have a set of properties specified in three places in the following order of precedence:

• Properties passed to the Component Factory service when creating new instances of the same component type.
• Properties retrieved from the Configuration Admin service.
• Properties specified in the component description. In the case of a service-providing component, they are exported as properties of registered service with specific default values. The values of these properties can be overridden through the Configuration Admin service or by passing new property values to the newInstance method of the Component Factory service. New component properties can be passed to this method, as well.

Each component also has COMPONENT_NAME property defined in its description and COMPONENT_ID property given by the SCR. These properties are obligatory and their values cannot be overridden as they uniquely identify the component to the SCR.

Service Component API

The Service Component API is contained in the org.osgi.service.component package. It is a lightweight API that defines base interfaces for using components.

Creating a Component

To create a component, write its implementation Java class and component description then pack them into a bundle JAR file.

Component Description Manifest Header

A bundle providing a component must have special header in its manifest that specifies the XML document of the component description:

Service-Component: <path to the XML document's location>

For example: Service-Component: myComponent/ComponentDescriptionXML.xml

Component Description Elements

The elements included in a component description vary depending on the functionality a component provides.

Generally, the possible elements of a component description are:

• component - This is the opening element of the component description. It can have the following attributes:
  • name - The component name. A component's name must be unique, it will be also used as a service PID in case the component implements a service or its properties are exported for configuration in the OSGi Configuration Admin service. This attribute is mandatory.
  • factory - This attribute is included for factory components and specifies a factory name.
  • immediate - This attribute specifies if the component should be activated right after its bundle is deployed and its dependencies are met. The default value is "false". This attribute is optional.
  • enabled - This attribute indicates whether the component should be enabled for usage immediately after its bundle is started. Its default value is "true". If set to "false" the component will remain disabled until it is explicitly enabled.The attribute is optional.
• implementation - The component's implementation class. This element has the following attribute:
  • class - The fully qualified name of the component's implementation class.
• service - This element provides information about the services registered by the component. Each provided service interface name is declared in a provide sub-element with an interface=<interface_name> attribute. The service element can have the following attribute:
  • servicefactory - It enables using a Service Factory concept for the provided service. Its default value is "false". When "true", a different component configuration is created, activated and its component instance returned as a service object for each bundle that requests the corresponding service.
• reference - This element provides information about the references a component makes to other services. The reference element can include the following attributes:
  • name - The name of the reference.
  • interface - The fully qualified name of the referenced service interface.
  • bind - The name of the method binding the service object to the component. See "Referencing a Service " section.
  • unbind - The name of the method unbinding the service object from the component. See "Referencing a Service "section.
  • cardinality - The reference cardinality.
  • target - A filter that further constraints the set of referenced services.
• property - A component property. It has the following attributes:
  • name - The name of the property.
  • value - The default value of the property.
  • type - The property type. As the default type is "String", you are not required to include the type attribute for a String property.
• properties - Here you can specify the path to a standard Java properties file containing the set of properties that the component uses.

For further information on the component description elements, refer to the component description schema provided in the OSGi Declarative Services Specification Release 4. .

Providing a Service

To create a component that provides a service, you have to go through the following stages:

1. Write the service interface.
   
   

   package simple.service; public interface HelloService { public void hello(); }

   Listing 1:HelloService interface
   
2. Write the service interface implementation class which will be the component's implementation class as well:
   
   

   package simple.service.impl; import simple.service.HelloService; public class HelloServiceImpl implements HelloService { public void hello() { System.out.println("Hello components!"); } }

   Listing 2: HelloService implementation class.
   
3. Write the component description.
   
   

   <?xml version="1.0" encoding="UTF-8"?> < scr:component name =" HelloServiceComponent" xmlns:scr =" http://www.osgi.org/xmlns/scr/v1.0.0"> <!-- The component's implementation class--> <implementation class =" simple.service.impl.HelloServiceImpl"/> < service > <!--The interface of the service provided by the component--> < provide interface =" simple.service.HelloService"/> </ service > </scr:component>

   Listing 3: HelloServiceComponent XML description

Referencing a Service

A component can reference services provided by other components or bundles in the framework by using one of the following models:

• Lookup model - In this model you have to call the locateService or locateServices methods of the ComponentConext object provided to your component's Java class. The locateService(s) method allows a component to "look up" the services it needs instead of keeping their objects. This model is suitable for referencing services with dynamic behavior.
• Event model - Using this model requires writing bind and unbind methods for the referenced service in the component's implementation class. The bind method will be called by the SCR to obtain the service object and the unbind to withdraw it. These methods must take a single parameter and the service object must be assignable to the parameter's type or the parameter has to be ServiceReference . The binding and unbinding methods are declared in the reference element of the component's description.

Lookup Model

To reference a service using this model:

1. Write a reference element in the component's description to declare the referenced service(s).
2. Get the component's ComponentContext object allocated to the instance of your component's class, passed as an argument to the component's activate method.
3. Call the locateService or locateServices method of the ComponentContext .

The code example snippet below contains a component's implementation class which references the service provided by the component introduced in the "Providing a Service " section.

package simple.service.reference;

import org.osgi.service.component.ComponentContext;
import simple.service.HelloService;

public class HelloServiceReference {

  protected ComponentContext context;
  HelloService helloService;
	
  protected void activate(ComponentContext ctxt){
		
     this.context = ctxt;
		
     helloService = (HelloService) ctxt.locateService("helloService");
     helloService.hello();
  }
	
  protected void deactivate(ComponentContext ctxt){
     this.context = null;
  }
}

And the component description:

<?xml version="1.0" encoding="UTF-8"?>
<

scr:component name

="

HelloServiceReference" 


xmlns:scr

="

http://www.osgi.org/xmlns/scr/v1.0.0">
  <implementation class

="

simple.service.reference.HelloServiceReference"/>
  <

reference name

="

helloService"
     

interface

="

simple.service.HelloService"
  />	
</

scr:component

>

Event Model

To obtain a service using this model:

1. Write bind and unbind methods.
2. Declare them in the reference element of the component description.

The SCR passes the referenced service as an argument of the bind and unbind methods.

The listing below contains a class which implements bind (setHelloService ) and unbind (unsetHelloService ) methods to obtain the service provided by the component introduced in the "Providing a Service " section:

package simple.service.reference;

import simple.service.HelloService;

public class HelloServiceBind {

  HelloService helloService;
	
  public void setHelloService(HelloService helloService){
     this.helloService = helloService;

     helloService.hello();
  }
	
  public void unsetHelloService(HelloService helloSerivce){
     this.helloService = null;
  } 
}

The XML description of the HelloServiceBind class:

<?xml version="1.0" encoding="UTF-8"?>
<

scr:component name

="

HelloServiceBind" 

xmlns:scr

="

http://www.osgi.org/xmlns/scr/v1.0.0">
  <implementation class

="

simple.service.reference.HelloServiceBind"/>
  <

reference name

="

helloService"
     

interface

="

simple.service.HelloService"
     

bind

="

setHelloService"
     

unbind

="

unsetHelloService"
  />	
</

scr:component

>

Using the Component Factory service

To use the Component Factory service:

1. Define the component you want to produce multiple instances of as a factory component. To define a component as a factory component, declare a factory="<factory_name>" attribute in the component element of its description.
2. Declare component properties in the component's description that will be passed to the Component Factory service when creating new instances of the same component type. Component properties are declared in property or properties elements as described in the "Component Description Elements " section.
3. Get the Component Factory OSGi service and call its newInstance method by providing some custom properties.

The Component Factory, that the SCR creates and associates with the component definition, can create multiple instances if the component is satisfied. If the a factory component's dependencies are not met, the component is disposed and the Component Factory service is unregistered.

If the factory component is supposed to provide a service, a service object will be registered on its behalf each time the newInstance method of the associated ComponentFactory is called.

Following is the implementation class of a factory component that provides the Hello Service introduced in the "Providing a Service " section. For simplicity, the service's hello method is called in the component's activate method:

package simple.service.impl;

import org.osgi.service.component.ComponentContext;
import simple.service.HelloService;

public class HelloServiceImpl implements HelloService {

  ComponentContext context;
	
  protected void activate(ComponentContext ctxt){
     this.context = ctxt;
     
     hello();		
  }
	
  public void hello() {
		
     System.out.println("Hello components!");
  }
	
  protected void deactivate(ComponentContext ctxt){
     this.context = null;
 }
}

And the component description where the component is declared as a factory component:

<?xml version="1.0" encoding="UTF-8"?>
<

scr:component name

="

HelloComponentFactory" 

factory

="

hello.component.factory" 


xmlns:scr

="

http://www.osgi.org/xmlns/scr/v1.0.0">
  <implementation class

="

simple.service.impl.HelloServiceImpl"/>
  <

service

>
      <

provide interface

="

simple.service.HelloService"/>
  </

service

>
  <

property name

="

Prop1" 

value

="

init value"/>
  <

property name

="

Prop2" 

type

="

Integer" 

value

="

0"/>
</

scr:component

>

The next example is a component which gets the Component Factory service and creates an instance of the factory component from the previous example:

package simple.component.factory;

import java.util.Hashtable;
import org.osgi.service.component.ComponentContext;
import org.osgi.service.component.ComponentFactory;
import org.osgi.service.component.ComponentInstance;
public class HelloComponentFactoryRef {
	
   ComponentContext context;
   ComponentFactory factory;
   ComponentInstance compInstance;
   Hashtable factoryProps;

   public void setFactory(ComponentFactory cmpFact){
     
      this.factory = cmpFact;
      factoryProps = new Hashtable();
      factoryProps.put("Prop1","new value");
      factoryProps.put("Prop2",new Integer(20));
			
      compInstance = factory.newInstance(factoryProps);	
   }
		
   public void unsetFactory(ComponentFactory cmpFact){
      
	  this.factory = null;
   }

}

The next listing contains the component description of the SimpleComponentFactoryRef component. Its reference element includes a target attribute who's value is an LDAP filter that constrains the referenced Component Factory services to the one associated with the SimpleComponent component. The filter is in (component.factory=<component factory name>) format.

<?xml version="1.0" encoding="UTF-8"?>


<

scr:component

 

name

="

HelloComponentFactoryRef" 

xmlns:scr

="

http://www.osgi.org/xmlns/scr/v1.0.0">
  <

implementation class

="

simple.component.factory.HelloComponentFactoryRef"/>
  <

reference name

="

ComponentFactoryRef"
     

interface

="

org.osgi.service.component.ComponentFactory"
     

bind

="

setFactory"
     

unbind

="

unsetFactory"
     

target

="

(component.factory=hello.component.factory)"
  />
</

scr:component

>

Using a Service Factory

To create unique instances of a component-providing service for each bundle referencing the service over the traditional OSGi Framework API or by using another service component, declare a servicefactory="true" attribute in the service element of the component's description like this:

<service servicefactory="true">

Providing Configurable Component Properties

To make a component's properties configurable through the Configuration Admin, write a metatype XML resource to export them as metadata as defined in the OSGi Metatype Service Specification, linking the defined metatype with the component name. Then, create the component configuration in the Configuration Admin using the component name as the configuration PID.

The example that follows is an XML document providing the metadata of a component's properties. Their IDs must be same as their names declared in the component description:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<

metatype:MetaData xmlns:metatype

="

http://www.osgi.org/xmlns/metatype/v1.0.0"


xmlns:xsi

="

http://www.w3.org/2001/XMLSchema-instance">
  <OCD name

="

Hello Component Config" 

id

="

ocd1">
     <

AD name

="

Property One" 

id

="

Prop1" 

type

="

String" 

default

="

init value"/>		
     <

AD name

="

Property Two" 

id

="

Prop2" 

type

="

Integer" 

default

="

0"/>
  </

OCD

>
  <

Designate pid

="

HelloServiceComponent">
     <

Object ocdref

="

ocd1"/>
  </

Designate

>
</

metatype:MetaData

>

If you want to produce and preconfigure multiple component instances, set the factory attribute of the Designate element to true to indicate that this metatype will be for a Managed Service Factory.

Services

Pluggable Commands

The Services Component Runtime bundle registers a com.prosyst.util.pcommands.PluggableCommands service that provides the console commands of the scr group. Refer to the "Console Commands " section for description of the scr command.

Console Commands

The Services Component Runtime bundle provides the scr group of commands in the framework text console for executing operations over the components available in the framework. The scr command group is enabled only when there are instantiated components in the framework.

System Properties

mbs.component.idle_timeout

1000

mbs.component.block_timeout

30000

mbs.scr.dontDisposeInstances

true

References

• OSGi Declarative Services Specification Release 4.2.
• Service Component API.