Changes between Version 21 and Version 22 of PluginDevelopmentGuide

20.04.2013 23:25:42 (11 years ago)

Consuming a service


  • PluginDevelopmentGuide

    v21 v22  
    862862You see, the plugin main class `TopicmapsPlugin` implements the plugin's service interface `TopicmapsService`. 
     864=== Consuming a service === 
     866Your plugin can consume the services provided by other plugins. To do so your plugin must get hold of the //service object// of the other plugin. Your plugin typically stores that service object in a private instance variable. Through the service object your plugin can call all the service methods declared in the other's plugin service interface. 
     868Behind the scenes the DeepaMehta Core handles a plugin service as an OSGi service. Because of the dynamic nature of an OSGi environment DeepaMehta plugin services can arrive and go away in an unpredictable fashion. Your plugin must deal with that. However, you as a plugin developer must not care about DeepaMehta's OSGi foundation. The DeepaMehta Core hides that from you and provides an easy-to-use API for consuming plugin services. 
     870To consume a plugin service your plugin must override 2 hooks: `serviceArrived` and `serviceGone`. Through the former your plugin gets hold of a service object and in the latter your plugin must release that service object. These 2 hooks are called by the DeepaMehta Core as soon as a desired plugin becomes available resp. goes away. 
     872To tell the DeepaMehta Core which plugin services your plugin wants to consume use the `@ConsumesService` annotation at the `serviceArrived` hook. State the fully qualified names (strings) of all the respective service interfaces as the annotation argument. For more than one service use the array notation: `{"...", "...", ...}`. 
     874The single argument of the 2 `serviceArrived` and `serviceGone` hooks is the respective service object, declared generically just as `PluginService`. (Remember, `PluginService` is the common base interface for all plugin services.) So, casting is required. In `serviceArrived` you typically store the service object in a private instance variable. In `serviceGone` you typically set the instance variable to `null` in order to release the service object. 
     876As an example, see how the //Workspaces// plugin (part of the DeepaMehta Standard Distribution) consumes the //Facets// service: 
     880package de.deepamehta.plugins.workspaces; 
     882import de.deepamehta.plugins.facets.service.FacetsService; 
     884import de.deepamehta.core.osgi.PluginActivator; 
     885import de.deepamehta.core.service.PluginService; 
     886import de.deepamehta.core.service.annotation.ConsumesService; 
     890public class WorkspacesPlugin extends PluginActivator { 
     892    private FacetsService facetsService; 
     894    // *** Hook Implementations *** 
     896    @Override 
     897    @ConsumesService("de.deepamehta.plugins.facets.service.FacetsService") 
     898    public void serviceArrived(PluginService service) { 
     899        facetsService = (FacetsService) service; 
     900    } 
     902    @Override 
     903    public void serviceGone(PluginService service) { 
     904        facetsService = null; 
     905    } 
     908You see the Workspaces plugin consumes just one plugin service: the //Facets// service. So, the `@ConsumesService`argument is just one string. The `PluginService` object passed to the 2 hooks needs not being further investigated.