Changes between Version 21 and Version 22 of PluginDevelopmentGuide

Timestamp:

20.04.2013 23:25:42 (12 years ago)

Author:

jri

Comment:

Consuming a service

PluginDevelopmentGuide

@@ -861 +861 @@
 
 You see, the plugin main class `TopicmapsPlugin` implements the plugin's service interface `TopicmapsService`.
+
+=== 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.
+
+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.
+
+As an example, see how the //Workspaces// plugin (part of the DeepaMehta Standard Distribution) consumes the //Facets// service:
+
+{{{
+#!java
+package de.deepamehta.plugins.workspaces;
+
+import de.deepamehta.plugins.facets.service.FacetsService;
+
+import de.deepamehta.core.osgi.PluginActivator;
+import de.deepamehta.core.service.PluginService;
+import de.deepamehta.core.service.annotation.ConsumesService;
+
+
+
+public class WorkspacesPlugin extends PluginActivator {
+
+    private FacetsService facetsService;
+
+    // *** Hook Implementations ***
+
+    @Override
+    @ConsumesService("de.deepamehta.plugins.facets.service.FacetsService")
+    public void serviceArrived(PluginService service) {
+        facetsService = (FacetsService) service;
+    }
+
+    @Override
+    public void serviceGone(PluginService service) {
+        facetsService = null;
+    }
+}}}
+
+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.