Changes between Version 21 and Version 22 of PluginDevelopmentGuide


Ignore:
Timestamp:
20.04.2013 23:25:42 (7 years ago)
Author:
jri
Comment:

Consuming a service

Legend:

Unmodified
Added
Removed
Modified
  • PluginDevelopmentGuide

    v21 v22  
    861861 
    862862You see, the plugin main class `TopicmapsPlugin` implements the plugin's service interface `TopicmapsService`. 
     863 
     864=== Consuming a service === 
     865 
     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. 
     867 
     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. 
     869 
     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. 
     871 
     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: `{"...", "...", ...}`. 
     873 
     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. 
     875 
     876As an example, see how the //Workspaces// plugin (part of the DeepaMehta Standard Distribution) consumes the //Facets// service: 
     877 
     878{{{ 
     879#!java 
     880package de.deepamehta.plugins.workspaces; 
     881 
     882import de.deepamehta.plugins.facets.service.FacetsService; 
     883 
     884import de.deepamehta.core.osgi.PluginActivator; 
     885import de.deepamehta.core.service.PluginService; 
     886import de.deepamehta.core.service.annotation.ConsumesService; 
     887 
     888 
     889 
     890public class WorkspacesPlugin extends PluginActivator { 
     891 
     892    private FacetsService facetsService; 
     893 
     894    // *** Hook Implementations *** 
     895 
     896    @Override 
     897    @ConsumesService("de.deepamehta.plugins.facets.service.FacetsService") 
     898    public void serviceArrived(PluginService service) { 
     899        facetsService = (FacetsService) service; 
     900    } 
     901 
     902    @Override 
     903    public void serviceGone(PluginService service) { 
     904        facetsService = null; 
     905    } 
     906}}} 
     907 
     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.