This guide describes a couple of models, by which a components refers to services.

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.

HelloServiceReference class component description

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.

How to reference a service using the Lookup model is shown below:

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 is as follows:

<?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:

The following example uses Event model for referencing a service:

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 component you can find in the snippet below:

<?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>

Disclaimer

The above information is only a small subset of the functionality provided by the OSGi Specification.