Changes between Version 22 and Version 23 of PluginDevelopmentGuide

Timestamp:

21.04.2013 00:33:45 (12 years ago)

Author:

jri

Comment:

Consuming more than one service

PluginDevelopmentGuide

@@ -864 +864 @@
 === Consuming a service ===
 
-Your 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.
-
-Behind 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.
+Your 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. Through the service object your plugin can call all the service methods declared in the other's plugin service interface.
+
+Behind 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 at any time. Your plugin must deal with that. However, you as a plugin developer must not care about DeepaMehta's OSGi foundation. The DeepaMehta Core hides the details from you and provides an easy-to-use API for consuming plugin services.
 
 To 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.
 
-To 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: `{"...", "...", ...}`.
-
-The 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.
+To tell the DeepaMehta Core which plugin service your plugin wants to consume use the `@ConsumesService` annotation at the `serviceArrived` hook. State the fully qualified name (string) of the respective service interface as the annotation argument. To consume more than one service use the array notation: `{"...", "..."}`.
+
+The 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.
 
 As an example, see how the //Workspaces// plugin (part of the DeepaMehta Standard Distribution) consumes the //Facets// service:
@@ -906 +906 @@
 }}}
 
-You 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.
+You see the Workspaces plugin consumes just one plugin service: the //Facets// service. Its service interface is specified as the `@ConsumesService` argument. The `PluginService` object passed to the 2 hooks needs not being further investigated.
+
+In contrast lets see how it looks like when a plugin consumes more than one service. As an example here is an extraction of the //Geomaps// plugin (part of the DeepaMehta Standard Distribution):
+
+{{{
+#!java
+public class GeomapsPlugin extends PluginActivator {
+
+    private TopicmapsService topicmapsService;
+    private FacetsService facetsService;
+
+    // *** Hook Implementations ***
+
+    @Override
+    @ConsumesService({
+        "de.deepamehta.plugins.topicmaps.service.TopicmapsService",
+        "de.deepamehta.plugins.facets.service.FacetsService"
+    })
+    public void serviceArrived(PluginService service) {
+        if (service instanceof TopicmapsService) {
+            topicmapsService = (TopicmapsService) service;
+        } else if (service instanceof FacetsService) {
+            facetsService = (FacetsService) service;
+        }
+    }
+
+    @Override
+    public void serviceGone(PluginService service) {
+        if (service == topicmapsService) {
+            topicmapsService = null;
+        } else if (service == facetsService) {
+            facetsService = null;
+        }
+    }
+}}}
+
+You see the Geomaps plugin consumes 2 plugin services: the //Topicmaps// service and the //Facets// service. Both service interfaces are specified as the `@ConsumesService` argument. Note the array notation with the curly braces `{...}`. Note also the `if` statements in the `serviceArrived` and `serviceGone` hooks.